Product Documentation
ADC
14.1 - Current Release 13.1 13.0 12.1
View PDF

SSL offloading configuration

August 20, 2024
Contributed by: 
C C S

To configure SSL offloading, you must enable SSL processing on the Citrix ADC appliance. Configure an SSL based virtual server that will intercept SSL traffic, decrypt the traffic, and forward it to a service that is bound to the virtual server. To secure time-sensitive traffic, such as media streaming, you can configure a DTLS virtual server. To enable SSL offloading, you must import a valid certificate and key and bind the pair to the virtual server.

Enable SSL

To process SSL traffic, you must enable SSL processing. You can configure SSL based entities, such as virtual servers and services, without enabling SSL processing, but they do not work until SSL processing is enabled.

Enable SSL processing by using the CLI

At the command prompt, type:

enable ns feature ssl

show ns feature
<!--NeedCopy-->

Example:

enable ns feature SSL
 Done
show ns feature

        Feature                        Acronym              Status
        -------                        -------              ------
 1)     Web Logging                    WL                   OFF
 2)     Surge Protection               SP                   ON
 3)     Load Balancing                 LB                   ON
 .
 .
 .
 9)     SSL Offloading                 SSL                  ON
 .
 .
 .
 24)    NetScaler Push                 push                 OFF
 Done
<!--NeedCopy-->

Enable SSL processing by using the GUI

Navigate to System > Settings and, in the Modes and Features group, select Configure Basic Features, and select SSL Offloading.

Configure services

On the Citrix ADC appliance, a service represents a physical server or an application on a physical server. Once configured, services are in the disabled state until the appliance can reach the physical server on the network and monitor its status.

Add a service by using the CLI

At the command prompt, type the following commands to add a service and verify the configuration:

add service <name> (<IP> | <serverName>) <serviceType> <port>
show service <serviceName>
<!--NeedCopy-->

Example:

add service sslsvc 198.51.100.225 SSL 443

Done

sh ssl service sslsvc

            Advanced SSL configuration for Back-end SSL Service sslsvc:
            DH: DISABLED
            DH Private-Key Exponent Size Limit: DISABLED    Ephemeral RSA: DISABLED
            Session Reuse: ENABLED          Timeout: 300 seconds
            Cipher Redirect: DISABLED
            SSLv2 Redirect: DISABLED
            ClearText Port: 0
            Server Auth: DISABLED
            SSL Redirect: DISABLED
            Non FIPS Ciphers: DISABLED
            SNI: DISABLED
            OCSP Stapling: DISABLED
            SSLv2: DISABLED  SSLv3: ENABLED  TLSv1.0: ENABLED  TLSv1.1: ENABLED  TLSv1.2: ENABLED  TLSv1.3: DISABLED
            Send Close-Notify: YES
            Strict Sig-Digest Check: DISABLED
            Zero RTT Early Data: ???
            DHE Key Exchange With PSK: ???
            Tickets Per Authentication Context: ???

            ECC Curve: P_256, P_384, P_224, P_521

    1)      Cipher Name: DEFAULT_BACKEND
            Description: Default cipher list for Backend SSL session
     Done
<!--NeedCopy-->

Modify or remove a service by using the CLI

To modify a service, use the set service command, which is just like using the add service command, except that you enter the name of an existing service. To remove a service, use the rm service command, which accepts only the <name> argument.

Configure a service by using the GUI

Navigate to Traffic Management > Load Balancing > Services, create a service, and specify the protocol as SSL.

SSL virtual server configuration

Secure sessions require establishing a connection between the client and an SSL-based virtual server on the Citrix ADC appliance. The SSL virtual server intercepts SSL traffic, decrypts it and processes it before sending it to services that are bound to the virtual server.

Note: The SSL virtual server is marked as down on the Citrix ADC appliance until a valid certificate / key pair and at least one service are bound to it. An SSL based virtual server is a load balancing virtual server of protocol type SSL or SSL_TCP. The load balancing feature must be enabled on the Citrix ADC appliance.

Add an SSL-based virtual server by using the CLI

At the command prompt, type the following commands to create an SSL-based virtual server and verify the configuration:

add lb vserver <name> (serviceType) <IPAddress> <port>
show ssl vserver <name>
<!--NeedCopy-->

Example:

add lb vserver sslvs SSL 192.0.2.240 443
Done

sh ssl vserver sslvs

            Advanced SSL configuration for VServer sslvs:
            DH: DISABLED
            DH Private-Key Exponent Size Limit: DISABLED    Ephemeral RSA: ENABLED          Refresh Count: 0
            Session Reuse: ENABLED          Timeout: 120 seconds
            Cipher Redirect: DISABLED
            SSLv2 Redirect: DISABLED
            ClearText Port: 0
            Client Auth: DISABLED
            SSL Redirect: DISABLED
            Non FIPS Ciphers: DISABLED
            SNI: DISABLED
            OCSP Stapling: DISABLED
            HSTS: DISABLED
            HSTS IncludeSubDomains: NO
            HSTS Max-Age: 0
            SSLv2: DISABLED  SSLv3: ENABLED  TLSv1.0: ENABLED  TLSv1.1: ENABLED  TLSv1.2: ENABLED  TLSv1.3: DISABLED
            Push Encryption Trigger: Always
            Send Close-Notify: YES
            Strict Sig-Digest Check: DISABLED
            Zero RTT Early Data: DISABLED
            DHE Key Exchange With PSK: NO
            Tickets Per Authentication Context: 1
            ECC Curve: P_256, P_384, P_224, P_521

    1)      Cipher Name: DEFAULT
            Description: Default cipher list with encryption strength >= 128bit
     Done
<!--NeedCopy-->

Modify or remove an SSL-based virtual server by using the CLI

To modify the load balancing properties of an SSL virtual server, use the set lb vserver command, which is just like using the add lb vserver command, except that you enter the name of an existing virtual server. To modify the SSL properties of an SSL-based virtual server, use the set ssl vserver command. For more information, see the “SSL virtual server parameters” section later in this page.

