In NetScaler 11.1
In Citrix ADC
In All products
Product documentation
In NetScaler 11.1
In Citrix ADC
In All products
NetScaler
13.0 12.1 11.1
View PDF

SSL offloading configuration

September 21, 2020
Contributed by: 
C

To configure SSL offloading, you must enable SSL processing on the NetScaler appliance and 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 will 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 NetScaler 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 NetScaler 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 NetScaler 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 NetScaler 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 vserver. 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

For the NetScaler appliance to forward decrypted SSL data to servers in the network, services representing these physical servers must be bound to the virtual server that receives the SSL data.

Because the link between the NetScaler appliance and the physical server is typically secure, data transfer between the appliance and the physical server does not have to be encrypted. 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 NetScaler 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: DISABLED

            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 NetScaler 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 NetScaler 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 above configuration is not in place, TLS connections to the domains in (certkey A) will 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 -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 new 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 NetScaler 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 NetScaler 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 this, 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 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.

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 NetScaler 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 NetScaler 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 NetScaler 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 NetScaler appliance. The NetScaler 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 NetScaler MPX appliance and a NetScaler 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 NetScaler 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 format is automatically detected by the software. Therefore, you are no longer required to specify the format in the inform parameter. If you do specify the format (correct or incorrect), it is ignored by the software. 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 (supported only on the front end)
  • SHA-512 (supported only on the front end)

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)
  • 2048-bit certificate on the back-end server
  • 2048-bit client certificate (if client authentication is enabled on the virtual server)

Note

A NetScaler SDX appliance supports certificates of 512 or more bits. Each NetScaler VPX instance hosted on the appliance supports the certificate sizes listed above 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 additional 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 NetScaler 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 should 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-->

Diffe-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 and/or resource, you need to disable ephemeral RSA key exchange.

By default, this feature is enabled on the NetScaler 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 NetScaler appliance by default. Enabling this feature reduces server load, improves response time, and increases the number of SSL transactions per second (TPS) that can be supported by the server.

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 NetScaler appliance supports the SSLv3, TLSv1, TLSv1.1, and TLSv1.2 protocols. Each of these 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 NetScaler 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 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 the 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 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  TLS                                                                                        v1.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 NetScaler 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 may 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 a client certificate is requested by the server 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 NetScaler 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.

Now, 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 this, 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 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 default profile is enabled, you can use it to configure 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 NetScaler 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
September 21, 2020
Contributed by: 
C
September 21, 2020
Contributed by: 
C

In this article

Site feedback | Privacy and legal terms | Cookie preferences | Consent settings
© 1999- Citrix Systems, Inc. All rights reserved.