ADC

SSL offloading configuration

August 1, 2023

Contributed by:

To configure SSL offloading, you must enable SSL processing on the NetScaler appliance and configure an SSL based virtual server. The virtual server 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.

Note

From release 13.1 build 17.x, protocols lower than TLSv1.2 are disabled on the SSL internal services. If the default (enhanced) profile is enabled, then the ns_default_ssl_profile_internal_frontend_service profile is bound to the SSL internal services and SSLv3, TLSv1.0, and TLSv1.1 protocols are disabled in the profile.

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. However, 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, click Configure Basic Features, and click 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.

rm service <servicename>
<!--NeedCopy-->

Example:

rm service sslsvc
<!--NeedCopy-->

To modify a service, use the set service command, select any parameter, and change its setting.

set service <name> (<IP> | <serverName>) <serviceType> <port>
<!--NeedCopy-->

Example:

set service sslsvc 198.51.100.225 SSL 443
<!--NeedCopy-->

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. The set command is similar to 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. To forward data, services representing these physical servers must be bound to the virtual server that receives the SSL data.

Typically, the link between the ADC appliance and the physical server is secure. Therefore, 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 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

Navigate to Traffic Management > Load Balancing > Virtual Servers.
Open a virtual server and click the Load Balancing Virtual Server Service Bindings tile under the Services and Service Groups section.
In the Load Balancing Virtual Server Service Binding page, click Add Bindings tab, click Click to select under Select Service, and select the check box next to the service to be bound.
Click Select and click Bind.

