Client SSL Certificate Validation

Overview

Avi Vantage can validate SSL certificates presented by clients against a trusted certificate authority (CA) and a configured certificate revocation list (CRL). Certificate information is passed to the server through various headers through additional options. For certificate authentication, an HTTP application profile and an associated public key infrastructure (PKI) profile have to be configured. Starting with Avi Vantage release 18.2.3, this has been extended to L4 SSL/TLS applications (via the Avi CLI). This article explains the application profiles and PKI profile configurations.

HTTP Application Profile

To configure an HTTP application profile:

  1. Navigate to Templates > Profiles > Application.
  2. Click on Create to create a new HTTP application profile with type as HTTP. To know more, refer to Configuring HTTP Profile

Note: The Client SSL Certificate Validation section of the UI displays three options for validation. Those options are discussed later in this article.

HTTP Policies

When sending a client certificate in a HTTP request, you can see a client-escaped certificate in the DataScript/ HTTP policy header.

DataScript

Attach a DataScript as follows:


 escaped_cert = avi.ssl.client_cert(avi.CLIENT_CERT_ESCAPED)
 avi.vs.log(escaped_cert)
 avi.http.add_header("escaped_client_cert",escaped_cert)

Send HTTPS request as follows:

sudo curl -vvv -k https://100.64.216.200:443 --cert /root/client/ssl_certs/client_auth_cert_1.pem --key /root/client/ssl_certs/client_auth_key_1.key

You will see a escaped certificate in the virtual service logs and headers.

Remove the DataScript and send the request again. There will not be any certificate there.

  • Attach an HTTP request policy in a virtual service.

  • Add an action rule of type Modify Header and select Add Header option.

  • In Add Header, specify the header name and select SSL Client Cert Escaped option for the header value.

  • Send a HTTP/ HTTPS request from the client.

  • The logs header displays the escaped certificate details.

  • Remove the rule and again send the traffic. There should not be any escaped certificate in the logs header.

HTTP Headers

Avi Vantage optionally inserts the client’s certificate, or parts of it, into a new HTTP header to be sent to the server. To insert multiple headers, the plus icon is used. These inserted headers are in addition to any headers added or manipulated by the more granular HTTP policies or DataScripts.

  • HTTP Header Name — Name of the headers to be inserted into the client request that is sent to the server.
  • HTTP Header Value — Used with the HTTP Header Name field, this field is used to determine the field of the client certificate to insert into the HTTP header sent to the server. Several options are more general, such as the SSL Cipher, which lists the ciphers negotiated between the client and Avi Vantage. These generic headers may be used for non-client certificate connections by setting the Validation Type to Request.

Note: Using the app profile option to add a header for SSL client cert using HTTP_POLICY_VAR_SSL_CLIENT_RAW code or appending the result of avi.ssl.client_cert(avi.CLIENT_CERT) via DataScript results in an invalid header value containing <0a> <09> as line separators for the PEM-encoded certificate rather than just <09>. This results in a malformed HTTP request going to the server since the <0a> is interpreted as the end of the header value.

L4 SSL/TLS Application Profile

Starting with Avi Vantage release 18.2.3 client certificate verification on L4 SSL/TLS applications is supported. Refer to the Configuring L4 SSL/TLS Profile section of the How to Enable Client Certificate Authentication on Avi Vantage article.

PKI Profile

The PKI profile contains the configured certificate authorities and CRL. A PKI profile is necessary if the Validation Type is set to Request or Validation Type is Required.

The PKI profile supports configuring and updating the client certificate revocation lists. The PKI profile is used to validate clients or server certificates.

Navigate to Applications > Templates, select the Security tab, and click on the PKI Profile option.

Refer to Create a PKI Profile to know more.

  • Client Certificate Validation: Avi Vantage validates client access to an HTTPS virtual service via client SSL certificates. Clients will present their certificate when accessing the virtual service. This will be matched against a CRL. If the certificate is valid and the clients are not on the list of revoked certificates, they will be allowed access to the HTTPS virtual server. Client certificate validation is enabled via the HTTP profile’s Authentication tab. The HTTP profile will reference the PKI profile for specifics on the CA and the CRL. A single PKI profile may be referenced by multiple profiles.

  • Server Certificate Validation: Avi Vantage can validate the certificate presented by a server, such as when an HTTPS health check is sent to a server. Server certificate validation also uses a PKI profile to validate the certificate presented. Server certificate validation can be configured by enabling SSL within the desired pool, then specifying the PKI Profile.