To remove an SSL virtual server, use the rm lb vserver command, which accepts only the <name> argument.

Configure an SSL-based virtual server by using the GUI

Navigate to Traffic Management > Load Balancing > Virtual Servers, create a virtual server, and specify the protocol as SSL.

Bind services to the SSL virtual server

The ADC appliance forwards decrypted SSL data to servers in the network, when services representing these physical servers are bound to the virtual server that receives the SSL data.

Because the link between the Citrix ADC appliance and the physical server is typically secure, data transfer between the appliance and the physical server can be unencrypted. However, you can provide end-to end-encryption by encrypting data transfer between the appliance and the server. For details, see Configure SSL offloading with end-to-end encryption.

Note: Enable the load balancing feature on the Citrix ADC appliance before you bind services to the SSL based virtual server.

Bind a service to a virtual server by using the CLI

At the command prompt, type the following commands to bind the service to the virtual server and verify the configuration:

bind lb vserver <name> <serviceName>
show lb vserver <name>
<!--NeedCopy-->

Example:

bind lb vserver sslvs sslsvc
     Done

sh lb vserver sslvs

            sslvs (192.0.2.240:443) - SSL       Type: ADDRESS
            State: DOWN[Certkey not bound]
            Last state change was at Wed May  2 11:43:04 2018
            Time since last state change: 0 days, 00:13:21.150
            Effective State: DOWN
            Client Idle Timeout: 180 sec
            Down state flush: ENABLED
            Disable Primary Vserver On Down : DISABLED
            Appflow logging: ENABLED
            No. of Bound Services :  1 (Total)       0 (Active)
            Configured Method: LEASTCONNECTION      BackupMethod: ROUNDROBIN
            Mode: IP
            Persistence: NONE
            Vserver IP and Port insertion: OFF
            Push: DISABLED  Push VServer:
            Push Multi Clients: NO
            Push Label Rule: none
            L2Conn: OFF
            Skip Persistency: None
            Listen Policy: NONE
            IcmpResponse: PASSIVE
            RHIstate: PASSIVE
            New Service Startup Request Rate: 0 PER_SECOND, Increment Interval: 0
            Mac mode Retain Vlan: DISABLED
            DBS_LB: DISABLED
            Process Local: DISABLE
            Traffic Domain: 0
            TROFS Persistence honored: ENABLED
            Retain Connections on Cluster: NO
    1) sslsvc (198.51.100.225: 443) - SSL State: DOWN       Weight: 1
     Done
<!--NeedCopy-->

Unbind a service from a virtual server by using the CLI

At the command prompt, type the following command:

unbind lb vserver <name> <serviceName>
<!--NeedCopy-->

Example:

unbind lb vserver sslvs sslsvc
     Done
<!--NeedCopy-->

Bind a service to a virtual server by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. Open a virtual server, and click in the Services section to bind a service to the virtual server.

Configure an SNI virtual server for secure hosting of multiple sites

Virtual hosting is used by web servers to host more than one domain name with the same IP address. The appliance supports hosting of multiple secure domains by offloading SSL processing from the Web servers using transparent SSL services or virtual server-based SSL offloading. However, when multiple websites are hosted on the same virtual server, the SSL handshake is completed before the expected host name is sent to the virtual server. As a result, the appliance cannot determine which certificate to present to the client after a connection is established. This problem is resolved by enabling Server Name Indication (SNI) on the virtual server. SNI is a Transport Layer Security (TLS) extension used by the client to provide the host name during handshake initiation. The Citrix ADC appliance compares this host name to the common name and, if it does not match, compares it to the subject alternative name (SAN). If the name matches, the appliance presents the corresponding certificate to the client.

A wildcard SSL Certificate helps enable SSL encryption on multiple subdomains if the domains are controlled by the same organization and share the second-level domain name. For example, a wildcard certificate issued to a sports network using the common name “*.sports.net” can be used to secure domains, such as “login.sports.net” and “help.sports.net” but not “login.ftp.sports.net.”

Notes:

  • On a Citrix ADC appliance, only domain name, URL, and email ID DNS entries in the SAN field are compared.

  • If an existing certificate-key pair (for example, certkey A) is bound to an SSL virtual server, and a second certificate-key pair (for example, certkey B) is added using SNI and bound to the same virtual server, certkey A must also be configured as -SNICert. If a Client Hello message includes an SNI extension with the domain name of certkey A and the preceding configuration is not in place, TLS connections to the domains in (certkey A) do not work.

You can bind multiple server certificates to a single SSL virtual server or transparent service using the -SNICert option. These certificates are issued by the virtual server or service if SNI is enabled on the virtual server or service. You can enable SNI at any time.

Bind multiple server certificates to a single SSL virtual server by using the CLI

At the command prompt, type the following commands to configure SNI and verify the configuration:

set ssl vserver <vServerName>@ [-SNIEnable ( ENABLED | DISABLED )]

bind ssl vserver <vServerName>@ -certkeyName <string> -SNICert

show ssl vserver <vServerName>
<!--NeedCopy-->

To bind multiple server certificates to a transparent service by using the CLI, replace vserver with service and vservername with servicename in the preceding commands.

Note: Create the SSL service with the -clearTextPort 80 option.

Bind multiple server certificates to a single SSL virtual server by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. Open an SSL virtual server and, in Certificates, click Server Certificate.
  3. Add a certificate or select a certificate from the list, and select Server Certificate for SNI.
  4. In Advanced Settings, click SSL Parameters.
  5. Select SNI Enable.

Support for SNI on the back-end service

Note: SNI is not supported on a DTLS back-end service.

The Citrix ADC appliance supports Server Name Indication (SNI) at the back end. That is, the common name is sent as the server name in the client hello to the back-end server for successful completion of the handshake. In addition to helping meet federal system integrator customer security requirements, this enhancement provides the advantage of using only one port instead of opening hundreds of different IP addresses and ports on a firewall.

Federal system integrator customer security requirements include support for Active Directory Federation Services (ADFS) 3.0 in 2012R2 and WAP servers. This requires supporting SNI at the back end on a Citrix ADC appliance.

