$ssl_client_serial

Description

The $ssl_client_serial variable is set when NGINX is configured to handle SSL/TLS connections that require client certificates for authentication. It retrieves the serial number of the client's SSL certificate if client verification is enabled, which typically occurs in a server block configured with the "ssl_verify_client" directive set to "on" or "optional". When presented with a valid client certificate during the TLS handshake, NGINX can access various attributes of the certificate, including the serial number, which is a unique identifier for the certificate instance. The value of $ssl_client_serial is often formatted as a hexadecimal string, representing the certificate's serial number. If client verification is not enabled, or if no client certificate is provided by the client, this variable will not be set and will return an empty string. This variable is especially useful for implementing access control, logging, or auditing mechanisms based on the identity of the client certificates being used.

Config Example

server {
    listen 443 ssl;
    ssl_certificate     /path/to/your/server.crt;
    ssl_certificate_key /path/to/your/server.key;
    ssl_verify_client on;

    location / {
        if ($ssl_client_serial) {
            add_header X-Client-Serial $ssl_client_serial;
        }
    }
}