TLS

Description

The tls vmod lets you query details relating to a TLS connection.

If called from one of the client VCL subroutines (e.g. sub vcl_recv or sub vcl_deliver), it will provide details about the client TLS connection.

If called from sub vcl_backend_response, vmod-tls will show details from the currently established TLS backend connection.

Note that the client-side functionality relies on using Varnish’s native TLS implementation. If you are currently terminating TLS in a separate process (for example using Hitch), you should instead use the PROXY VMOD which offers similar functionality.

Examples

Client connection

The following example will report which TLS version and which cipher is used for the client connection.

import tls;

sub vcl_deliver {
  if (tls.is_tls()) {
    # Report cipher and TLS version as a response header
    set resp.http.tls-version = tls.version();
    set resp.http.tls-cipher = tls.cipher();

    # Alternatively, we can log it
    std.log("tls-version: " + tls.version());
    std.log("tls-cipher: " + tls.cipher());
  }
}

Backend connection

The following example will report information about the backend connection. This is only available from sub vcl_backend_response.

import tls;

sub vcl_backend_response {
  if (tls.is_tls()) {
    # Report cipher and TLS version as a backend response header
    set beresp.http.be-tls-version = tls.version();
    set beresp.http.be-tls-cipher = tls.cipher();

    # Also log:
    std.log("backend-tls-version: " + tls.version());
    std.log("backend-tls-cipher: " + tls.cipher());
  }
}

API

is_tls

BOOL is_tls()

Indicates whether the peer is connected over an SSL/TLS connection.

Arguments: None

Type: Function

Returns: Bool

version

STRING version()

Returns the TLS version in use for this connection. E.g. “TLSv1.2”.

Arguments: None

Type: Function

Returns: String

cipher

STRING cipher()

Returns the cipher that was chosen during the TLS handshake.

Arguments: None

Type: Function

Returns: String

authority

STRING authority()

Returns the hostname presented for Server Name Indication (SNI).

Arguments: None

Type: Function

Returns: String

alpn

STRING alpn()

Returns the result of the Application Layer Protocol Negotiation (ALPN). This will contain one of “http/1.1”, “h2” or NULL if no ALPN happened.

Varnish does not currently do ALPN with its backends, so if used in vcl_backend_response this will always return NULL.

Arguments: None

Type: Function

Returns: String

cert_sign

STRING cert_sign()

Certificate signature algorithm. E.g. “SHA256”.

Arguments: None

Type: Function

Returns: String

cert_key

STRING cert_key()

The algorithm used to generate the certificate. E.g. “RSA2048”.

Arguments: None

Type: Function

Returns: String

Availability

The tls VMOD is available in Varnish Cache Plus version 6.0.6r5 and later.