$ssl_ech_status

Description

The $ssl_ech_status variable is set within the context of an SSL connection that supports Encrypted ClientHello (ECH). It communicates the client's ECH status as determined during the SSL handshake process. The variable can return various values indicating whether ECH was used or if there were any errors related to its use during the handshake. Common values include 'on' if ECH was successfully negotiated, 'off' if it was not supported by the client, and error codes for other specific issues. The handling of this variable happens when the NGINX server is configured with SSL and ECH support enabled. When a client connects and attempts to initiate an ECH handshake, the server evaluates the request and sets the $ssl_ech_status accordingly. This allows webmasters to implement fine-grained access control or customize responses based on the status of ECH, thus enhancing the privacy features offered to clients that support it. In practice, the variable is useful for logging or for writing conditions in configuration files that can tailor responses depending on client support for encryption. This might involve customizing the behavior of application servers or even redirecting clients based on their security capabilities.

Config Example

server {
    listen 443 ssl;
    ssl_certificate /etc/ssl/cert.pem;
    ssl_certificate_key /etc/ssl/key.pem;
    
    location / {
        if ($ssl_ech_status = 'on') {
            add_header X-ECH-Status 'Enabled';
        }
        if ($ssl_ech_status = 'off') {
            return 403;
        }
    }
}