Note:

For SNI to work, the server name in the client hello must match the host name configured on the back-end service that is bound to an SSL virtual server. For example, if the host name of the back end server is www.mail.example.com, the SNI-enabled back-end service must be configured with the server name as https://www.mail.example.com, and this host name must match the server name in the client hello.

Configure SNI on the back-end service by using the CLI

At the command prompt, type:

add service <name>  <IP>  <serviceType>  <port>

add lb vserver <name>  <IPAddress> <serviceType>  <port>

bind lb vserver <name> <serviceName>

set ssl service <serviceName> -SNIEnable ENABLED -commonName <string>
<!--NeedCopy-->

Example:

    add service service_ssl 198.51.100.100 SSL 443

    add lb vserver ssl-vs 203.0.113.200 SSL 443

    bind lb vserver ssl-vs service_ssl

    set ssl service service_ssl -SNIEnable ENABLED –commonName www.example.com
<!--NeedCopy-->

Configure SNI on the back-end service by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Services.
  2. Select an SSL service, and in Advanced Settings, select SSL Parameters.
  3. Select SNI Enable.

Bind a secure monitor to an SNI-enabled back-end service

You can also bind secure monitors of type HTTP-ECV or TCP-ECV to the back-end services that support SNI. To do so, the custom header in the monitor must be set to the server name that is sent as the SNI extension in the client hello.

Configure and bind a secure monitor to an SNI-enabled back-end service by using the CLI

At the command prompt, type:

add lb monitor <monitorName> <type>

set lb monitor <monitorName> <type> -customHeaders <string>

bind service <name> -monitorName <string>
<!--NeedCopy-->

Example:

add monitor https-ecv-mon http-ecv
    Done
set monitor https-ecv-mon HTTP-ECV -customHeaders "Host: example.com\r\n"
    Done
bind service ssl_service –monitorName https-ecv
<!--NeedCopy-->

Configure and bind a secure monitor to an SNI-enabled back-end service by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Monitor.
  2. Add a monitor of type HTTP-ECV or TCP-ECV, and specify a Custom Header.
  3. Click Create.
  4. Navigate to Traffic Management > Load Balancing > Services.
  5. Select an SSL service and click Edit.
  6. In Monitors, click Add Binding, select the monitor created in step 3, and click Bind.

Add or update a certificate-key pair

Caution: If while adding a certificate-key pair, you add a certificate file with the same name as an existing certificate file but with different content, the original certificate file is overwritten with no warning. This action might cause issues after the appliance is restarted because the original certificate file is no longer available in the /nsconfig/ssl directory.

Note:

If you don’t have an existing certificate and key, see Create a certificate.

To create an ECDSA certificate-key pair, click Create an ECDSA certificate-key pair.

From release 12.1 build 50.x, the password of the private key used while adding an SSL certificate-key pair is now saved using a unique encryption key for each Citrix ADC appliance.

For any SSL transaction, the server needs a valid certificate and the corresponding private and public key pair. The SSL data is encrypted with the server’s public key, which is available through the server’s certificate. Decryption requires the corresponding private key.

Because the Citrix ADC appliance offloads SSL transactions from the server, the server’s certificate and private key must be present on the appliance, and the certificate must be paired with its corresponding private key. This certificate-key pair must then be bound to the virtual server that processes the SSL transactions.

Note: From release 11.0, the default certificate on a Citrix ADC appliance is 2048 bits. In earlier builds, the default certificate was 512 bits or 1024 bits. After upgrading to release 11.0, you must delete all your old certificate-key pairs starting with “ns-“, and then restart the appliance to automatically generate a 2048-bit default certificate.

Both the certificate and the key must be in local storage on the Citrix ADC appliance before they can be added to the appliance. If your certificate or key file is not on the appliance, upload it to the appliance before you create the pair.

Important: Certificates and keys are stored in the /nsconfig/ssl directory by default. If your certificates or keys are stored in any other location, you must provide the absolute path to the files on the Citrix ADC appliance. The Citrix ADC FIPS appliances do not support external keys (non-FIPS keys). On a FIPS appliance, you cannot load keys from a local storage device such as a hard disk or flash memory. The FIPS keys must be present in the Hardware Security Module (HSM) of the appliance.

On a Citrix ADC MPX appliance and a Citrix ADC FIPS appliance, only RSA private keys are supported. On a VPX virtual appliance, both RSA and DSA private keys are supported. On an SDX appliance if SSL chips are assigned to an instance, then only RSA private keys are supported. However, if SSL chips are not assigned to an instance, then both RSA and DSA private keys are supported. In all the cases, you can bind a CA certificate with either RSA or DSA keys.

Set the notification period and enable the expiry monitor to issue a prompt before the certificate expires.

The Citrix ADC appliance supports the following input formats of the certificate and the private-key files:

  • PEM - Privacy Enhanced Mail
  • DER - Distinguished Encoding Rule
  • PFX - Personal Information Exchange

The software automatically detects the format. Therefore, you are no longer required to specify the format in the inform parameter. If you do specify the format (correct or incorrect), the software ignores it. The format of the certificate and the key file must be the same.

Note: A certificate must be signed by using one of the following hash algorithms:

  • MD5
  • SHA-1
  • SHA-224
  • SHA-256
  • SHA-384
  • SHA-512

An MPX appliance supports certificates of 512 or more bits, up to the following sizes:

  • 4096-bit server certificate on the virtual server
  • 4096-bit client certificate on the service
  • 4096-bit CA certificate (includes intermediate and root certificates)
  • 4096-bit certificate on the back-end server
  • 4096-bit client certificate (if client authentication is enabled on the virtual server)

A VPX virtual appliance supports certificates of 512 or more bits, up to the following sizes:

  • 4096-bit server certificate on the virtual server
  • 4096-bit client certificate on the service
  • 4096-bit CA certificate (includes intermediate and root certificates)
  • 4096-bit certificate on the back-end server
  • 2048-bit client certificate (if client authentication is enabled on the virtual server)

