SearchVarnish Enterprise
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.
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());
}
}
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());
}
}
BOOL is_tls()
Indicates whether the peer is connected over an SSL/TLS connection.
Arguments: None
Type: Function
Returns: Bool
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING version()
Returns the TLS version in use for this connection. E.g. “TLSv1.2”.
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING ja3()
Returns the ja3 fingerprint for this connection if the tls_ja3 parameter
has been enabled.
MD5 fingerprint can be calculated using digest.hash_md5(tls.ja3());
Arguments: None
Type: Function
Returns: String
STRING cipher()
Returns the cipher that was chosen during the TLS handshake.
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING authority()
Returns the hostname presented for Server Name Indication (SNI).
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
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
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING cert_sign()
Certificate signature algorithm. E.g. “SHA256”.
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING cert_key()
The algorithm used to generate the certificate. E.g. “RSA2048”.
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
BOOL client_verified()
Returns True if client provided a certificate and the certificate verification succeded.
Arguments: None
Type: Function
Returns: Bool
Restricted to: client
STRING client_cert()
If the client provided a certificate, this will return the subject name of that certificate. Otherwise returns NULL if no client certificate was provided.
This function may also be used in vcl_backend_response where it will return the subject name of the client certificate for the current backend connection, if any.
Arguments: None
Type: Function
Returns: String
Restricted to: client, vcl_backend_response, vcl_pipe, vcl_connect
STRING ktls_provider(ENUM {delivery, fetch, connection} path = delivery)
Kernel TLS (kTLS) is a method to offload the symmetric encryption to the kernel and if possible offload it all the way to the Network Interface Card (NIC).
This function can be used to check if such offloading is enabled and if so which provider is being used.
This function will always return “none” unless the experimental bit
ktls_openssl was set when the client connection was accepted, and kTLS was
successfully initiated by an OpenSSL version that supports it.
The path can be used to select which direction to test for kTLS. By default,
delivery tests if kTLS data-path for sending is used. fetch can be used
to test if kTLS data-path for receving is used. While connection returns
“none” if either direction does not supports kTLS.
Possible return values: “none”, “openssl”.
Other return values could be added in the future.
Arguments:
path is an ENUM that accepts values of delivery, fetch, and connection with a default value of delivery optional
Type: Function
Returns: String
Restricted to: client
The tls VMOD is available in Varnish Enterprise version 6.0.6r5 and later.