Install, link, and update certificates
To install a certificate, see Add or update a certificate-key pair.
Note:
NetScaler supports PEM, DER, and PFX (PKCS12) certificate formats.
- PEM can have .crt, .pem, or .cer extension.
- DER has .der extension.
- PFX can have .p12 or .pfx extension.
Typically, the file name extension does not matter. The contents of the file are encoded differently, which decides the format, and the certificate is parsed accordingly.
Link certificates
Many server certificates are signed by multiple hierarchical Certificate Authorities (CA), which means that the certificates form a chain like the following:
Sometimes, the Intermediate CA is split into a primary and secondary intermediate CA certificate. Then the certificates form a chain like the following:
Client machines usually contain the root CA certificate in their local certificate store, but not one or more intermediate CA certificates. The ADC appliance must send one or more intermediate CA certificates to the clients.
Note: The appliance must not send the root CA certificate to the client. The Public Key Infrastructure (PKI) trust relationship model requires root CA certificates to be installed on clients through an out-of-band method. For example, the certificates are included with the operating system or web browser. The client ignores a root CA certificate sent by the appliance.
Sometimes, an intermediate CA that standard web browsers do not recognize as a trusted CA, issues the server certificate. In this case, one or more CA certificates must be sent to the client with the server’s own certificate. Otherwise, the browser terminates the SSL session because it fails to authenticate the server certificate.
Refer to the following sections to add the server and intermediate certificates:
- Manual certificate linking
- Automated certificate linking
- Create a chain of certificates
How to link an intermediate authority certificate
Manual certificate linking
Note: This feature is not supported on the NetScaler FIPS platform and in a cluster setup.
Instead of adding and linking individual certificates, you can now group a server certificate and up to nine intermediate certificates in a single file. You can specify the file’s name when adding a certificate-key pair. Before you do so, make sure that the following prerequisites are met.
- The certificates in the file are in the following order:
- Server certificate (must be the first certificate in the file)
- Optionally, a server key
- Intermediate certificate 1 (ic1)
- Intermediate certificate 2 (ic2)
- Intermediate certificate 3 (ic3), and so on Note: Intermediate certificate files are created for each intermediate certificate with the name “<certificatebundlename>.pem_ic< n>” where n is between 1 and 9. For example, bundle.pem_ic1, where bundle is the name of the certificate set and ic1 is the first intermediate certificate in the set.
- Bundle option is selected.
- No more than nine intermediate certificates are present in the file.
The file is parsed and the server certificate, intermediate certificates, and server key (if present) are identified. First, the server certificate and key are added. Then, the intermediate certificates are added, in the order in which they were added to the file, and linked accordingly.
An error is reported if any of the following conditions exist:
- A certificate file for one of the intermediate certificates exists on the appliance.
- The key is placed before the server certificate in the file.
- An intermediate certificate is placed before the server certificate.
- Intermediate certificates are not in placed in the file in the same order as they are created.
- No certificates are present in the file.
- A certificate is not in the proper PEM format.
- The number of intermediate certificates in the file exceeds nine.
Add a certificate set by using the CLI
At the command prompt, type the following commands to create a certificate set and verify the configuration:
add ssl certKey <certkeyName> -cert <string> -key <string> -bundle (YES | NO)
show ssl
show ssl certlink
<!--NeedCopy-->
Note:
Starting from NetScaler release 14.1 build 21.x, the length of the path is increased from 63 to 255 characters for the certificate and key parameters.
In the following example, the certificate set (bundle.pem) contains the following files:
Server certificate (bundle) linked to bundle_ic1
First intermediate certificate (bundle_ic1) linked to bundle_ic2
Second intermediate certificate (bundle_ic2) linked to bundle_ic3
Third intermediate certificate (bundle_ic3)
add ssl certKey bundletest -cert bundle9.pem -key bundle9.pem -bundle yes
sh ssl certkey
1) Name: ns-server-certificate
Cert Path: ns-server.cert
Key Path: ns-server.key
Format: PEM
Status: Valid, Days to expiration:5733
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Server Certificate
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=US,ST=California,L=San Jose,O=Citrix ANG,OU=NS Internal,CN=default OULLFT
Validity
Not Before: Apr 21 15:56:16 2016 GMT
Not After : Mar 3 06:30:56 2032 GMT
Subject: C=US,ST=California,L=San Jose,O=Citrix ANG,OU=NS Internal,CN=default OULLFT
Public Key Algorithm: rsaEncryption
Public Key size: 2048
2) Name: servercert
Cert Path: complete/server/server_rsa_1024.pem
Key Path: complete/server/server_rsa_1024.ky
Format: PEM
Status: Valid, Days to expiration:7150
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Server Certificate
Version: 3
Serial Number: 1F
Signature Algorithm: sha1WithRSAEncryption
Issuer: C=IN,ST=KAR,O=Citrix R&D Pvt Ltd,CN=Citrix
Validity
Not Before: Sep 2 09:54:07 2008 GMT
Not After : Jan 19 09:54:07 2036 GMT
Subject: C=IN,ST=KAR,O=Citrix Pvt Ltd,CN=Citrix
Public Key Algorithm: rsaEncryption
Public Key size: 1024
3) Name: bundletest
Cert Path: bundle9.pem
Key Path: bundle9.pem
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Server Certificate
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA9
Validity
Not Before: Nov 28 06:43:11 2014 GMT
Not After : Nov 25 06:43:11 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=Server9
Public Key Algorithm: rsaEncryption
Public Key size: 2048
4) Name: bundletest_ic1
Cert Path: bundle9.pem_ic1
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA8
Validity
Not Before: Nov 28 06:42:56 2014 GMT
Not After : Nov 25 06:42:56 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA9
Public Key Algorithm: rsaEncryption
Public Key size: 2048
5) Name: bundletest_ic2
Cert Path: bundle9.pem_ic2
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA7
Validity
Not Before: Nov 28 06:42:55 2014 GMT
Not After : Nov 25 06:42:55 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA8
Public Key Algorithm: rsaEncryption
Public Key size: 2048
6) Name: bundletest_ic3
Cert Path: bundle9.pem_ic3
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA6
Validity
Not Before: Nov 28 06:42:53 2014 GMT
Not After : Nov 25 06:42:53 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA7
Public Key Algorithm: rsaEncryption
Public Key size: 2048
7) Name: bundletest_ic4
Cert Path: bundle9.pem_ic4
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA5
Validity
Not Before: Nov 28 06:42:51 2014 GMT
Not After : Nov 25 06:42:51 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA6
Public Key Algorithm: rsaEncryption
Public Key size: 2048
8) Name: bundletest_ic5
Cert Path: bundle9.pem_ic5
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA4
Validity
Not Before: Nov 28 06:42:50 2014 GMT
Not After : Nov 25 06:42:50 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA5
Public Key Algorithm: rsaEncryption
Public Key size: 2048
9) Name: bundletest_ic6
Cert Path: bundle9.pem_ic6
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA3
Validity
Not Before: Nov 28 06:42:48 2014 GMT
Not After : Nov 25 06:42:48 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA4
Public Key Algorithm: rsaEncryption
Public Key size: 2048
10) Name: bundletest_ic7
Cert Path: bundle9.pem_ic7
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA2
Validity
Not Before: Nov 28 06:42:46 2014 GMT
Not After : Nov 25 06:42:46 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA3
Public Key Algorithm: rsaEncryption
Public Key size: 2048
11) Name: bundletest_ic8
Cert Path: bundle9.pem_ic8
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=ICA1
Validity
Not Before: Nov 28 06:42:45 2014 GMT
Not After : Nov 25 06:42:45 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA2
Public Key Algorithm: rsaEncryption
Public Key size: 2048
12) Name: bundletest_ic9
Cert Path: bundle9.pem_ic9
Format: PEM
Status: Valid, Days to expiration:3078
Certificate Expiry Monitor: ENABLED
Expiry Notification period: 30 days
Certificate Type: Intermediate CA
Version: 3
Serial Number: 01
Signature Algorithm: sha256WithRSAEncryption
Issuer: C=IN,ST=ka,O=sslteam,CN=RootCA4096
Validity
Not Before: Nov 28 06:42:43 2014 GMT
Not After : Nov 25 06:42:43 2024 GMT
Subject: C=IN,ST=ka,O=sslteam,CN=ICA1
Public Key Algorithm: rsaEncryption
Public Key size: 2048
Done
sh ssl certlink
1) Cert Name: bundletest CA Cert Name: bundletest_ic1
2) Cert Name: bundletest_ic1 CA Cert Name: bundletest_ic2
3) Cert Name: bundletest_ic2 CA Cert Name: bundletest_ic3
4) Cert Name: bundletest_ic3 CA Cert Name: bundletest_ic4
5) Cert Name: bundletest_ic4 CA Cert Name: bundletest_ic5
6) Cert Name: bundletest_ic5 CA Cert Name: bundletest_ic6
7) Cert Name: bundletest_ic6 CA Cert Name: bundletest_ic7
8) Cert Name: bundletest_ic7 CA Cert Name: bundletest_ic8
9) Cert Name: bundletest_ic8 CA Cert Name: bundletest_ic9
Done
<!--NeedCopy-->
Add a certificate set by using the GUI
- Navigate to Traffic Management > SSL > Certificates > CA Certificates.
- In the details pane, click Install.
- In the Install Certificate dialog box, type the details, such as the certificate and key file name, and then select Certificate Bundle.
- Click Install, and then click Close.
Automated certificate linking
Note: This feature is available from release 13.0 build 47.x.
You no longer have to manually link a certificate to its issuer all the way to the root certificate. If the intermediate CA certificates and the root certificate are present on the appliance, you can click the Link button in the end user certificate.
The potential chain appears.
Click Link Certificate to link all the certificates.
Create a chain of certificates
Instead of using a set of certificates (a single file), you can create a chain of certificates. The chain links the server certificate to its issuer (the intermediate CA). This approach requires that the intermediate CA certificate file is installed on the ADC appliance, and the client application must trust one of the certificates in the chain. For example, link Cert-Intermediate-A to Cert-Intermediate-B, where Cert-Intermediate-B is linked to Cert-Intermediate-C, which is a certificate trusted by the client application.
Note: The appliance supports sending a maximum of 10 certificates in the chain of certificates sent to the client (one server certificate and nine CA certificates).
Create a certificate chain by using the CLI
At the command prompt, type the following commands to create a certificate chain and verify the configuration. (Repeat the first command for each new link in the chain.)
link ssl certkey <certKeyName> <linkCertKeyName>
show ssl certlink
<!--NeedCopy-->
Example:
link ssl certkey siteAcertkey CAcertkey
Done
show ssl certlink
linked certificate:
1) Cert Name: siteAcertkey CA Cert Name: CAcertkey
Done
<!--NeedCopy-->
Create a certificate chain by using the GUI
- Navigate to Traffic Management > SSL > Certificates.
- Select a server certificate, and in the Action list, select Link, and specify a CA certificate name.
Support for SSL certificate bundle
The current design for a certificate bundle has the following drawbacks:
- Adding a certificate bundle adds multiple commands in the configuration. Therefore, you cannot add another certificate bundle if the two bundles share a common intermediate certificate.
- Removing a certificate bundle is a manual process. You must manually remove the files in a specific order.
- Updating a certificate bundle is not supported.
- Cluster is not supported.
The new design for a certificate bundle resolves all these issues. The new entity works on a certificate bundle file. Therefore, there is no need to create files for each intermediate certificate. Removal is also simple with this new entity.
Two certificate bundles can share part of the intermediate certificate chain. You can also add a certificate-key pair using the same server certificate and key that is also part of a certificate bundle.
Note:
Starting from NetScaler release 14.1 build 21.x, the length of the path is increased from 63 to 255 characters for the certificate and key parameters in the following commands:
- add ssl certKeyBundle
- update ssl certKeyBundle
In the following example:
- Certificate bundle bundle1.pem contains server certificate (S1) and intermediate certificates (IC1 and IC2).
- Server certificate is server_cert.pem (S1).
- Intermediate certificates are ic1.pem (IC1) and ic2.pem (IC2).
You can add a certificate bundle that contains S1, IC1, and IC2.
add ssl certkeybundle b1 -bundlefile bundle1.pem
You can also add a certificate-key pair using S1 and IC1.
add ssl certkey server-cert -cert server_cert.pem
add ssl certkey ic1 -cert ic1.pem
Important!
- Bundle creation fails if the following order is not met:
- Server certificate (SC) must be placed at the top of the bundle file.
-
IC[1-9]
are intermediate certificates.IC[i]
is issued byIC[i+1]
. The certificates must be placed in a sequence, and all the intermediate certificates must be present in the bundle.
- Certificates must be of PEM format only.
- Server certificate key (SCK) can be placed anywhere in the bundle.
- A maximum of 9 intermediate certificates are supported.
To add a certificate bundle using the CLI
At the command prompt, type:
add ssl certKeyBundle <bundle_name> -bundlefile <bundle_file_name> -passplain <>
Example:
add ssl certkeyBundle cert_bundle -bundlefile bundle_4096.pem
To add a certificate bundle using the GUI
- Navigate to Traffic Management > SSL > Certificate Key Bundle.
- Click Install.
- Specify a name for the bundle, browse to the location of the bundle on the appliance or your local computer, and select a file.
- Click Create.
To update a certificate bundle using the CLI
Note:
The update command is available in release 14.1 build 12.x and later.
At the command prompt, type:
update ssl certKeyBundle [-bundlefile <input_filename>]
Example:
update ssl certKeyBundle cert_bundle -bundlefile bundle_4096_updated.pem
To update a certificate bundle using the GUI
- Navigate to Traffic Management > SSL > Certificate Key Bundle.
- Select a bundle and click Update.
- Browse to the location of the bundle on the appliance or your local computer, and select a file.
- Click OK.
To remove a certificate bundle using the CLI
At the command prompt, type:
rm ssl certKeyBundle <bundle_name>
Example:
rm ssl certkeybundle cert_bundle
To remove a certificate bundle using the GUI
- Navigate to Traffic Management > SSL > Certificate Key Bundle.
- Select a bundle and click Delete.
- In the confirmation dialog box, click Yes.
To bind a certificate bundle to an SSL virtual server using the CLI
At the command prompt, type:
bind ssl vserver <vip-name> -certkeybundleName <certkeybundle_name> [ -SNICertkeybundle]
Example:
bind ssl vserver v_server -certkeyBundleName cert_bundle
show ssl certkeyBundle cert_bundle
1) Name: cert_bundle
Bundle path: bundle_4096.pem
Certificate:
Status: Valid, Days to expiration:278
Serial Number: 83
Subject: C=IN,ST=KAR,O=CITRIX,CN=4096.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=ia24096.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:17:57 2021 GMT
Not After : Jul 13 10:17:57 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 82
Subject: C=IN,ST=KAR,O=CITRIX,CN=ia24096.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=ia14098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:15:37 2021 GMT
Not After : Jul 13 10:15:37 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 81
Subject: C=IN,ST=KAR,O=CITRIX,CN=ia14098.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:13:20 2021 GMT
Not After : Jul 13 10:13:20 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 00
Subject: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:10:23 2021 GMT
Not After : Jul 13 10:10:23 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 2048
SAN ENTRIES: None
1) Vserver Name: v_server
<!--NeedCopy-->
To bind a certificate bundle to an SSL virtual server using the GUI
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- Select an SSL virtual server and click Edit.
- In the Certificate section of the Load Balancing Virtual Server page, click Bundle Certificate.
-
In the Certificate Key Bundle Binding page, do one of the following:
- Select a bundle: Click the right-arrow (
>
) and select a bundle. Click Select. - Add a bundle: Click Add. Browse to the location of the bundle on the appliance or your local computer and click Create.
- Select a bundle: Click the right-arrow (
- Click Bind.
To bind a certificate bundle to an SSL virtual server as an SNI certificate bundle using the CLI
At the command prompt, type:
bind ssl vserver <vip-name> -certkeybundleName b2 -SNICertkeybundle
Example:
bind ssl vserver v_server -certkeyBundleName cert_bundle -sniCertkeybundle
sh ssl certkeybundle cert_bundle
1) Name: cert_bundle
Bundle path: bundle_4096.pem
Certificate:
Status: Valid, Days to expiration:278
Serial Number: 83
Subject: C=IN,ST=KAR,O=CITRIX,CN=4096.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=ia24096.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:17:57 2021 GMT
Not After : Jul 13 10:17:57 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 82
Subject: C=IN,ST=KAR,O=CITRIX,CN=ia24096.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=ia14098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:15:37 2021 GMT
Not After : Jul 13 10:15:37 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 81
Subject: C=IN,ST=KAR,O=CITRIX,CN=ia14098.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:13:20 2021 GMT
Not After : Jul 13 10:13:20 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 4096
SAN ENTRIES: None
CA Certificate:
Status: Valid, Days to expiration:278
Serial Number: 00
Subject: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Issuer: C=IN,ST=KAR,O=CITRIX,CN=root4098.com
Signature Algorithm: sha256WithRSAEncryption
Validity
Not Before: Jul 13 10:10:23 2021 GMT
Not After : Jul 13 10:10:23 2022 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 2048
SAN ENTRIES: None
1) Vserver Name: v_server
2) Vserver Name: v_server
<!--NeedCopy-->
To bind a certificate bundle to an SSL virtual server as an SNI certificate bundle using the GUI
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- Select an SSL virtual server and click Edit.
- In the Certificate section, click Bundle Certificate.
- In the Certificate Key Bundle Binding page, do one of the following:
- Select a bundle: Click the right-arrow (“>”) and choose a bundle from the list. Click Select.
- Add a bundle: Click Add. Browse to the location of the bundle on the appliance or your local computer and click Create.
- Select SNICertKey Bundle.
- Click Bind.
To unbind a certificate bundle from an SSL virtual server using the CLI
At the command prompt, type:
unbind ssl vserver <vip-name> -certkeybundleName <certkeybundle_name> [ -SNICertkeybundle]
Example:
unbind ssl vserver v_server -certkeybundleName cert_bundle
To unbind a certificate bundle from an SSL virtual server using the GUI
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- Select an SSL virtual server and click Edit.
- In the Certificate section, click Bundle Certificate.
- In the SSL Virtual Server Certkey Bundle Binding page, select a bundle, and click Unbind.
- In the confirmation dialog box, click Yes.
- Click Close.
- Click Done.
User scenarios for certificate bundle binding
The following scenarios explain how the ADC appliance processes a request related to certificate bundles.
Scenario 1: A certificate-key pair and a certificate bundle containing the same server certificate is bound to the same SSL virtual server
While binding a certificate-key pair and a certificate bundle containing the same server certificate to the same SSL virtual server, the order of commands determines the final binding.
For example,
- Certificate bundle bundle1.pem contains server certificate S1 and intermediate certificates IC1 and IC2.
- Certificate file server_cert.pem contains S1.
Both bundle1.pem and server_cert.pem have the same server certificate S1.
If the following commands are run in the specified order, the server certificate binding to the SSL virtual server replaces the certificate bundle binding to that virtual server.
add ssl certkeybundle b1 -bundlefile bundle1.pem
add ssl certkey server_cert -cert server_cert.pem
bind ssl vserver v1 -certkeybundle b1
bind ssl vserver v1 -cert server_cert
Scenario 2: Two certificate bundles contain the same intermediate certificate chain
You can add two certificate bundles with the same intermediate certificate chain. The two bundles act as independent entities.
In the following example, certificate bundle bundle-1 contains server certificate S1 and intermediate certificates IC1 and IC2 in that order. Certificate bundle bundle-2 contains server certificate S2 and intermediate certificates IC1 and IC2 in that order.
- Certificate bundle bundle1.pem (S1, IC1, IC2)
- Certificate bundle bundle2.pem (S2, IC1, IC2)
When S1 in bundle-1 is selected in the SSL handshake process, the intermediate certificate chain of bundle-1 is sent to the client.
add ssl certkeybundle bundle-1 -bundlefile bundle1.pem
add ssl certkeybundle bundle-2 -bundlefile bundle2.pem
Scenario 2: Two certificate bundles contain some common intermediate certificates in the chain
You can add two certificate bundles with some common intermediate certificates in the chain.
In the following example, bundle-1 contains server certificate S1 and intermediate certificates IC1 and IC2. Certificate bundle bundle-2 contains server certificate S2 and intermediate certificates IC1, IC2, and IC3.
Certificate bundle bundle1.pem (S1, IC1, IC2) Certificate bundle bundle2.pem (S2, IC1, IC2, IC3)
add ssl certkeybundle bundle-1 -bundlefile bundle1.pem
add ssl certkeybundle bundle-2 -bundlefile bundle2.pem
When S1 in bundle-1 is selected in the SSL handshake process, the intermediate certificate chain of bundle-1 is sent to the client. That is, (S1→IC1→IC2)
is sent to the client. IC3 is not added.
When S2 in bundle-2 is selected in the SSL handshake process, the intermediate certificate chain of bundle-2 only sent to the client. That is, (S1→IC1→IC2→IC3)
is sent to the client.
Limitations of certificate bundle
- Monitoring the status of a certificate in the certificate bundle is not supported.
- Certificate bundles can be bound only to SSL virtual servers.
- OCSP stapling is not supported.
Note
Update operations are supported on certificate bundles from release 14.1 build 12.x. You can now directly update a certificate bundle. Previously, you had to first unbind and delete a bundle, and then add and bind a certificate bundle.
Update an existing server certificate
To change an existing server certificate manually, you must perform the following steps:
- Unbind the old certificate from the virtual server.
- Remove the certificate from the appliance.
- Add the new certificate to the appliance.
- Bind the new certificate to the virtual server.
To reduce downtime when replacing a certificate-key pair, you can update an existing certificate. If you want to replace a certificate with a certificate that was issued to a different domain, you must disable domain checks before updating the certificate.
To receive notifications about certificates due to expire, you can enable the expiry monitor.
When you remove or unbind a certificate from a configured SSL virtual server or service, the virtual server or service becomes inactive. They are active after a new valid certificate is bound to them. To reduce downtime, you can use the update feature to replace a certificate-key pair that is bound to an SSL virtual server or an SSL service.
Overview diagram of how to update an SSL certificate on the NetScaler appliance.
Note:
Starting from NetScaler release 14.1 build 21.x, the length of the path is increased from 63 to 255 characters for the certificate and key parameters.
How to update an existing certificate
Update an existing certificate-key pair by using the CLI
At the command prompt, type the following commands to update an existing certificate-key pair and verify the configuration:
update ssl certkey <certkeyName> -cert <string> -key <string>
show ssl certKey <certkeyName>
<!--NeedCopy-->
Example:
update ssl certkey siteAcertkey -cert /nsconfig/ssl/cert.pem -key /nsconfig/ssl/pkey.pem
Done
show ssl certkey siteAcertkey
Name: siteAcertkey Status: Valid
Version: 3
Serial Number: 02
Signature Algorithm: md5WithRSAEncryption
Issuer: /C=US/ST=CA/L=Santa Clara/O=siteA/OU=Tech
Validity
Not Before: Nov 11 14:58:18 2001 GMT
Not After: Aug 7 14:58:18 2004 GMT
Subject: /C=US/ST-CA/L=San Jose/O=CA/OU=Security
Public Key Algorithm: rsaEncryption
Public Key size: 2048
Done
<!--NeedCopy-->
Update an existing certificate-key pair by using the GUI
-
Navigate to Traffic Management > SSL > Certificates > Server Certificates.
-
Select the certificate that you want to update, and click Update.
-
Select Update the certificate and key.
-
In Certificate File Name, click Choose File > Local, and browse to the updated .pfx file or certificate PEM file.
-
If you upload a .pfx file, you are prompted to specify the .pfx file password.
-
If you upload a certificate pem file, you must also upload a certificate key file. If the key is encrypted, you must specify the encryption password.
-
-
If the common name of the new certificate does not match the old certificate, then select No Domain Check.
-
Click OK. All the SSL virtual servers to which this certificate is bound are automatically updated.
-
After replacing the certificate, you might have to update the certificate link to a new intermediate certificate. For more information about updating an intermediate certificate without breaking the links, see Update an intermediate certificate without breaking the links.
-
Right-click the updated certificate, and click Cert Links, to see if it is linked to an intermediate certificate.
-
If the certificate is not linked, then right-click the updated certificate, and click Link to link it to an intermediate certificate. If you don’t see an option to link, then you must first have to install a new intermediate certificate on the appliance under the CA Certificates node.
-
Update an existing CA certificate
The steps to update an existing CA certificate are the same as updating an existing server certificate. The only difference is that you do not need a key in the case of CA certificates.
Disable domain checks
When an SSL certificate is replaced on the appliance, the domain name mentioned on the new certificate must match the domain name of the certificate being replaced. For example, if you have a certificate issued to abc.com, and you are updating it with a certificate issued to def.com, the certificate update fails.
However, if you want the server that has been hosting a particular domain to host a new domain, disable the domain check before updating its certificate.
Disable the domain check for a certificate by using the CLI
At the command prompt, type the following commands to disable the domain check and verify the configuration:
update ssl certKey <certkeyName> -noDomainCheck
show ssl certKey <certkeyName>
<!--NeedCopy-->
Example:
update ssl certKey sv -noDomainCheck
Done
show ssl certkey sv
Name: sv
Cert Path: /nsconfig/ssl/complete/server/server_rsa_512.pem
Key Path: /nsconfig/ssl/complete/server/server_rsa_512.ky
Format: PEM
Status: Valid, Days to expiration:9349
Certificate Expiry Monitor: DISABLED
Done
<!--NeedCopy-->
Disable the domain check for a certificate by using the GUI
- Navigate to Traffic Management > SSL > Certificates, select a certificate, and click Update.
- Select No Domain Check.
Replace the default certificate of an ADC appliance with a trusted CA certificate that matches the host name of the appliance
The following procedure assumes that the default certificate (ns-server-certificate
) is bound to the internal services.
- Navigate to Traffic Management > SSL > SSL Certificates > Create Certificate Request.
- In common name, type
test.citrixadc.com
. - Submit the CSR to a trusted certificate authority.
- After receiving the certificate from the trusted CA, copy the file to the
/nsconfig/ssl
directory. - Navigate to Traffic Management > SSL > Certificates > Server Certificates.
- Select the default server certificate (
ns-server-certificate
) and click Update. - In the Update Certificate dialog box, in Certificate File Name, browse to the certificate received from the CA after signing.
- In the Key File Name field, specify the default private key file name (
ns-server.key
). - Select No Domain Check.
- Click OK.
Enable the expiry monitor
An SSL certificate is valid for a specific period. A typical deployment includes multiple virtual servers that process SSL transactions, and the certificates bound to them can expire at different times. An expiry monitor configured on the appliance creates entries in the appliance’s syslog and ns audit logs when a certificate configured is due to expire.
If you want to create SNMP alerts for certificate expiration, you must configure them separately.
Enable an expiry monitor for a certificate by using the CLI
At the command prompt, type the following commands to enable an expiry monitor for a certificate and verify the configuration:
set ssl certKey <certkeyName> [-expiryMonitor ( ENABLED | DISABLED ) [-notificationPeriod <positive_integer>]]
show ssl certKey <certkeyName>
<!--NeedCopy-->
Example:
set ssl certKey sv -expiryMonitor ENABLED –notificationPeriod 60
Done
<!--NeedCopy-->
Enable an expiry monitor for a certificate by using the GUI
- Navigate to Traffic Management > SSL > Certificates, select a certificate, and click Update.
- Select Notify When Expires, and optionally specify a notification period.
Update an intermediate certificate without breaking the links
You can update an intermediate certificate without breaking any existing links. The ‘AuthorityKeyIdentifier’ extension, in the linked certificate issued by the certificate to be replaced, must not contain an authority certificate serial number (‘authorityCertSerialNumber’) field. If the ‘AuthorityKeyIdentifier’ extension contains a serial number field, then the certificate serial numbers of the old and new certificate must be the same. You can update any number of certificates in the link, one at a time, if the preceding condition is met. Previously, the links broke if an intermediate certificate was updated.
For example, there are four certificates: CertA
, CertB
, CertC
, and CertD
. Certificate CertA
is the issuer for CertB
, CertB
is the issuer for CertC
, and so on. If you want to replace an intermediate certificate CertB
with CertB_new
, without breaking the link, the following condition must be met:
The certificate serial number of CertB
must match the certificate serial number of CertB_new
if both of the following conditions are met:
- The
AuthorityKeyIdentifier
extension is present inCertC
. - This extension contains a serial number field.
If the common name in a certificate changes, while updating the certificate specify nodomaincheck
.
In the preceding example, to change “www.example.com” in CertD
to “*.example.com,” select the ‘No Domain Check” parameter.
Update the certificate by using the CLI
At the command prompt, type:
update ssl certKey <certkeyName> -cert <string> [-password] -key <string> [-noDomainCheck]
<!--NeedCopy-->
Example:
update ssl certkey siteAcertkey -cert /nsconfig/ssl/cert.pem -key /nsconfig/ssl/pkey.pem -noDomainCheck
<!--NeedCopy-->
Display a certificate chain
A certificate contains the name of the issuing authority and the subject to whom the certificate is issued. To validate a certificate, you must look at the issuer of that certificate and confirm if you trust the issuer. If you do not trust the issuer, you must see who issued the issuer certificate. Go up the chain until you reach the root CA certificate or an issuer that you trust.
As part of the SSL handshake, when a client requests a certificate, the appliance presents a certificate and the chain of issuer certificates present on the appliance. An administrator can view the certificate chain for the certificates present on the appliance and install any missing certificates.
View the certificate chain for the certificates present on the appliance by using the CLI
At the command prompt, type:
show ssl certchain <cert_name>
<!--NeedCopy-->
Examples
There are 3 certificates: c1, c2, and c3. Certificate c3 is the root CA certificate and signs c2, and c2 signs c1. The following examples illustrate the output of the
show ssl certchain c1
command in different scenarios.
Scenario 1:
Certificate c2 is linked to c1, and c3 is linked to c2.
Certificate c3 is a root CA certificate.
If you run the following command, the certificate links up to the root CA certificate are displayed.
show ssl certchain c1
Certificate chain details of certificate name c1 are:
1) Certificate name: c2 linked; not a root certificate
2) Certificate name: c3 linked; root certificate
Done
<!--NeedCopy-->
Scenario 2:
Certificate c2 is linked to c1.
Certificate c2 is not a root CA certificate.
If you run the following command, the information that certificate c3 is a root CA certificate but is not linked to c2 is displayed.
show ssl certchain c1
Certificate chain details of certificate name c1 are:
1) Certificate Name: c2 linked; not a root certificate
2) Certificate Name: c3 not linked; root certificate
Done
<!--NeedCopy-->
Scenario 3:
Certificate c1, c2, and c3 are not linked but are present on the appliance.
If you run the following command, information about all the certificates starting with the issuer of certificate c1 is displayed. It is also specified that the certificates are not linked.
show ssl certchain c1
Certificate chain details of certificate name c1 are:
1) Certificate Name: c2 not linked; not a root certificate
2) Certificate Name: c3 not linked; root certificate
Done
<!--NeedCopy-->
Scenario 4:
Certificate c2 is linked to c1.
Certificate c3 is not present on the appliance.
If you run the following command, information about the certificate linked to c1 is displayed. You are prompted to add a certificate with the subject name specified in c2. In this case, the user is asked to add the root CA certificate c3.
show ssl certchain c1
Certificate chain details of certificate name c1 are:
1) Certificate Name: c2 linked; not a root certificate
2) Certificate Name: /C=IN/ST=ka/O=netscaler/CN=test
Action: Add a certificate with this subject name.
Done
<!--NeedCopy-->
Scenario 5:
A certificate is not linked to certificate c1 and the issuer certificate of c1 is not present on the appliance.
If you run the following command, you are prompted to add a certificate with the subject name in certificate c1.
sh ssl certchain c1
Certificate chain details of certificate name c1 are:
1) Certificate Name: /ST=KA/C=IN
Action: Add a certificate with this subject name.
<!--NeedCopy-->
Support for CA certificate bundle
Starting from release 14.1 build 29.x, you can effortlessly add and bind a CA certificate bundle to an SSL virtual server, service, and service group without creating separate files for each CA certificate using the CA certificate bundle support. Using the cacertbundle
parameter, you can easily add, bind, unbind, and delete a CA certificate bundle file containing a list of CA certificates.
Important:
-
Bundle creation fails if the following order is not met:
- `IC[1-9]` are intermediate certificates. `IC[i]` is issued by `IC[i+1]`. The certificates must be placed in a sequence, all the intermediate certificates must be present in the bundle, and the root certificate should be the last one. In the following example, the certificate set (bundle.pem) contains the following files: - First intermediate certificate (bundle_ic1) - Second intermediate certificate (bundle_ic2) - Root certificate - A maximum of 9 intermediate certificates are supported. - Certificate must be in PEM format.
- If a CA certificate key pair is bound to a virtual server, service or service group then you cannot bind the CA certificate bundle and vice versa.
- Encrypted private keys are not supported.
- DTLS bind and Cluster are not supported.
- OCSP and CRL is not supported.
Add CA certificate bundle using CLI
At the command prompt, type:
add ssl cacertbundle <cacertbundle_name> -bundlefile <cabundle_file_name>
sh ssl cacertbundle
<!--NeedCopy-->
Example:
add ssl cacertbundle cb1 -bundlefile cabundle_1.pem
sh ssl cacertbundle cb1
Name: cb1
CA certbundle path: cabundle_1.pem
CA Certificate:
Status: Valid, Days to expiration:6501
Serial Number: F5CFF9EF1E246198
Subject: C=in,O=citrix,CN=ca_6
Issuer: C=in,O=citrix,CN=root
Signature Algorithm: sha1WithRSAEncryption
Validity
Not Before: Jul 7 09:44:12 2011 GMT
Not After : Jun 29 09:44:12 2041 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 2048
SAN ENTRIES:
None
CA Certificate:
Status: Valid, Days to expiration:6501
Serial Number: 8D653DEA29C98668
Subject: C=in,O=citrix,CN=root
Issuer: C=in,O=citrix,CN=root
Signature Algorithm: sha1WithRSAEncryption
Validity
Not Before: Jul 7 09:44:08 2011 GMT
Not After : Jun 29 09:44:08 2041 GMT
Public Key Algorithm: rsaEncryption
Public Key size: 2048
SAN ENTRIES:
None
Done
<!--NeedCopy-->
Add CA certificate bundle using GUI
- Navigate to Traffic Management > SSL > CA Certificate Bundle.
- Click Install.
- In the Install CA Certificate Bundle page, enter the name and select the CA certificate bundle file.
- Click Create.
Delete CA certificate bundle uisng CLI
At the command prompt, type:
rm ssl cacertbundle <cacertbundle_name>
Example:
rm ssl cacertbundle cacertbundlesample
Delete CA certificate bundle using GUI
- Navigate to Traffic Management > SSL > CA Certificate Bundle.
- Select an existing CA certificate bundle and click Delete.
Bind CA certificate bundle to an SSL virtual server using CLI
At the command prompt, type:
bind ssl vserver <vip-name> -cacertbundle <cacertbundle_name> [-skipCACertBundle]
<!--NeedCopy-->
Example:
bind ssl vserver v1 -cacertbundle cb1
Done
> sh ssl vs v1
Advanced SSL configuration for VServer v1:
DH: DISABLED
DH Private-Key Exponent Size Limit: DISABLED Ephemeral RSA: ENABLED Refresh Count: 0
Session Reuse: ENABLED Timeout: 120 seconds
Cipher 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
HSTS Preload: NO
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: X_25519, P_256, P_384, P_224, P_521
1) CA certbundle Name: cb1 CA_Name Sent
1) Cipher Name: DEFAULT
Description: Default cipher list with encryption strength >= 128bit
Done
<!--NeedCopy-->
Bind CA certificate bundle using GUI
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- Select the SSL virtual server and click Edit.
- Under the Certificate section, click CA Certificate Bundle.
- In the CA Certificate Bundle Binding page, select the CA certificate bundle and click Bind.
Unbind CA certificate bundle using CLI
At the command prompt, type:
unbind ssl vserver <vip-name> -cacertbundle <cacertbundle_name>
Example:
unbind ssl vserver Vserver1 -cacertbundle cb1
Unbind CA certificate bundle using GUI
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- Select an SSL virtual server and click Edit.
- Under the Certificate section, click CA Certificate Bundle.
- In the SSL Virtual Server CA Certificate Bundle Binding page, select the CA Bundle file and click Unbind.
In this article
- Link certificates
- How to link an intermediate authority certificate
- Manual certificate linking
- Automated certificate linking
- Create a chain of certificates
- Support for SSL certificate bundle
- User scenarios for certificate bundle binding
- Limitations of certificate bundle
- Update an existing server certificate
- How to update an existing certificate
- Update an existing CA certificate
- Disable domain checks
- Replace the default certificate of an ADC appliance with a trusted CA certificate that matches the host name of the appliance
- Enable the expiry monitor
- Update an intermediate certificate without breaking the links
- Display a certificate chain
- Support for CA certificate bundle