Note

A Citrix ADC SDX appliance supports certificates of 512 or more bits. Each Citrix ADC VPX instance hosted on the appliance supports the certificate sizes listed earlier for a VPX virtual appliance. However, if an SSL chip is assigned to an instance, that instance supports the certificate sizes supported by an MPX appliance.

Add a certificate-key pair by using the CLI

At the command prompt, type the following commands to add a certificate-key pair and verify the configuration:

add ssl certKey <certkeyName> -cert <string>[(-key <string> [-password]) | -fipsKey <string>] [-inform ( DER | PEM )] [<passplain>] [-expiryMonitor ( ENABLED | DISABLED ) [-notificationPeriod <positive_integer>]]

show ssl certKey [<certkeyName>]
<!--NeedCopy-->

Example:

add ssl certKey sslckey -cert server_cert.pem -key server_key.pem -password ssl -expiryMonitor ENABLED -notificationPeriod 30
 Done
Note: For FIPS appliances, replace -key with -fipskey

show ssl certKey sslckey
        Name: sslckey           Status: Valid,   Days to expiration:8418
        Version: 3
        Serial Number: 01
        Signature Algorithm: md5WithRSAEncryption
        Issuer:  C=US,ST=SJ,L=SJ,O=NS,OU=NSSSL,CN=www.root.com
        Validity
                Not Before: Jul 15 02:25:01 2005 GMT
                Not After : Nov 30 02:25:01 2032 GMT
        Subject:  C=US,ST=SJ,L=SJ,O=NS,OU=NSSSL,CN=www.server.com
        Public Key Algorithm: rsaEncryption
        Public Key size: 2048
 Done
<!--NeedCopy-->

Update or remove a certificate-key pair by using the CLI

To modify the expiry monitor or notification period in a certificate-key pair, use the set ssl certkey command. To replace the certificate or key in a certificate-key pair, use the update ssl certkey command. The update ssl certkey command has an extra parameter for overriding the domain check. For both commands, enter the name of an existing certificate-key pair. To remove an SSL certificate-key pair, use the rm ssl certkey command, which accepts only the <certkeyName> argument.

Example:

set ssl certKey <certkeyName> [-expiryMonitor ( ENABLED | DISABLED )
       [-notificationPeriod <positive_integer>]]

update ssl certKey <certkeyName> [-cert <string> [-password]] [-key
       <string> | -fipsKey <string>] [-inform <inform>] [-noDomainCheck]
<!--NeedCopy-->

Add or update a certificate-key pair by using the GUI

Navigate to Traffic Management > SSL > Certificates, and configure a certificate-key pair.

Bind the certificate-key pair to the SSL virtual server

An SSL certificate is an integral element of the SSL encryption and decryption process. The certificate is used during an SSL handshake to establish the identity of the SSL server.

The certificate being used for processing SSL transactions must be bound to the virtual server that receives the SSL data. If you have multiple virtual servers receiving SSL data, a valid certificate-key pair must be bound to each of them.

You can use a valid, existing SSL certificate that you have uploaded to the Citrix ADC appliance. As an alternative for testing purposes, you can create your own SSL certificate on the appliance. Intermediate certificates created by using a FIPS key on the appliance cannot be bound to an SSL virtual server.

As a part of the SSL handshake, in the certificate request message during client authentication, the server lists the distinguished names (DNs) of all the certificate authorities (CAs) bound to the server from which it accepts a client certificate. If you do not want the DN name of a specific CA certificate to be sent to the SSL client, set the skipCA flag. This setting indicates that the particular CA certificate’s distinguished name must not be sent to the SSL client.

For details on how to create your own certificate, see Managing Certificates.

Note: Citrix recommends that you use only valid SSL certificates issued by a trusted certificate authority.

Bind an SSL certificate-key pair to a virtual server by using the CLI

At the command prompt, type the following commands to bind an SSL certificate-key pair to a virtual server and verify the configuration:

-  bind ssl vserver <vServerName> -certkeyName <certificate-KeyPairName> -CA -skipCAName
-  show ssl vserver <vServerName>
<!--NeedCopy-->

Example:

bind ssl vs vs1 -certkeyName cert2 -CA -skipCAName
 Done
sh ssl vs vs1

 Advanced SSL configuration for VServer vs1:

 DH: DISABLED

 Ephemeral RSA: ENABLED Refresh Count: 0

 Session Reuse: ENABLED Timeout: 120 seconds

 Cipher Redirect: DISABLED

 SSLv2 Redirect: DISABLED

 ClearText Port: 0

 Client Auth: DISABLED

 SSL Redirect: DISABLED

 Non FIPS Ciphers: DISABLED

 SNI: DISABLED

 OCSP Stapling: DISABLED

 HSTS: DISABLED

 IncludeSubDomains: NO

 HSTS Max-Age: 0

 SSLv2: DISABLED SSLv3: ENABLED  TLSv1.0: ENABLED  TLSv1.1: DISABLED  TLSv1.2: DISABLED

 Push Encryption Trigger: Always

 Send Close-Notify: YES

 Strict Sig-Digest Check: DISABLED

ECC Curve: P_256, P_384, P_224, P_521

 1) CertKey Name: cert1 CA Certificate OCSPCheck: Optional CA_Name Sent
 2) CertKey Name: cert2 CA Certificate OCSPCheck: Optional CA_Name Skipped
 1) Cipher Name: DEFAULT

Description: Default cipher list with encryption strength >= 128bit
Done
<!--NeedCopy-->

Unbind an SSL certificate-key pair from a virtual server by using the CLI

If you try to unbind a certificate-key pair from a virtual server by using the unbind ssl certKey <certkeyName> command, an error message appears because the syntax of the command has changed. At the command prompt, type the following command:

unbind ssl vserver <vServerName> -certkeyName <string>
<!--NeedCopy-->

Example:

unbind ssl vserver vssl -certkeyName sslckey
<!--NeedCopy-->