Configure a server name indication (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 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 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 same organization controls these domains and the second-level domain name is the same. 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”. It cannot secure the “login.ftp.sports.net” domain.

Note: On an ADC appliance, only domain name, URL, and email ID DNS entries in the SAN field are compared.

You can bind multiple server certificates to a single SSL virtual server or transparent service using the -SNICert option. The virtual server or service issues these certificates 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 service name 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

Navigate to Traffic Management > Load Balancing > Virtual Servers.
Open an SSL virtual server and, in Certificates, select Server Certificate.
Add a certificate or select a certificate from the list, and click Server Certificate for SNI.
In Advanced Settings, select SSL Parameters.
Click 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. This support helps meet federal system integrator customer security requirements. Also, SNI 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. To meet this requirement, support for SNI at the back end on a NetScaler appliance is required.

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.

Support for dynamic SNI on the back-end service

The NetScaler appliance supports dynamic SNI on the back-end TLS connections. That is, the appliance learns the SNI in the client connection and uses it in the server-side connection. You no longer need to specify a common name in the SSL service, service group, or profile. The common name received in the SNI extension of the Client Hello message is forwarded to the back-end SSL connection.

Earlier, you had to configure static SNI on SSL services, service groups, and SSL profiles. As a result, only the configured static SNI extension was sent to the server. If a client needed to access multiple domains at the same time, the ADC appliance was not able to send the SNI received from the client to the back-end service. Instead, it sent the static common name that was configured. Now, if the back-end server is configured for multiple domains, the server can respond with the correct certificate based on the SNI received in the Client Hello message from the appliance.

Point to Note:

SNI must be enabled on the front end and the correct SNI certificate bound to the SSL virtual server. If you don’t enable SNI on the front end, the SNI information is not passed to the back end.
When server authentication is enabled, the server certificate is verified by the CA certificate and the common name/SAN entries in the server certificate are matched with the SNI. Therefore, the CA certificate must be bound to the service.
Reuse of back-end connection and SSL session is based on SNI when dynamic SNI is enabled.

SSL monitors do not send SNI when dynamic SNI is enabled. For SNI based probing, attach a back-end profile on which static SNI is configured to the SSL monitors. The monitor must be configured with the same custom header as SNI.

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>

set ssl profile <name> -SNIEnable ENABLED
<!--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

    set ssl profile sslprof -SNIEnable ENABLED
<!--NeedCopy-->

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

Navigate to Traffic Management > Load Balancing > Services.
Select an SSL service, and in Advanced Settings, click SSL Parameters.
Click SNI Enable.

Configure SNI on the SSL profile by using the GUI

Navigate to System > Profiles > SSL Profile.
Click Add.
In Basic Settings, select SNI Enable.
Click OK.

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

You can bind secure monitors of type HTTP, HTTP-ECV, TCP, or TCP-ECV to the back-end services and service groups that support SNI. However, the monitor probes do not send the SNI extension if dynamic SNI is enabled. To send SNI probes, enable static SNI in the back-end SSL profile and bind the profile to the monitor. Set the custom header in the monitor to the server name that is sent as the SNI extension in the client hello of the monitor probe.

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> -secure YES
add ssl profile <name> -sslProfileType BackEnd
set lb monitor <monitorName> <type> -customHeaders <string> -sslprofile <backend ssl profile>
set ssl profile <name> -sniEnable ENABLED -commonName <string>
bind service <name> -monitorName <string>
<!--NeedCopy-->

Example:

add ssl profile sni_backend_profile -sslProfileType BackEnd
set ssl profile sni_backend_profile -sniEnable ENABLED -commonName example.com
add lb monitor http-ecv-mon HTTP-ECV -secure YES
set monitor http-ecv-mon HTTP-ECV -customHeaders "Host: example.com\r\n" -sslprofile sni_backend_profile
bind service ssl_service –monitorName http-ecv-mon
<!--NeedCopy-->

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

Navigate to System > Profiles > SSL Profiles.
Click Add.
Specify a name for the profile and in SSL Profile Type, select Backend.
Specify the common name (same as host header) and select SNI Enable.
Click OK.
Navigate to Traffic Management > Load Balancing > Monitor.
Click Add.
Specify a name for the monitor. In Type, select HTTP, HTTP-ECV, TCP, or TCP-ECV.
Specify a Custom Header.
Select Secure.
In SSL Profile, select the back-end SSL profile created in the preceding steps.
Click Create.
Navigate to Traffic Management > Load Balancing > Services.
Select an SSL service and click Edit.
In Monitors, click Add Binding, select the monitor created in the preceding steps, and click Bind.

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

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

Allow handshake to continue for an unknown server name

Note

This feature is available in release 13.1 build 45.x and later.

When SNI is enabled, and the NetScaler appliance receives a client hello with an unknown server name, it terminates the SSL handshake. From release 13.1 build 45.x, the appliance allows the SSL handshake to continue even for an unknown server name, and leaves the decision to the client to drop or complete the handshake. You can configure this setting on a front-end SSL profile when SNI is ENABLED using the allowUnknownSNI parameter.

Keep this parameter disabled if you need to use a forward action for an SNI-based rule. For example, you have enabled SNI on virtual server v1 and configured a policy to forward all requests for a specific domain (www.example.com) to virtual server v2. Earlier, any requests received on v1 for this domain are automatically forwarded to v2. However, if the allowunknownSNI parameter is enabled then the request is processed on v1. The parameter must be disabled for the appliance to process the request on v1.

Configure allow unknown SNI using the CLI

At the command prompt, type:

set ssl profile default_profile -SNIEnable Enabled -allowUnknownSNI <DISABLED/ENABLED>

The `allowunknownSNI parameter is disabled by default. As a result, the appliance aborts the handshake for an unknown server name. To enable this setting, type:

set ssl profile default_profile -SNIEnable Enabled -allowUnknownSNI ENABLED

Configure allow unknown SNI using the GUI

Navigate to System > Profiles > SSL Profile.
If you add a profile, select FrontEnd in the SSL Profile Type list. Otherwise, you can edit an existing front-end profile.
Select Allow Unknown SNI.
Click OK and then click Done.

Add or update a certificate-key pair

Notes:

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 build 41.x, certificate names of up to 63 characters are supported.

From release 13.0 build 79.x, password protected certificate-key pairs are always added successfully. Earlier, if a strong password option was enabled on a NetScaler appliance, sometimes the password protected certificate-key pairs were not added. However, the certificate-key configuration is lost if you downgrade to an earlier build. Also, in the NITRO API response for certificate-key pairs, the passplain variable is sent instead of the passcrypt variable.

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. The password of the private key used while adding an SSL certificate-key pair is saved using a unique encryption key for each NetScaler appliance.

The ADC appliance offloads SSL transactions from the server. Therefore, 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 be bound to the virtual server that processes the SSL transactions.

Note: 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.

Only RSA keys are supported on NetScaler appliances.

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

From release 13.1 build 17.x, all NetScaler platforms support certificates that are signed using the RSASSA-PSS algorithms. These algorithms are supported in the X.509 certificate path validation. The following table shows the RSASSA-PSS parameter sets supported by the NetScaler appliance.

Public Key OID	Mask Generation Function (MGF)	MGF Digest Function	Signature Digest Function	Salt Length
rsaEncryption	MGF1	SHA-256	SHA-256	32 bytes
rsaEncryption	MGF1	SHA-384	SHA-384	48 bytes
rsaEncryption	MGF1	SHA-512	SHA-512	64 bytes

Note

A NetScaler SDX appliance supports certificates of 512 or more bits. Each NetScaler VPX instance hosted on the appliance supports the preceding certificate sizes 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 > Server.
Enter the values for the following parameters and click Install.
- Certificate-Key Pair Name - Name for the certificate and private-key pair.
- Certificate File Name - Signed certificate received from the certificate authority.
- Key File Name - Name of and, optionally, path to the private-key file that is used to form the certificate-key pair.

Bind the certificate-key pair to the SSL virtual server

Important: Link any intermediate certificates to this certificate before binding the certificate to an SSL virtual server. For information about linking certificates, see Create a chain of certificates.

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.

Use a valid, existing SSL certificate that you have uploaded to the NetScaler appliance. As an alternative for testing purposes, 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.

During the SSL handshake, in the certificate request message during client authentication, the server lists the distinguished names (DN) of all the certificate authorities (CA) bound to the server. The server accepts a client certificate only from this list. 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. The error 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

Navigate to Traffic Management > Load Balancing > Virtual Servers and open an SSL virtual server. Click inside the Certificate section.
Click the arrow to select the certificate-key pair.
Select the certificate-key pair from the list.
Bind the certificate-key pair to the virtual server. To add a server certificate as an SNI certificate, select Server Certificate for SNI.

SSL virtual server parameters

Set the advanced SSL configuration for an SSL virtual server. You can also set many of these parameters 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

To use ciphers on the appliance that require a DH key exchange to set up the SSL transaction, enable DH key exchange on the appliance. 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

Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
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 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. It is 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

Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
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 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

Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
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 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 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 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. The handshake succeeds if one of the following conditions is met:

TLS_FALLBACK_SCSV value is not included in the client hello message.
The protocol version in the client hello is the highest protocol version supported by the virtual server.

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

Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
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 close-notify at the entity level by using the CLI

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

To configure at the virtual server level, type:

set ssl vserver <vServerName> -sendCloseNotify ( YES | NO )
show ssl vserver <vServerName>
<!--NeedCopy-->

To configure at the service level, type:

set ssl service <serviceName> -sendCloseNotify ( YES | NO )
show ssl service <serviceName>
<!--NeedCopy-->

To configure 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 feature at the entity level by using the GUI

Navigate to Traffic Management > Load Balancing > Virtual Servers, and open a virtual server.
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.
NDCPP compliance certificate check – Applies when the appliance acts a client (back-end connection). During certificate verification, ignore the common name if SAN is present in the SSL certificate.
Enable a heterogeneous cluster of Cavium chip-based appliances, such as MPX 14000, and Intel Coleto chip-based appliances, such as MPX 15000 appliances with a different number of packet engines. (Support added in release 13.0 build 47.x).
Enable secure renegotiation at the back end (Support added from release 1.0 build 58.x).
Adaptive SSL traffic control (Support added in release 13.0 build 58.x).

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>] [-ndcppComplianceCertCheck ( YES | NO)] [-heterogeneousSSLHW (ENABLED | DISABLED )]
show ssl parameter
<!--NeedCopy-->

Example:

set ssl parameter -quantumSize 8 -crlMemorySizeMB 256 -strictCAChecks no -ssltriggerTimeout 100 -sendClosenotify no -encryptTriggerPktCount 45 -denySSLReneg NONSECURE -insertionEncoding unicode -ocspCacheSize 10 -pushFlag 3 -dropReqWithNoHostHeader YES  -pushEncTriggerTimeout 100 ms -ndcppComplianceCertCheck YES
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                                : NONSECURE
    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
    Crypto Device Disable Limit                           : 0
    Global undef action for control policies              : CLIENTAUTH
    Global undef action for data policies                 : NOOP
    Default profile                                       : DISABLED
    SSL Insert Space in Certificate Header                : YES
    Disable TLS 1.1/1.2 for SSL_BRIDGE secure monitors    : NO
    Disable TLS 1.1/1.2 for dynamic and VPN services      : NO
    Software Crypto acceleration CPU Threshold            : 0
    Hybrid FIPS Mode                                      : DISABLED
    Signature and Hash Algorithms supported by TLS1.2     : ALL
    SSL Interception Error Learning and Caching           : DISABLED
    SSL Interception Maximum Error Cache Memory           : 0 Bytes
    NDCPP Compliance Certificate Check                    : YES
    Heterogeneous SSL HW (Cavium and Intel Based)         : ENABLED
 Done
<!--NeedCopy-->

Configure NDcPP compliance certificate check by using the GUI

Navigate to Traffic Management > SSL and, in the Settings group, select Change advanced SSL settings.
Select NDCPP Compliance Certificate Check. Click OK.

Support for secure renegotiation at the back end of a NetScaler appliance

Note: This feature is supported in release 13.0 build 58.x and later. In earlier releases and builds, only non-secure renegotiation was supported on the back end.

The feature is supported on the following platforms: • VPX • MPX platforms containing N2 or N3 chips • Intel Coleto SSL chip-based platforms

The feature is not yet supported on the FIPS platform.

Secure renegotiation is denied by default on the back end of an ADC appliance. That is, the denySSLReneg parameter is set to ALL (default).

To allow secure renegotiation on the back end, select from one of the following settings for the denySSLReneg parameter:

NO
FRONTEND_CLIENT
FRONTEND_CLIENTSERVER
NONSECURE

Enable secure renegotiation by using the CLI

At the command prompt, type:

set ssl parameter -denySSLReneg <denySSLReneg>

Example:

set ssl parameter -denySSLReneg NONSECURE
 Done

sh 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                                     : YES
    Encryption trigger packet count                       : 45
    Deny SSL Renegotiation                                : NONSECURE
    Subject/Issuer Name Insertion Format                  : Unicode
    OCSP cache size                                       : 10 MB
    Push flag                                             : 0x0 (Auto)
    Strict Host Header check for SNI enabled SSL sessions : NO
    Match HTTP Host header with SNI                       : CERT
    PUSH encryption trigger timeout                       : 1 ms
    Crypto Device Disable Limit                           : 0
    Global undef action for control policies              : CLIENTAUTH
    Global undef action for data policies                 : NOOP
    Default profile                                       : ENABLED
    SSL Insert Space in Certificate Header                : YES
    Disable TLS 1.1/1.2 for SSL_BRIDGE secure monitors    : NO
    Disable TLS 1.1/1.2 for dynamic and VPN services      : NO
    Software Crypto acceleration CPU Threshold            : 0
    Hybrid FIPS Mode                                      : DISABLED
    Signature and Hash Algorithms supported by TLS1.2     : ALL
    SSL Interception Error Learning and Caching           : DISABLED
    SSL Interception Maximum Error Cache Memory           : 0 Bytes
    NDCPP Compliance Certificate Check                    : NO
    Heterogeneous SSL HW (Cavium and Intel Based)         : DISABLED
    Crypto Operation Queue Limit                          : 150%
 Done
<!--NeedCopy-->

Enable secure renegotiation by using the GUI

Navigate to Traffic Management > SSL > Change advanced SSL settings.
Set Deny SSL Renegotiation to any value other than ALL.

Adaptive SSL traffic control

Note: This feature is supported in release 13.0 build 58.x and later.

When high traffic is received on the appliance and the crypto acceleration capacity is full, the appliance starts queuing connections to process later. Currently, the size of this queue is fixed at 64 K and the appliance starts dropping connections if this value is exceeded.

From release 13.0 build 58.x, the user can configure a value that is a percentage of the actual capacity. With this enhancement, the appliance drops new connections if the number of elements in the queue is greater than the limit that is adaptively and dynamically calculated. This approach controls incoming SSL connections and prevents excessive resource consumption and other failures, such as load balancing monitoring failure or slow response to secure applications, on the appliance.

If the queue is empty, the appliance can continue to accept connections. If the queue is not empty, the crypto system has reached its capacity and the appliance starts queuing connections.

The limit is calculated based on:

The actual capacity of the appliance.
Value configured by the user as a percentage of the actual capacity. Default value is set to 150%.

For example, if the actual capacity of an appliance is 1000 operations/second at a given time and the default percentage is configured, the limit after which the appliance drops connections is 1500 (150% of 1000).

To configure the operation queue limit by using the CLI

At the command prompt, type:

set ssl parameter -operationQueueLimit <positive_integer>

Operation Queue Limit - Limit in percentage of capacity of the crypto operations queue beyond which new SSL connections are not accepted until the queue is reduced. Default value: 150. Minimum value: 0. Maximum value: 10000.

To configure the operation queue limit by using the GUI

Navigate to Traffic Management > SSL.
In Settings, click Change advanced SSL settings.
Type a value in Operation Queue Limit. Default is 150.
Click OK.

Heterogeneous cluster deployments

From release 13.0 build 47.x, you can form a heterogeneous cluster deployment of NetScaler MPX appliances with a different number of packet engines by setting the SSL parameter “Heterogeneous SSL HW” to ENABLED. For example, to form a cluster of Cavium chip-based appliances (MPX 14000 or similar) and Intel Coleto chip-based appliances (MPX 15000 or similar), enable the SSL parameter “Heterogeneous SSL HW.” To form a cluster of platforms using the same chip, keep the default value (DISABLED) for this parameter.

Notes:

The following features are not supported in a heterogeneous cluster:

VPX instances hosted on NetScaler SDX appliances.

SSLv3 protocol on SSL entities, such as virtual server, services, service group, and internal services.

Software crypto acceleration CPU threshold (using hardware and software to improve ECDSA and ECDHE cipher performance).

For more information about the platforms supported in a heterogeneous cluster, see https://docs.citrix.com/en-us/citrix-adc/13-1/clustering/support-for-heterogeneous-cluster.html.

Enable a heterogeneous cluster using the CLI

At the command prompt, type:

set ssl parameter -heterogeneousSSLHW ENABLED

Enable a heterogeneous cluster using the GUI

Navigate to Traffic Management > SSL and, in the Settings group, select Change advanced SSL settings.
Select Heterogeneous SSL HW. Click OK.

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

Navigate to Traffic Management > Load Balancing > Virtual servers and open an SSL virtual server.
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 algorithms. The client indicates to the server which signature hash algorithm pairs might be used in the SSL handshake messages (SKE and CCV) by using the “signature_algorithms” extension. 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 signature hash 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 signature hash algorithm.

Note:

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

The appliance supports only RSA-SHA1 and RSA-SHA256 on the front end, and RSA-MD5, RSA-SHA1, and RSA-SHA256 on the back end.

The MPX/SDX/VPX appliance supports the following signature hash 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 and on an MPX/SDX appliance without N3 chips:
- RSA-MD5
- RSA-SHA1
- RSA-SHA224
- RSA-SHA256
- RSA-SHA384
- RSA-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

By default, all the signature hash algorithms are enabled. However, you can enable only a few signature hash 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

              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 signature hash algorithms included in the Client Hello extension. You can use the strictSigDigestCheck parameter. Depending on the signature hash list sent by the client, if you enable strictSigDigestCheck, the appliance returns a certificate signed by one of the signature hash 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, the signature hash 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 signature hash 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 signature hash 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 signature hash algorithms listed in the Client Hello extension. The client certificate must be signed using one of the signature hash 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 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 signature-hashes common to the client list and the list configured on the appliance. If there is no common signature hash, the connection is dropped.

Configure SSL for ADC Admin UI access

A certificate-key pair is required for HTTPS access to the configuration utility and for secure remote procedure calls. On a NetScaler MPX appliance or a VPX virtual appliance, a certificate-key pair is automatically bound to the internal services. However, this certificate might not be trusted by browsers. You must upload valid CA certificates in the browser to complete the authentication without any errors.

Configure secure HTTPS by using the CLI

To configure secure HTTPS by using the CLI, follow these steps:

Add a certificate-key pair.

add certkey server -cert servercert -key serverkey
<!--NeedCopy-->

Bind this certificate-key pair to the following internal services.

bind ssl service nshttps-127.0.0.1-443 -certkeyname server

bind ssl service nshttps-::11-443 -certkeyname server
<!--NeedCopy-->

Configure secure HTTPS by using the GUI

To configure secure HTTPS by using the GUI, follow these steps:

Navigate to Traffic Management > SSL > Certificates.
In the details pane, click Install.
In the Install Certificate dialog box, type the certificate details.
Click Install, and then click Close.
Navigate to Traffic Management > Load Balancing > Services.
In the details pane, on the Action tab, click Internal Services.
Select nshttps-127.0.0.1-443 from the list, and then click Open.
On the SSL Settings tab, in the Available pane, select the certificate created in step 4, click Bind, and then click OK.
Select nshttps-::11-443 from the list, and then click Open.
On the SSL Settings tab, in the Available pane, select the certificate created in step 4, click Bind, and then click OK.
Click OK.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

SSL offloading configuration

August 1, 2023

Contributed by:

August 1, 2023

Contributed by:

Enable SSL
Configure services
SSL virtual server configuration
Bind services to the SSL virtual server
Configure a server name indication (SNI) virtual server for secure hosting of multiple sites
Support for SNI on the back-end service
Allow handshake to continue for an unknown server name
Add or update a certificate-key pair
Bind the certificate-key pair to the SSL virtual server
SSL virtual server parameters
Global SSL parameters
Configure SSL for ADC Admin UI access

SSL offloading configuration

Enable SSL

Enable SSL processing by using the CLI

Enable SSL processing by using the GUI

Configure services

Add a service by using the CLI

Modify or remove a service by using the CLI

Configure a service by using the GUI

SSL virtual server configuration

Add an SSL-based virtual server by using the CLI

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

Configure an SSL-based virtual server by using the GUI

Bind services to the SSL virtual server

Bind a service to a virtual server by using the CLI

Unbind a service from a virtual server by using the CLI

Bind a service to a virtual server by using the GUI

Configure a server name indication (SNI) virtual server for secure hosting of multiple sites

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

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

Support for SNI on the back-end service

Support for dynamic SNI on the back-end service

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

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

Configure SNI on the SSL profile by using the GUI

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

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

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

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

Allow handshake to continue for an unknown server name

Configure allow unknown SNI using the CLI

Configure allow unknown SNI using the GUI

Add or update a certificate-key pair

Add a certificate-key pair by using the CLI

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

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

Bind the certificate-key pair to the SSL virtual server

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

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

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

SSL virtual server parameters

Set SSL virtual server parameters by using the CLI

Diffie-Hellman (DH) parameters

Configure DH parameters by using the CLI

Configure DH parameters by using the GUI

Ephemeral RSA

Configure ephemeral RSA by using the CLI

Configure ephemeral RSA by using the GUI

Session reuse

Configure session reuse by using the CLI

Configure session reuse by using the GUI

SSL protocol settings

Configure SSL protocol support by using the CLI

Configure SSL protocol support by using the GUI

Close-notify

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

Configure the close-notify feature at the entity level by using the GUI

Global SSL parameters

Configure global SSL parameters by using the CLI

Configure NDcPP compliance certificate check by using the GUI

Support for secure renegotiation at the back end of a NetScaler appliance

Enable secure renegotiation by using the CLI

Enable secure renegotiation by using the GUI

Adaptive SSL traffic control

To configure the operation queue limit by using the CLI

To configure the operation queue limit by using the GUI

Heterogeneous cluster deployments

Enable a heterogeneous cluster using the CLI

Enable a heterogeneous cluster using the GUI

PUSH flag based encryption trigger mechanism

Configure PUSH flag-based encryption by using the CLI

Configure PUSH flag-based encryption by using the GUI

Support for TLS1.2 signature hash algorithm

Validate the peer certificate

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

Configure SSL for ADC Admin UI access

Configure secure HTTPS by using the CLI

Configure secure HTTPS by using the GUI

In this article