SSL built-in actions and user-defined actions

Unless you need only the built-in actions in your policies, you have to create the actions before creating the policies, so that you can specify the actions when you create the policies. The built-in actions are of two types, control actions and data actions. You use control actions in control policies, and data actions in data policies.

The built-in control actions are:

• CLIENTAUTH—Perform client certificate authentication.
• NOCLIENTAUTH—Do not perform client certificate authentication.

The built-in data actions are:

• RESET—Close the connection by sending a RST packet to the client.
• DROP—Drop all packets from the client. The connection remains open until the client closes it.
• NOOP—Forward the packet without performing any operation on it.

You can create user-defined data actions. For example, if you enable client authentication, you can create an SSL action to insert client-certificate data into the request header before forwarding the request to the web server.

If a policy evaluation results in an undefined state, an UNDEF action is performed. For either a data policy or a control policy, you can specify RESET, DROP, or NOOP as the UNDEF action. For a control policy, you also have the option of specifying CLIENTAUTH or NOCLIENTAUTH.

Examples of built-in actions in a policy

In the following example, if the client sends a cipher other than an EXPORT category cipher, the Citrix ADC appliance requests client authentication. The client has to provide a valid certificate for a successful transaction.

add ssl policy pol1 -rule CLIENT.SSL.CIPHER_EXPORTABLE.NOT -reqAction CLIENTAUTH
<!--NeedCopy-->

The following examples assume that client authentication is enabled.

If the version in the certificate provided by the user matches the version in the policy, no action is taken and the packet is forwarded:

add ssl policy pol1 -rule CLIENT.SSL.CLIENT_CERT.VERSION.EQ(2) -reqAction NOOP
<!--NeedCopy-->

If the version in the certificate provided by the user matches the version in the policy, the connection is dropped:

add ssl policy pol1 -rule CLIENT.SSL.CLIENT_CERT.VERSION.EQ(2) -reqAction DROP
<!--NeedCopy-->

If the version in the certificate provided by the user matches the version in the policy, the connection is reset:

add ssl policy pol1 -rule CLIENT.SSL.CLIENT_CERT.VERSION.EQ(2) -reqAction RESET
<!--NeedCopy-->

User-defined SSL actions

In addition to built-in actions, you can also configure other SSL actions depending on your deployment. These are called user-defined actions.

Configure a user-defined SSL action by using the CLI

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

add SSL action <name> -clientAuth(DOCLIENTAUTH | NOCLIENTAUTH) -clientCert (ENABLED | DISABLED) certHeader <string> -clientHeader <string> -clientCertSerialNumber (ENABLED | DISABLED) -certSerialHeader <string> -clientCertSubject (ENABLED | DISABLED) -certSubjectHeader <string> -clientCertHash (ENABLED | DISABLED) -certHashHeader <string> -clientCertIssuer (ENABLED | DISABLED) -certIssuerHeader <string> -sessionID (ENABLED | DISABLED) -sessionIDheader <string> -cipher (ENABLED | DISABLED) -cipherHeader <string> -clientCertNotBefore (ENABLED | DISABLED) -certNotBeforeHeader <string> -clientCertNotAfter (ENABLED | DISABLED) -certNotAfterHeader <string> -OWASupport (ENABLED | DISABLED)
<!--NeedCopy-->

show ssl action [<name>]
<!--NeedCopy-->

Example:

add ssl action Action-SSL-ClientCert -clientCert ENABLED -certHeader "X-Client-Cert"
<!--NeedCopy-->

show ssl action Action-SSL-ClientCert

1)      Name: Action-SSL-ClientCert
        Data Insertion Action:
        Cert Header: ENABLED            Cert Tag: X-Client-Cert
Done
<!--NeedCopy-->

Configure a user-defined SSL action by using the GUI

Navigate to Traffic Management > SSL > Policies and, on the Actions tab, click Add.

Configure an SSL action to forward client traffic to another virtual server

Note: This feature is available in release 12.1 build 49.x and later.

Admins can configure an SSL action to forward the client traffic received on an SSL virtual server to another virtual server to avoid SSL offloading or terminating the connection on the ADC appliance. For example, if the appliance does not have a certificate or it does not support a specific cipher, instead of terminating the connection, admins can choose to forward the request to another virtual server for further action. This virtual server can be of type: SSL, TCP, or SSL_BRIDGE.