Bind an SSL certificate-key pair to a virtual server by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
  2. Open an SSL virtual server and, in Advanced Settings, click SSL Certificate.
  3. Bind a server certificate or CA certificate to the virtual server. To add a server certificate as an SNI certificate, select Server Certificate for SNI.

SSL virtual server parameters

You can set the advanced SSL configuration for an SSL virtual server. Many of these parameters can also be set in an SSL profile. For information about the parameters that can be set in an SSL profile, see SSL profile parameters.

Set SSL virtual server parameters by using the CLI

At the command prompt, type:

set ssl vserver <vServerName>@ [-clearTextPort <port>] [-dh ( ENABLED |DISABLED ) -dhFile <string>] [-dhCount <positive_integer>][-dhKeyExpSizeLimit ( ENABLED | DISABLED )] [-eRSA ( ENABLED | DISABLED) [-eRSACount <positive_integer>]] [-sessReuse ( ENABLED | DISABLED )[-sessTimeout <positive_integer>]] [-cipherRedirect ( ENABLED | DISABLED ) [-cipherURL <URL>]] [-sslv2Redirect ( ENABLED | DISABLED )[-sslv2URL <URL>]] [-clientAuth ( ENABLED | DISABLED ) [-clientCert ( Mandatory | Optional )]] [-sslRedirect ( ENABLED | DISABLED )][-redirectPortRewrite ( ENABLED | DISABLED )] [-ssl2 ( ENABLED | DISABLED )] [-ssl3 ( ENABLED | DISABLED )] [-tls1 ( ENABLED | DISABLED )] [-tls11 ( ENABLED | DISABLED )] [-tls12 ( ENABLED | DISABLED )][-tls13 ( ENABLED | DISABLED )] [-SNIEnable ( ENABLED | DISABLED )][-ocspStapling ( ENABLED | DISABLED )] [-pushEncTrigger <pushEncTrigger>] [-sendCloseNotify ( YES | NO )] [-dtlsProfileName <string>] [-sslProfile <string>] [-HSTS ( ENABLED | DISABLED )][-maxage <positive_integer>] [-IncludeSubdomains ( YES | NO )][-strictSigDigestCheck ( ENABLED | DISABLED )] [-zeroRttEarlyData (ENABLED | DISABLED )] [-tls13SessionTicketsPerAuthContext <positive_integer>] [-dheKeyExchangeWithPsk ( YES | NO )]
<!--NeedCopy-->

Diffie-Hellman (DH) parameters

If you are using ciphers on the appliance that require a DH key exchange to set up the SSL transaction, enable DH key exchange on the appliance and configure other settings based on your network.

To list the ciphers for which DH parameters must be set by using the CLI, type: sh cipher DH.

To list the ciphers for which DH parameters must be set by using the configuration utility, navigate to Traffic Management > SSL > Cipher Groups, and double-click DH.

For details on how to enable DH key exchange, see Generate a Diffie-Hellman (DH) key.

Configure DH parameters by using the CLI

At the command prompt, type the following commands to configure DH parameters and verify the configuration:

-  `set ssl vserver <vserverName> -dh <Option> -dhCount <RefreshCountValue> -filepath <string>
-  show ssl vserver <vServerName>`
<!--NeedCopy-->

Example:

set ssl vserver vs-server -dh ENABLED  -dhFile /nsconfig/ssl/ns-server.cert -dhCount 1000
Done

show ssl vserver vs-server

            Advanced SSL configuration for VServer vs-server:
            DH: ENABLED
            Ephemeral RSA: ENABLED          Refresh Count: 1000
            Session Reuse: ENABLED          Timeout: 120 seconds
            Cipher Redirect: DISABLED
            SSLv2 Redirect: DISABLED
            ClearText Port: 0
            Client Auth: DISABLED
            SSL Redirect: DISABLED
            Non FIPS Ciphers: DISABLED
            SNI: DISABLED
            OCSP Stapling: DISABLED
            HSTS: DISABLED
            HSTS IncludeSubDomains: NO
            HSTS Max-Age: 0
            SSLv2: DISABLED SSLv3: ENABLED  TLSv1.0: ENABLED TLSv1.2: ENABLED  TLSv1.2: ENABLED

    1)      Cipher Name: DEFAULT
            Description: Predefined Cipher Alias
Done
<!--NeedCopy-->

Configure DH Parameters by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select Enable DH Param, and specify a refresh count and file path.

Ephemeral RSA

Ephemeral RSA allows export clients to communicate with the secure server even if the server certificate does not support export clients (1024-bit certificate). If you want to prevent export clients from accessing the secure web object or resource, you need to disable ephemeral RSA key exchange.

By default, this feature is enabled on the Citrix ADC appliance, with the refresh count set to zero (infinite use).

Note:

The ephemeral RSA key is automatically generated when you bind an export cipher to an SSL or TCP-based SSL virtual server or service. When you remove the export cipher, the eRSA key is not deleted but reused later when another export cipher is bound to an SSL or TCP-based SSL virtual server or service. The eRSA key is deleted when the system restarts.

Configure Ephemeral RSA by using the CLI

At the command prompt, type the following commands to configure ephemeral RSA and verify the configuration:

set ssl vserver <vServerName> -eRSA (enabled | disabled) -eRSACount <positive_integer>
show ssl vserver <vServerName>
<!--NeedCopy-->

Example:

set ssl vserver vs-server -eRSA ENABLED -eRSACount 1000
 Done

show ssl vserver vs-server

        Advanced SSL configuration for VServer vs-server:
        DH: DISABLED
        Ephemeral RSA: ENABLED          Refresh Count: 1000
        Session Reuse: ENABLED          Timeout: 120 seconds
        Cipher Redirect: DISABLED
        SSLv2 Redirect: DISABLED
        ClearText Port: 0
        Client Auth: DISABLED
        SSL Redirect: DISABLED
        Non FIPS Ciphers: DISABLED
        SNI: DISABLED
        OCSP Stapling: DISABLED
        HSTS: DISABLED
        HSTS IncludeSubDomains: NO
        HSTS Max-Age: 0
        SSLv2: DISABLED SSLv3: ENABLED  TLSv1.0: ENABLED TLSv1.2: ENABLED  TLSv1.2: ENABLED