PKI Profile Settings

The PKI profile settings are explained below.

  • Name — The unique name for the profile.

  • Ignore Peer Chain — This option is disabled by default. When disabled, the certificate must present a full chain which is traversed and validated, starting from the client or server presented certificate to the terminal root certificate.
    If this option is enabled, Avi Vantage will ignore whatever cert chain the peer/client is presenting. Instead, the root and intermediate certs configured in the Certificate Authority section of the PKI profile are used to verify trust of the client’s cert. Each intermediate certificate must be validated and matched against a CA certificate included in the PKI profile.

  • Host Header Check — If enabled, this option ensures the virtual service’s VIP field, when resolved using DNS, matches the domain name field of the certificate presented from a server to Avi Vantage when back-end SSL is enabled. If the server’s certificate does not match, it is considered insecure and marked down.
  • Enable CRL Check — If this option is selected, the client’s certificate will be verified against the certificate revocation list.

For more information, refer to Create a PKI Profile.

Certificate Authority

Add a new certificate from a trusted Certificate Authority. If more than one CA are included in the PKI profile, then a client’s certificate should match one of them to be valid. A client’s certificate must match the CA as the root of the chain. If the presented certificate has an intermediate chain, then each link in the chain must be included here. Enable Ignore Peer Chain to ignore intermediate validation checking.

Certificate Revocation List

The CRL allows invalidation of certificates (serial number). The revocation list may be updated by manually uploading a new CRL, or by periodically downloading from a CRL server. If a client or server certificate is found to be in the CRL, the SSL handshake will fail, with a resulting log created to provide further information about the handshake.

  • Leaf Certificate CRL validation only — When enabled, Avi Vantage will only validate the leaf certificate against the CRL. The leaf is the next certificate in the chain up from the client certificate. A chain may consist of multiple certificates. To validate all certificates against the CRL, disable this option. Disabling this option means you need to upload all the CRLs issued by each certificate in the chain. Even if one CRL is missing, the validation process will fail.
  • Server URL — Specify a server from which CRL updates can be downloaded. Access to this server will be done from the Avi Controller IP addresses, which means they will require firewall access to this destination. The CRL server may be identified by an IP address or a fully qualified domain name (FQDN) along with an HTTP path, such as https://www.avinetworks.com/crl.
  • Refresh Time — Enter the time (in minutes) after which Avi Vantage checks for a CRL update and automatically downloads an updated version of the CRL. For more information, see more.
  • Upload Certificate Revocation List File — Navigate to a CRL file for upload. Subsequent CRL updates can be done by manually uploading newer lists, or configuring the Server URL and Refresh Time to automate the process.

Refresh Time

Avi Vantage checks for a CRL update and automatically downloads an updated version of the CRL on a regular schedule starting from the time of the creation of the PKI Profile.

Avi Vantage checks the CRL distribution point for a new CRL at the configured Refresh Interval. If no Refresh Interval is configured or if the Refresh Interval is greater than 1440 minutes (one day), then an interval of 1440 minutes is used.

The CRL Distribution Server should support ETag semantics. Avi Vantage checks the CRL distribution point using the If-None-Match option and ETag obtained from the last downloaded CRL response. If the CRL has not been modified, the server responds with 304 Not Modified and no further action is taken until the next refresh interval.

In general, most Certificate Authorities update CRLs on a known regular schedule but in some cases CRL publishing intervals may be variable and the expiry (Next Update) time for a given CRL can also vary. The Refresh Interval should be configured such that Avi Vantage checks for an updated CRL with sufficient frequency to ensure the CRL will never expire.

If the expiry (Next Update) time of the CRL is passed without a new CRL being downloaded, the CRL will become invalid and Avi Vantage will fail close and treat all submitted certificates as untrusted. Override this behavior by deferring the certificate validation to a DataScript and treating the expired CRL condition as fail open. See Avi SSL Client Cert Validation.

If the Avi Controller is rebooted or is down for a period of time then upon reboot the Controller will resume the regular refresh schedule using the last_refreshed time stored in the PKI Profile. If the Controller comes back online after being down for an extended period such that one or more scheduled refresh intervals have been missed (based on the last_refreshed timestamp and configured refresh interval in the PKI Profile), then the Controller will immediately check for an updated CRL.

Date Change Summary
December 20, 2021 Updated HTTP Headers section mentioning about SSL client details for 21.1.3