Configure SSL-based header insertion
Because the Citrix ADC appliance offloads all SSL-related processing from the servers, the servers receive only HTTP traffic. In some circumstances, the server needs certain SSL information. For example, security audits of recent SSL transactions require the client subject name (contained in an X509 certificate) to be logged on the server.
Such data can be sent to the server by inserting it into the HTTP header as a name-value pair. You can insert the entire client certificate, if required, a hash (also known as fingerprint or thumbprint) of the entire client certificate, or only the specific fields from the certificate, such as the subject, serial number, issuer, signature, SSL session ID, cipher suite, or the not-before or not-after date used to determine certificate validity.
You can enable SSL-based insertion for HTTP-based SSL virtual servers and services only. You cannot apply it to TCP-based SSL virtual servers and services. Also, client authentication must be enabled on the SSL virtual server, because the inserted values are taken from the client certificate that is presented to the virtual server for authentication.
To configure SSL-based header insertion, first create an SSL action for each specific set of information to be inserted, and then create policies that identify the connections for which you want to insert the information. As you create each policy, specify the action that you want associated with the policy. Then, bind the policies to the SSL virtual servers that will receive the SSL traffic.
The following example uses default syntax policies. In the following example, a control policy (ctrlpol) is created to perform client authentication if a request is received for the URL /testsite/file5.html. A data policy (datapol) is created to perform an action (act1) if client authentication is successful, and an SSL action (act1) is added to insert the certificate details and issuer’s name in the request before forwarding the request. For other URLs, client authentication is disabled. The policies are then bound to an SSL virtual server (ssl_vserver) that receives the SSL traffic.
Command-line example of configuring SSL-based header insertion
Example:
add ssl action act1 -clientCert ENABLED -certHeader mycert -clientcertissuer ENABLED -certIssuerHeader myissuer
add ssl policy datapol -rule HTTP.REQ.URL.EQ("/testsite/file5.html") -action act1
add ssl policy ctrlpol -rule HTTP.REQ.URL.EQ("/testsite/file5.html") -action CLIENTAUTH
bind ssl vserver ssl_vserver -policyName ctrlpol -priority 1
bind ssl vserver ssl_vserver -policyName datapol -priority 1
Done
<!--NeedCopy-->
Configure SSL-based header insertion by using the GUI
-
Navigate to Traffic Management > SSL > Policies.
-
In the details pane, on the Actions tab, click Add.
-
In the Create SSL Action dialog box, set the following parameters:
- Name*
- Client Certificate
- Certificate Tag
- Client Certificate Issuer
- Issuer Tag
* A required parameter
-
Click Create, and then click Close.
-
On the tab, click Add to create a control policy.
-
In the Create SSL Policy dialog box, set the following parameters:
- Name*
- Expression
- Request Action
* A required parameter
-
Click Create, and then click Close.
-
Create a data policy by repeating steps 5 through 7.
-
In the navigation pane, expand SSL Offload, and then click Virtual Servers.
-
In the details pane, from the list of virtual servers, select the virtual server to which you want to bind the SSL policies, and then click Open.
-
In the Configure Virtual Server (SSL Offload) dialog box, click SSL Settings, and then click SSL Policies.
-
In the Bind/Unbind SSL Policies dialog box, click Insert Policy. Under Policy Name, select the policy that you created in steps 5 through 7.
-
Click OK, and then click Close. A message appears in the status bar, stating that the policy has been bound successfully.
-
Repeat steps 12 and 13 and select the policy that you created in step 8.
Configure an SSL policy action for inserting client certificate thumbprint in the HTTP header
Citrix ADC appliances now support inserting the thumbprint (also called a fingerprint) of a certificate into the header of a request sent to a back-end server. If client authentication is enabled, the appliance computes the thumbprint of the certificate, and uses an SSL policy action to insert the thumbprint into the request. The server searches for the thumbprint, and grants secure access if there is a match.
You must configure an SSL action to enable client certificate fingerprint, specify a header name to insert the client certificate fingerprint, and a digest (hash value) to compute the fingerprint value. The Citrix ADC appliance supports SHA1 and SHA2 (SHA224, SHA256, SHA384, SHA512) digests. The appliance derives the fingerprint value by computing the specified digest of the DER-encoding of the client certificate. Then, create an SSL policy specifying this action, and bind the policy to an SSL virtual server.
Configure an SSL action for inserting client certificate thumbprint by using the CLI
At the command prompt type:
add ssl action <name> -clientCertFingerprint ( ENABLED | DISABLED ) -certFingerprintHeader <string> -certFingerprintDigest <certFingerprintDigest>
<!--NeedCopy-->
Arguments:
clientCertFingerprint:
Insert the certificate’s fingerprint into the HTTP header of the request being sent to the web server. The fingerprint is derived by computing the specified hash value (SHA256, for example) of the DER-encoding of the client certificate.
certFingerprintHeader:
Name of the header into which to insert the client certificate fingerprint.
certFingerprintDigest:
Digest algorithm used to compute the fingerprint of the client certificate.
Possible values: SHA1, SHA224, SHA256, SHA384, SHA512
Example:
add ssl action act1 -clientcertfingerprint ENABLED -certfingerprintdigest SHA1 -certfingerprintheader example
Done
<!--NeedCopy-->
sh ssl action act1
1) Name: act1
Type: Data Insertion
Cert Fingerprint Header: ENABLED
Cert-Fingerprint Tag: example
Cert-Fingerprint Digest Algorithm: SHA1
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
<!--NeedCopy-->
add ssl policy pol1 -rule true -action act1
Done
<!--NeedCopy-->
bind ssl vserver v1 -policyName pol1 -priority 10
Done
<!--NeedCopy-->
sh ssl vserver 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
SSLv2 Redirect: DISABLED
ClearText Port: 0
Client Auth: ENABLED Client Cert Required: Mandatory
SSL Redirect: DISABLED
Non FIPS Ciphers: DISABLED
SNI: DISABLED
OCSP Stapling: DISABLED
SSLv2: DISABLED SSLv3: DISABLED TLSv1.0: DISABLED TLSv1.1: ENABLED TLSv1.2: DISABLED
Push Encryption Trigger: Always
Send Close-Notify: YES
ECC Curve: P_256, P_384, P_224, P_521
1) CertKey Name: intca6 CA Certificate CRLCheck: Mandatory CA_Name Sent
2) CertKey Name: intca5 CA Certificate CRLCheck: Mandatory CA_Name Sent
3) CertKey Name: intca4 CA Certificate CRLCheck: Mandatory CA_Name Sent
4) CertKey Name: intca3 CA Certificate CRLCheck: Mandatory CA_Name Sent
5) CertKey Name: intca2 CA Certificate CRLCheck: Mandatory CA_Name Sent
6) CertKey Name: intca1 CA Certificate CRLCheck: Mandatory CA_Name Sent
Data policy
1) Policy Name: pol1 Priority: 10
1) Cipher Name: DEFAULT
Description: Default cipher list with encryption strength >= 128bit
Done
<!--NeedCopy-->
Configure an SSL action for inserting client certificate thumbprint by using the GUI
- Navigate to Traffic Management > SSL > Policies.
- In the details pane, select the SSL Actions tab, and click Add.
- In the Create SSL Action dialog box, set the following parameters:
- Name*
- Client Certificate Finger Print
- FingerPrint Tag
- FingerPrint Digest *A required parameter
- Click Create.
- Select the SSL Policies tab, and click Add.
- In the Create SSL Policy dialog box, set the following parameters:
- Name*
- Action
- Expression *A required parameter
- Click Create.
- Navigate to Traffic Management > Load Balancing > Virtual Servers.
- In the details pane, from the list of SSL virtual servers, select the virtual server to which you want to bind the SSL policy, and then click Edit.
- In Advanced Settings, click SSL Policies.
- Click below SSL Policy, and in Policy Binding dialog box, select the policy created earlier and assign a priority.
- Click Bind.