1)      Cipher Name: DEFAULT
        Description: Predefined Cipher Alias
 Done
<!--NeedCopy-->

Configure Ephemeral RSA by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select Enable Ephemeral RSA, and specify a refresh count.

Session reuse

For SSL transactions, establishing the initial SSL handshake requires CPU-intensive public key encryption operations. Most handshake operations are associated with the exchange of the SSL session key (client key exchange message). When a client session is idle for some time and is then resumed, the SSL handshake is typically conducted all over again. With session reuse enabled, session key exchange is avoided for session resumption requests received from the client.

Session reuse is enabled on the Citrix ADC appliance by default. Enabling this feature reduces server load, improves response time, and increases the number of SSL transactions per second (TPS) that the server can support.

Configure session reuse by using the CLI

At the command prompt, type the following commands to configure session reuse and verify the configuration:

set ssl vserver <vServerName> -sessReuse ( ENABLED | DISABLED ) -sessTimeout <positive_integer>
show ssl vserver <vServerName>
<!--NeedCopy-->

Example:

set ssl vserver vs-ssl -sessreuse enabled -sesstimeout 600
 Done

show ssl vserver vs-ssl

        Advanced SSL configuration for VServer vs-ssl:
        DH: DISABLED
        Ephemeral RSA: ENABLED          Refresh Count: 1000
        Session Reuse: ENABLED          Timeout: 600 seconds
        Cipher Redirect: DISABLED
        SSLv2 Redirect: DISABLED
        ClearText Port: 0
        Client Auth: DISABLED
        SSL Redirect: DISABLED
        Non FIPS Ciphers: DISABLED
        SNI: DISABLED
        OCSP Stapling: DISABLED
        HSTS: DISABLED
        HSTS IncludeSubDomains: NO
        HSTS Max-Age: 0
        SSLv2: DISABLED SSLv3: ENABLED  TLSv1.0: ENABLED TLSv1.2: ENABLED  TLSv1.2: ENABLED

1)      CertKey Name: Auth-Cert-1       Server Certificate

1)      Cipher Name: DEFAULT
        Description: Predefined Cipher Alias
 Done
<!--NeedCopy-->

Configure session reuse by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select Enable Session Reuse, and specify a time for which to keep the session active.

SSL protocol settings

The Citrix ADC appliance supports the SSLv3, TLSv1, TLSv1.1, and TLSv1.2 protocols. These protocols can be set on the appliance as required by your deployment and the type of clients that connect to the appliance.

TLS protocol versions 1.0, 1.1, and 1.2 are more secure than older versions of the TLS/SSL protocol. However, to support legacy systems, many TLS implementations maintain backward compatibility with the SSLv3 protocol. In an SSL handshake, the highest protocol version common to the client and the SSL virtual server configured on the Citrix ADC appliance is used.

In the first handshake attempt, a TLS client offers the highest protocol version that it supports. If the handshake fails, the client offers a lower protocol version. For example, if a handshake with TLS version 1.1 is not successful, the client attempts to renegotiate by offering the TLSv1.0 protocol. If that attempt is unsuccessful, the client reattempts with the SSLv3 protocol. A “man in the middle” (MITM) attacker can break the initial handshake and trigger renegotiation with the SSLv3 protocol, and then exploit a vulnerability in SSLv3. To mitigate such attacks, you can disable SSLv3 or not allow renegotiation using a downgraded protocol. However, this approach might not be practical if your deployment includes legacy systems. An alternative is to recognize a signaling cipher suite value (TLS_FALLBACK_SCSV) in the client request.

A TLS_FALLBACK_SCSV value in a client hello message indicates to the virtual server that the client has previously attempted to connect with a higher protocol version and that the current request is a fallback. If the virtual server detects this value, and it supports a version higher than the one indicated by the client, it rejects the connection with a fatal alert. If a TLS_FALLBACK_SCSV is not included in the client hello message, or if the protocol version in the client hello is the highest protocol version supported by the virtual server, the handshake succeeds.

Configure SSL protocol support by using the CLI

At the command prompt, type the following commands to configure SSL protocol support and verify the configuration:

set ssl vserver <vServerName> -ssl2 ( ENABLED | DISABLED ) -ssl3 ( ENABLED | DISABLED ) -tls1 ( ENABLED | DISABLED ) -tls11 ( ENABLED | DISABLED ) -tls12 ( ENABLED | DISABLED )

show ssl vserver <vServerName>
<!--NeedCopy-->

Example:

set ssl vserver vs-ssl -tls11 ENABLED -tls12 ENABLED
Done

sh ssl vs vs-ssl

        Advanced SSL configuration for VServer vs-ssl:
            DH: DISABLED
            Ephemeral RSA: ENABLED                            Refresh Count: 0
            Session Reuse: ENABLED                              Timeout: 120 seconds
            Cipher Redirect: DISABLED
            SSLv2 Redirect: DISABLED
            ClearText Port: 0
            Client Auth: DISABLED
            SSL Redirect: DISABLED
            Non FIPS Ciphers: DISABLED
            SNI: DISABLED
            SSLv2: DISABLED        SSLv3: ENABLED    TLSv1.0: ENABLED  TLSv1.1: ENABLED  TLSv1.2: ENABLED
            Push Encryption Trigger: Always
            Send Close-Notify: YES
            1 bound certificate:

    1)      CertKey Name: mycert  Server Certificate
            1 configured cipher:

    1)      Cipher Name: DEFAULT
            Description: Predefined Cipher Alias

Done
<!--NeedCopy-->

Configure SSL protocol support by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select a protocol to enable.

Close-notify

A close-notify is a secure message that indicates the end of SSL data transmission. A close-notify setting is required at the global level. This setting applies to all virtual servers, services, and service groups. For information about the global setting, see the Global SSL parameters section later in this page.