To achieve the above, a new bind point ‘CLIENTHELLO_REQ’ is added to evaluate client traffic when a client hello is received. If the policy bound to the virtual server receiving client traffic evaluates to true after parsing the client hello, the traffic is forwarded to another virtual server. If this virtual server is of type SSL, it performs the handshake. If this virtual server is of type TCP or SSL_BRIDGE, the backend server performs the handshake.

In release 12.1-49.x, only the forward and reset actions are supported for CLIENTHELLO_REQ bind point. The following expression prefixes are available:

• CLIENT.SSL.CLIENT_HELLO.CIPHERS.HAS_HEXCODE
• CLIENT.SSL.CLIENT_HELLO.CLIENT_VERSION
• CLIENT.SSL.CLIENT_HELLO.IS_RENEGOTIATE
• CLIENT.SSL.CLIENT_HELLO.IS_REUSE
• CLIENT.SSL.CLIENT_HELLO.IS_SCSV
• CLIENT.SSL.CLIENT_HELLO.IS_SESSION_TICKET
• CLIENT.SSL.CLIENT_HELLO.LENGTH
• CLIENT.SSL.CLIENT_HELLO.SNI

For a description of these prefixes, see Advanced policy expressions: parsing SSL

A new parameter ‘forward’ is added to the ‘add SSL action’ command and new bind point ‘CLIENTHELLO_REQ’ is added to the ‘bind ssl vserver’ command.

Configuration using the CLI

At the command prompt, type:

add ssl action <name> -forward <virtual server name>

add ssl policy <name> -rule <expression> -action <string>

bind ssl vserver <vServerName> -policyName <string> -priority <positive_integer> -type <type>
<!--NeedCopy-->

EXAMPLE:

add ssl action act1 -forward v2

add ssl policy pol1 -rule client.ssl.client_hello.ciphers.has_hexcode(0x002f) -action act1

bind ssl vserver v1 -policyName pol1 -priority 1 -type CLIENTHELLO_REQ
<!--NeedCopy-->

Configuration using the GUI

Navigate to Traffic Management > SSL > Policies.

Create SSL action:

1. In SSL Actions, click Add.
2. In Create SSL Action, specify a name for the action.
3. In Forward Action Virtual Server, select an existing virtual server or add a new virtual server to forward the traffic to.
4. Optionally, set other parameters.
5. Click Create.

Create SSL policy:

1. In SSL Policies, click Add.
2. In Create SSL Policy, specify a name for the policy.
3. In Action, select the action that you created above.
4. In Expression Editor, enter the rule to evaluate.
5. Click Create.

Create or add a virtual server and bind policy:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
2. Add or select a virtual server.
3. In Advanced Settings, click SSL Policies.
4. Click in the SSL Policy section.
5. In Select Policy, select the policy that you created earlier.
6. In Policy Binding, specify a priority for the policy.
7. In Type, select CLIENTHELLO_REQ.
8. Click Bind.
9. Click Done.

For the end-to-end configuration for the most popular use cases, see Configure SSL action to forward client traffic if the appliance does not have a domain specific (SNI) certificate and Configure SSL action to forward client traffic if a cipher is not supported on the ADC.

SSL action to selectively pick CAs based on SNI for client authentication

Starting Citrix ADC release 12.1 build 50.x, you can send only the list of CAs based on SNI (domain) in the client certificate request rather than the list of all the CAs bound to an SSL virtual server. For example, when a client hello is received, only the CA certificates based on the SSL policy expression (for example, SNI) are sent. To send a specific set of certificates, you must create a CA certificates group, bind this group to an SSL action, and bind the action to an SSL policy. If the policy bound to the virtual server receiving client traffic evaluates to true after parsing the client hello, only a specific CA certificates group is sent in the client request certificate.

Earlier, you had to bind CA certificates to an SSL virtual server. With this enhancement, you can simply add CA certificate groups and associate them to an SSL action.

Note: Client authentication and SNI must be enabled on the SSL virtual server, and the correct SNI certificates must be bound to the virtual server.

Perform the following steps:

1. Add a CA certificate group.

2. Add certificate-key pairs.

3. Bind the certificate-key pairs to this group.

4. Add an SSL action.

5. Add an SSL policy. Specify the action in the policy.

6. Bind the policy to an SSL virtual server. Specify the bind point as CLIENTHELLO_REQ.

Configuration using the CLI

At the command prompt, type the following commands in a sequence:

add ssl caCertGroup <caCertGroupName>
add ssl certkey <certkey_name> -cert <cert> -key <key>
bind ssl caCertGroup <caCertGroupName> <certkey_name>
add ssl action <name> -caCertGrpName <string>
add ssl policy <name> -rule <expression> -action <string>
bind ssl vserver <vServerName> -policyName <string> -priority <positive_integer> -type CLIENTHELLO_REQ
<!--NeedCopy-->

Example:

add ssl cacertGroup ca_cert_group

add ssl certkey ca_certkey1 -cert cacert1 -key cakey1
add ssl certkey ca_certkey2 -cert cacert2 -key cakey2
add ssl certkey snicert -cert snicert -key snikey

bind ssl cacertGroup ca_cert_group ca_certkey1
bind ssl caCertGroup ca_cert_group ca_certkey2
<!--NeedCopy-->

sh ssl caCertGroup ca_cert_group

CA GROUP NAME:     ca_cert_group
ACTIONS REFERRING: 1

1) CertKey Name: ca_certkey1   CA Certificate   CRLCheck: Optional   CA_Name Sent
2) CertKey Name: ca_certkey2   CA Certificate   CRLCheck: Optional   CA_Name Sent
<!--NeedCopy-->

add ssl action pick_ca_group -cacertGrpName ca_cert_group
<!--NeedCopy-->

sh ssl action pick_ca_group
1) Name: sniaction
   Type: Data Insertion
   PickCaCertGroup: ca_cert_group
   Hits: 0
   Undef Hits: 0
   Action Reference Count: 1
<!--NeedCopy-->

add ssl policy snipolicy -rule client.ssl.client_hello.sni.contains("abc") -action pick_ca_group
bind ssl vserver v_SSL -policyName snipolicy -type CLIENTHELLO_REQ -priority 10
<!--NeedCopy-->

sh ssl policy snipolicy
    Name: pol1
    Rule: client.ssl.client_hello.sni.contains("abc")
    Action: pick_ca_group
    UndefAction: Use Global
    Hits: 0
    Undef Hits: 0


    Policy is bound to following entities
1)  Bound to: CLIENTHELLO_REQ VSERVER v_SSL
    Priority: 10
<!--NeedCopy-->

set ssl vserver v_SSL -clientauth ENABLED -SNIEnable ENABLED
bind ssl vserver v_SSL -certkeyName snicert -sniCert
<!--NeedCopy-->

sh ssl vserver v_SSL

    Advanced SSL configuration for VServer v_SSL:
    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: ENABLED
    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)  CertKey Name: snicert   Server Certificate for SNI


    Data policy
1)  Policy Name: snipolicy  Priority: 10



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

Configuration using the GUI

Create CA certificates group and bind certificates to the group:

1. Navigate to Traffic Management > SSL > CA Certificates Group.
2. Click Add and specify a name for the group.
3. Click Create.
4. Select the CA certificate group and then click Show Bindings.
5. Click Bind.
6. In the CA Certificate Binding page, select an existing certificate or click Add to add a new certificate.
7. Click Select and then click Bind.
8. To bind another certificate, repeat steps 5 through 7.
9. Click Close.

Navigate to Traffic Management > SSL > Policies.

Create SSL action:

1. In SSL Actions, click Add.
2. In Create SSL Action, specify a name for the action.
3. In Forward Action Virtual Server, select an existing virtual server or add a new virtual server to forward the traffic to.
4. Optionally, set other parameters.
5. Click Create.

Create SSL policy:

1. In SSL Policies, click Add.
2. In Create SSL Policy, specify a name for the policy.
3. In Action, select the action that you created above.
4. In Expression Editor, enter the rule to evaluate.
5. Click Create.

Create or add a virtual server and bind policy:

1. Navigate to Traffic Management > Load Balancing > Virtual Servers.
2. Add or select a virtual server.
3. In Advanced Settings, click SSL Policies.
4. Click in the SSL Policy section.
5. In Select Policy, select the policy that you created earlier.
6. In Policy Binding, specify a priority for the policy.
7. In Type, select CLIENTHELLO_REQ.
8. Click Bind.
9. Click Done.

Unbind a CA certificate group by using the GUI

1. Navigate to Traffic Management > SSL > CA Certificates Group.
2. Select a certificate group and click Show Bindings.
3. Select the certificate to remove from the group and click Unbind.
4. If prompted for confirmation, click Yes.
5. Click Close.

Remove a CA certificate group by using the GUI

1. Navigate to Traffic Management > SSL > CA Certificates Group.
2. Select a certificate group and click Delete.
3. If prompted for confirmation, click Yes.