In addition to the global setting, you can set the close-notify parameter at the virtual server, service, or service group level. You therefore have the flexibility of setting the parameter for one entity and unsetting it for another entity. However, make sure that you set this parameter at the global level. Otherwise, the setting at the entity level does not apply.

Configure the close-notify parameter at the entity level by using the CLI

At the command prompt, type any of the following commands to configure the close-notify parameter and verify the configuration:

  1. To configure the close-notify parameter at the virtual server level, type:
set ssl vserver <vServerName> -sendCloseNotify ( YES | NO )
show ssl vserver <vServerName>
<!--NeedCopy-->
  1. To configure the close-notify parameter at the service level, type:
set ssl service <serviceName> -sendCloseNotify ( YES | NO )
show ssl service <serviceName>
<!--NeedCopy-->
  1. To configure the close-notify parameter at the service group level, type:
set ssl serviceGroup <serviceGroupName> -sendCloseNotify ( YES | NO )
show ssl serviceGroup <serviceGroupName>
<!--NeedCopy-->

Example:

set ssl vserver sslvsvr -sendCloseNotify YES

Done
<!--NeedCopy-->

Configure a close-notify parameter at the entity level by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
  2. In the SSL Parameters section, select Send Close-Notify.

Global SSL parameters

Advanced customization of your SSL configuration addresses specific issues. You can use the set ssl parameter command or the configuration utility to specify the following:

  • Quantum size to be used for SSL transactions.
  • CRL memory size.
  • OCSP cache size.
  • Deny SSL renegotiation.
  • Set the PUSH flag for decrypted, encrypted, or all records.
  • Drop requests if the client initiates the handshake for one domain and sends an HTTP request for another domain.
  • Set the time after which encryption is triggered. Note: The time that you specify applies only if you use the set ssl vserver command or the configuration utility to set timer-based encryption.

Configure global SSL parameters by using the CLI

At the command prompt, type the following commands to configure advanced SSL settings and verify the configuration:

set ssl parameter [-quantumSize <quantumSize>] [-crlMemorySizeMB <positive_integer>] [-strictCAChecks (YES | NO)] [-sslTriggerTimeout <positive_integer>] [-sendCloseNotify (YES | NO)] [-encryptTriggerPktCount <positive_integer>] [-denySSLReneg <denySSLReneg>] [-insertionEncoding (Unicode|UTF-8)] [-ocspCacheSize <positive_integer>][- pushFlag <positive_integer>] [- dropReqWithNoHostHeader (YES | NO)] [-pushEncTriggerTimeout <positive_integer>]
show ssl parameter
<!--NeedCopy-->

Example:

set ssl parameter -quantumSize 8 -crlMemorySizeMB 256 -strictCAChecks no -sslt
iggerTimeout 100 -sendClosenotify no -encryptTriggerPktCount 45 -denySSLReneg no
-insertionEncoding unicode -ocspCacheSize 10 -pushFlag 3 -dropReqWithNoHostHeader YES  -pushEncTriggerTimeout 100 ms
 Done

show ssl parameter
Advanced SSL Parameters
-----------------------
        SSL quantum size:               8 kB
        Max CRL memory size:            256 MB
        Strict CA checks:               NO
        Encryption trigger timeout      100 mS
        Send Close-Notify               NO
        Encryption trigger packet count:        45
        Deny SSL Renegotiation          NO
        Subject/Issuer Name Insertion Format:   Unicode
        OCSP cache size:        10 MB
           Push flag:      0x3 (On every decrypted and encrypted record)
                                Strict Host Header check for SNI enabled SSL sessions:          YES
                                 PUSH encryption trigger timeout 100 ms
 Done
<!--NeedCopy-->

Configure global SSL parameters by using the GUI

Navigate to Traffic Management > SSL and, in the Settings group, select Change advanced SSL settings.

PUSH flag based encryption trigger mechanism

The encryption trigger mechanism that is based on the PSH TCP flag now enables you to do the following:

  • Merge consecutive packets in which the PSH flag is set into a single SSL record, or ignore the PSH flag.
  • Perform timer-based encryption, in which the time-out value is set globally by using the set ssl parameter -pushEncTriggerTimeout <positive_integer> command.

Configure PUSH flag-based encryption by using the CLI

At the command prompt, type the following commands to configure PUSH flag-based encryption and verify the configuration:

set ssl vserver <vServerName> [-pushEncTrigger <pushEncTrigger>]

show ssl vserver
<!--NeedCopy-->

Example:

set ssl vserver vserver1 -pushEncTrigger always

Done

sh ssl vserver vserver1

            Advanced SSL configuration for VServer vserver1:
            DH: DISABLED
            DH Private-Key Exponent Size Limit: DISABLED    Ephemeral RSA: ENABLED                                                                             Refresh Count: 0
            Session Reuse: ENABLED          Timeout: 120 seconds
            Cipher Redirect: DISABLED
            SSLv2 Redirect: DISABLED
            ClearText Port: 0
            Client Auth: DISABLED
            SSL Redirect: DISABLED
            Non FIPS Ciphers: DISABLED
            SNI: DISABLED
            OCSP Stapling: DISABLED
            HSTS: DISABLED
            HSTS IncludeSubDomains: NO
            HSTS Max-Age: 0
            SSLv2: DISABLED  SSLv3: ENABLED  TLSv1.0: ENABLED  TLSv1.1: ENABLED  TLSv1.2: ENABLED  TLSv1.3: DISABLED
            Push Encryption Trigger: Always
            Send Close-Notify: YES
            Strict Sig-Digest Check: DISABLED
            Zero RTT Early Data: DISABLED
            DHE Key Exchange With PSK: NO
            Tickets Per Authentication Context: 1
            ECC Curve: P_256, P_384, P_224, P_521

    1)      Cipher Name: DEFAULT
            Description: Default cipher list with encryption strength >= 128bit
Done
<!--NeedCopy-->

Configure PUSH flag-based encryption by using the GUI

  1. Navigate to Traffic Management > Load Balancing > Virtual servers and open an SSL virtual server.
  2. In the SSL Parameters section, from the PUSH Encryption Trigger list, select a value.

Support for TLS1.2 signature hash algorithm

The Citrix ADC appliance is completely TLS1.2 signature hash extension compliant.

In an SSL handshake, a client sends a list of supported signature hash (sighash) algorithms. The client uses the “signature_algorithms” extension to indicate to the server which sighash algorithm pairs might be used in the SSL handshake messages (SKE and CCV). The “extension_data” field of this extension contains a “supported_signature_algorithms” value in the Client Hello message. The SSL handshake proceeds if the server supports one of these sighash algorithms. If the server does not support any of these algorithms, the connection is dropped.

Similarly, if the server requests a client certificate for client authentication, the Certificate Request message contains a “supported_signature_algorithms” value. The client certificate is selected based on this sighash algorithm.

Note:

The Citrix ADC appliance acts as a server to a client and as a client to the back-end server.

Previously, the appliance supported only RSA-SHA1 and RSA-SHA256 on the front end, and RSA-MD5, RSA-SHA1, and RSA-SHA256 on the back end. In addition, the VPX appliance supported DSA-SHA1 on the front end and back end.

The MPX/SDX/VPX appliance supports the following sighash combinations. On an SDX appliance, if an SSL chip is assigned to a VPX instance, the cipher support of an MPX appliance applies. Otherwise, the normal cipher support of a VPX instance applies.

  • On a VPX instance:
    • RSA-MD5
    • RSA-SHA1
    • RSA-SHA224
    • RSA-SHA256
    • RSA-SHA384
    • RSA-SHA512
    • DSA-SHA1
    • DSA-SHA224
    • DSA-SHA256
    • DSA-SHA384
    • DSA-SHA512
  • On an MPX/SDX appliance with N3 chips:
    • RSA-MD5
    • RSA-SHA1
    • RSA-SHA224
    • RSA-SHA256
    • RSA-SHA384
    • RSA-SHA512
    • ECDSA-SHA1
    • ECDSA-SHA224
    • ECDSA-SHA256
    • ECDSA-SHA384
    • ECDSA-SHA512
  • On an MPX/SDX appliance without N3 chips:
    • RSA-MD5
    • RSA-SHA1
    • RSA-SHA224
    • RSA-SHA256
    • RSA-SHA384
    • RSA-SHA512

By default, all the sighash algorithms are enabled. However, you can enable only a few sighash algorithms by using the following command:

set ssl parameter -sigDigestType <sigDigestType>

Parameters

sigDigestType

Signature digest algorithms supported by the appliance. The platform determines the list of algorithms supported by default.

              On VPX: RSA-MD5 RSA-SHA1 RSA-SHA224 RSA-SHA256 RSA-SHA384 RSA-

              SHA512 DSA-SHA1 DSA-SHA224 DSA-SHA256 DSA-SHA384 DSA-SHA512

              On MPX with N3 cards: RSA-MD5 RSA-SHA1 RSA-SHA224 RSA-

              SHA256 RSA-SHA384 RSA-SHA512 ECDSA-SHA1 ECDSA-SHA224 ECDSA-

              SHA256 ECDSA-SHA384 ECDSA-SHA512

              Other MPX Platforms: RSA-MD5 RSA-SHA1 RSA-SHA224 RSA-SHA256 RSA-SHA384 RSA-

              SHA512.

    set ssl parameter -sigDigestType RSA-SHA224 RSA-SHA256 RSA-SHA384 RSA-SHA512
<!--NeedCopy-->

Validate the peer certificate

According to RFC 5246, the peer certificate must be signed using one of the sighash algorithms included in the Client Hello extension. To do so, use the strictSigDigestCheck parameter. Depending on the sighash list sent by the client, if you enable strictSigDigestCheck, the appliance returns a certificate signed by one of the sighash algorithms mentioned in the Client Hello extension. If the peer does not have a proper certificate, the connection is dropped. If this parameter is disabled, sighash is not checked in the peer certificate.  

You can configure a strict signature digest check on an SSL virtual server and service. If you enable this parameter on an SSL virtual server, the server certificate sent by the server must be signed by one of the sighash algorithms listed in the Client Hello extension. If client authentication is enabled, then the client certificate received by the server must be signed using one of the sighash algorithms listed in the certificate request sent by the server.

If you enable this parameter on an SSL service, the server certificate received by the client must be signed by one of the sighash algorithms listed in the Client Hello extension. The client certificate must be signed using one of the sighash algorithms listed in the certificate request message.

If the default profile is enabled, you can use it to configure a strict signature digest check on an SSL virtual server, SSL service, and SSL profile.

Configure strict signature digest check on an SSL virtual server, service, or profile by using the CLI

At the command prompt, type:

set ssl vserver <vServerName> -strictSigDigestCheck ( ENABLED | DISABLED )

set ssl service <serviceName> -strictSigDigestCheck ( ENABLED | DISABLED )

set ssl profile <name>-strictSigDigestCheck ( ENABLED | DISABLED )

Parameters

strictSigDigestCheck

              Check whether peer entity certificate is signed using one of the signature-hash algorithms supported by the Citrix ADC appliance.

              Possible values: ENABLED, DISABLED

              Default: DISABLED
<!--NeedCopy-->

Example:

set ssl vserver v1 –strictSigDigestCheck Enabled
set ssl service s1 –strictSigDigestCheck Enabled
set ssl profile p1 –strictSigDigestCheck Enabled
<!--NeedCopy-->

Important:

If DH, ECDHE, or ECDSA ciphers are configured on the appliance, the SKE message must be signed using one of the sighash common to the client list and the list configured on the appliance. If there is no common sighash, the connection is dropped.

SSL offloading configuration
August 20, 2024
Contributed by: 
C C S
August 20, 2024
Contributed by: 
C C S

In this article

Site feedback | Your privacy choices footer linkYour Privacy Choices | Privacy and legal terms | Cookie preferences | Consent settings | docs.cloud.com
© 1999- Cloud Software Group, Inc. All rights reserved.