HaProxy

TLS

(3.1) Process management and security

• ca-base <dir>:

  • Assigns a default directory to fetch SSL CA certificates and CRLs from when a
    relative path is used with "ca-file" or "crl-file" directives. Absolute
    locations specified in "ca-file" and "crl-file" prevail and ignore "ca-base".

• crt-base <dir>:

  • Assigns a default directory to fetch SSL certificates from when a relative
    path is used with "crtfile" directives. Absolute locations specified after
    "crtfile" prevail and ignore "crt-base".

• ca-file <cafile>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a PEM file from which to load CA certificates used to verify
    client's certificate.

• ca-ignore-err [all|<errorID>,...]:

  • This setting is only available when support for OpenSSL was built in.
    Sets a comma separated list of errorIDs to ignore during verify at depth > 0.
    If set to 'all', all errors are ignored. SSL handshake is not aborted if an
    error is ignored.

• ciphers <ciphers>:

  • This setting is only available when support for OpenSSL was built in. It sets
    the string describing the list of cipher algorithms ("cipher suite") that are
    negotiated during the SSL/TLS handshake. The format of the string is defined
    in "man 1 ciphers" from OpenSSL man pages, and can be for instance a string
    such as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes).

• crl-file <crlfile>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a PEM file from which to load certificate revocation list used
    to verify client's certificate.

• crt <cert>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a PEM file containing both the required certificates and any
    associated private keys. This file can be built by concatenating multiple
    PEM files into one (e.g. cat cert.pem key.pem > combined.pem). If your CA
    requires an intermediate certificate, this can also be concatenated into this
    file.
    
    If the OpenSSL used supports Diffie-Hellman, parameters present in this file
    are loaded.
    
    If a directory name is used instead of a PEM file, then all files found in
    that directory will be loaded unless their name ends with '.issuer' or
    '.ocsp' (reserved extensions). This directive may be specified multiple times
    in order to load certificates from multiple files or directories. The
    certificates will be presented to clients who provide a valid TLS Server Name
    Indication field matching one of their CN or alt subjects. Wildcards are
    supported, where a wildcard character '*' is used instead of the first
    hostname component (eg: *.example.org matches www.example.org but not
    www.sub.example.org).
    
    If no SNI is provided by the client or if the SSL library does not support
    TLS extensions, or if the client provides an SNI hostname which does not
    match any certificate, then the first loaded certificate will be presented.
    This means that when loading certificates from a directory, it is highly
    recommended to load the default one first as a file.
    
    Note that the same cert may be loaded multiple times without side effects.
    
    Some CAs (such as Godaddy) offer a drop down list of server types that do not
    include HAProxy when obtaining a certificate. If this happens be sure to
    choose a webserver that the CA believes requires an intermediate CA (for
    Godaddy, selection Apache Tomcat will get the correct bundle, but many
    others, e.g. nginx, result in a wrong bundle that will not work for some
    clients).
    
    For each PEM file, haproxy checks for the presence of file at the same path
    suffixed by ".ocsp". If such file is found, support for the TLS Certificate
    Status Request extension (also known as "OCSP stapling") is automatically
    enabled. The content of this file is optional. If not empty, it must contain
    a valid OCSP Response in DER format. In order to be valid an OCSP Response
    must comply with the following rules: it has to indicate a good status,
    it has to be a single response for the certificate of the PEM file, and it
    has to be valid at the moment of addition. If these rules are not respected
    the OCSP Response is ignored and a warning is emitted. In order to  identify
    which certificate an OCSP Response applies to, the issuer's certificate is
    necessary. If the issuer's certificate is not found in the PEM file, it will
    be loaded from a file at the same path as the PEM file suffixed by ".issuer"
    if it exists otherwise it will fail with an error.

• crt-ignore-err <errors>:

  • This setting is only available when support for OpenSSL was built in. Sets a
    comma separated list of errorIDs to ignore during verify at depth == 0.  If
    set to 'all', all errors are ignored. SSL handshake is not aborted if an error
    is ignored.

• crt-list <file>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a list of PEM file with an optional list of SNI filter per
    certificate, with the following format for each line :
    
        <crtfile> [[!]<snifilter> ...]
    
    Wildcards are supported in the SNI filter. Negative filter are also supported,
    only useful in combination with a wildcard filter to exclude a particular SNI.
    The certificates will be presented to clients who provide a valid TLS Server
    Name Indication field matching one of the SNI filters. If no SNI filter is
    specified, the CN and alt subjects are used. This directive may be specified
    multiple times. See the "crt" option for more information. The default
    certificate is still needed to meet OpenSSL expectations. If it is not used,
    the 'strict-sni' option may be used.

• crtfile: ???;

• force-sslv3:

  • This option enforces use of SSLv3 only on SSL connections instantiated from
    this listener. SSLv3 is generally less expensive than the TLS counterparts
    for high connection rates. See also "force-tls*", "no-sslv3", and "no-tls*".

• force-tlsv10:

  • This option enforces use of TLSv1.0 only on SSL connections instantiated from
    this listener. See also "force-tls*", "no-sslv3", and "no-tls*".

• force-tlsv11:

  • This option enforces use of TLSv1.1 only on SSL connections instantiated from
    this listener. See also "force-tls*", "no-sslv3", and "no-tls*".

• force-tlsv12:

  • This option enforces use of TLSv1.2 only on SSL connections instantiated from
    this listener. See also "force-tls*", "no-sslv3", and "no-tls*".

• no-sslv3:

  • This setting is only available when support for OpenSSL was built in. It
    disables support for SSLv3 on any sockets instantiated from the listener when
    SSL is supported. Note that SSLv2 is forced disabled in the code and cannot
    be enabled using any configuration option. See also "force-tls*",
    and "force-sslv3".

• no-tls-tickets:

  • This setting is only available when support for OpenSSL was built in. It
    disables the stateless session resumption (RFC 5077 TLS Ticket
    extension) and force to use stateful session resumption. Stateless
    session resumption is more expensive in CPU usage.

• no-tlsv10:

  • This setting is only available when support for OpenSSL was built in. It
    disables support for TLSv1.0 on any sockets instantiated from the listener
    when SSL is supported. Note that SSLv2 is forced disabled in the code and
    cannot be enabled using any configuration option. See also "force-tls*",
    and "force-sslv3".

• no-tlsv11:

  • This setting is only available when support for OpenSSL was built in. It
    disables support for TLSv1.1 on any sockets instantiated from the listener
    when SSL is supported. Note that SSLv2 is forced disabled in the code and
    cannot be enabled using any configuration option. See also "force-tls*",
    and "force-sslv3".

• no-tlsv12:

  • This setting is only available when support for OpenSSL was built in. It
    disables support for TLSv1.2 on any sockets instantiated from the listener
    when SSL is supported. Note that SSLv2 is forced disabled in the code and
    cannot be enabled using any configuration option. See also "force-tls*",
    and "force-sslv3".

• npn <protocols>:

  • This enables the NPN TLS extension and advertises the specified protocol list
    as supported on top of NPN. The protocol list consists in a comma-delimited
    list of protocol names, for instance: "http/1.1,http/1.0" (without quotes).
    This requires that the SSL library is build with support for TLS extensions
    enabled (check with haproxy -vv). Note that the NPN extension has been
    replaced with the ALPN extension (see the "alpn" keyword).

• ssl:

  • This setting is only available when support for OpenSSL was built in. It
    enables SSL deciphering on connections instantiated from this listener. A
    certificate is necessary (see "crt" above). All contents in the buffers will
    appear in clear text, so that ACLs and HTTP processing will only have access
    to deciphered contents.

• strict-sni:

  • This setting is only available when support for OpenSSL was built in. The
    SSL/TLS negotiation is allow only if the client provided an SNI which match
    a certificate. The default certificate is not used.
    See the "crt" option for more information.

• verify [none|optional|required]:

  • This setting is only available when support for OpenSSL was built in. If set
    to 'none', client certificate is not requested. This is the default. In other
    cases, a client certificate is requested. If the client does not provide a
    certificate after the request and if 'verify' is set to 'required', then the
    handshake is aborted, while it would have succeeded if set to 'optional'. The
    certificate provided by the client is always verified using CAs from
    'ca-file' and optional CRLs from 'crl-file'. On verify failure the handshake
    is aborted, regardless of the 'verify' option, unless the error code exactly
    matches one of those listed with 'ca-ignore-err' or 'crt-ignore-err'.

(5.2) Server and default-server options

• ca-file <cafile>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a PEM file from which to load CA certificates used to verify
    server's certificate.
    
    Supported in default-server: No

• check-ssl:

  • This option forces encryption of all health checks over SSL, regardless of
    whether the server uses SSL or not for the normal traffic. This is generally
    used when an explicit "port" or "addr" directive is specified and SSL health
    checks are not inherited. It is important to understand that this option
    inserts an SSL transport layer below the checks, so that a simple TCP connect
    check becomes an SSL connect, which replaces the old ssl-hello-chk. The most
    common use is to send HTTPS checks by combining "httpchk" with SSL checks.
    All SSL settings are common to health checks and traffic (eg: ciphers).
    See the "ssl" option for more information.
    
    Supported in default-server: No

• ciphers <ciphers>:

  • This option sets the string describing the list of cipher algorithms that is
    is negotiated during the SSL/TLS handshake with the server. The format of the
    string is defined in "man 1 ciphers". When SSL is used to communicate with
    servers on the local network, it is common to see a weaker set of algorithms
    than what is used over the internet. Doing so reduces CPU usage on both the
    server and haproxy while still keeping it compatible with deployed software.
    Some algorithms such as RC4-SHA1 are reasonably cheap. If no security at all
    is needed and just connectivity, using DES can be appropriate.
    
    Supported in default-server: No

• crl-file <crlfile>:

  • This setting is only available when support for OpenSSL was built in. It
    designates a PEM file from which to load certificate revocation list used
    to verify server's certificate.
    
    Supported in default-server: No

• crt <cert>:

  • This setting is only available when support for OpenSSL was built in.
    It designates a PEM file from which to load both a certificate and the
    associated private key. This file can be built by concatenating both PEM
    files into one. This certificate will be sent if the server send a client
    certificate request.
    
    Supported in default-server: No

• force-sslv3:

  • This option enforces use of SSLv3 only when SSL is used to communicate with
    the server. SSLv3 is generally less expensive than the TLS counterparts for
    high connection rates. See also "no-tlsv*", "no-sslv3".
    
    Supported in default-server: No

• force-tlsv10:

  • This option enforces use of TLSv1.0 only when SSL is used to communicate with
    the server. See also "no-tlsv*", "no-sslv3".
    
    Supported in default-server: No

• force-tlsv11:

  • This option enforces use of TLSv1.1 only when SSL is used to communicate with
    the server. See also "no-tlsv*", "no-sslv3".
    
    Supported in default-server: No

• force-tlsv12:

  • This option enforces use of TLSv1.2 only when SSL is used to communicate with
    the server. See also "no-tlsv*", "no-sslv3".
    
    Supported in default-server: No

• no-sslv3:

  • This option disables support for SSLv3 when SSL is used to communicate with
    the server. Note that SSLv2 is disabled in the code and cannot be enabled
    using any configuration option. See also "force-sslv3", "force-tlsv*".
    
    Supported in default-server: No

• no-tls-tickets:

  • This setting is only available when support for OpenSSL was built in. It
    disables the stateless session resumption (RFC 5077 TLS Ticket
    extension) and force to use stateful session resumption. Stateless
    session resumption is more expensive in CPU usage for servers.
    
    Supported in default-server: No

• no-tlsv10:

  • This option disables support for TLSv1.0 when SSL is used to communicate with
    the server. Note that SSLv2 is disabled in the code and cannot be enabled
    using any configuration option. TLSv1 is more expensive than SSLv3 so it
    often makes sense to disable it when communicating with local servers. See
    also "force-sslv3", "force-tlsv*".
    
    Supported in default-server: No

• no-tlsv11:

  • This option disables support for TLSv1.1 when SSL is used to communicate with
    the server. Note that SSLv2 is disabled in the code and cannot be enabled
    using any configuration option. TLSv1 is more expensive than SSLv3 so it
    often makes sense to disable it when communicating with local servers. See
    also "force-sslv3", "force-tlsv*".
    
    Supported in default-server: No

• no-tlsv12:

  • This option disables support for TLSv1.2 when SSL is used to communicate with
    the server. Note that SSLv2 is disabled in the code and cannot be enabled
    using any configuration option. TLSv1 is more expensive than SSLv3 so it
    often makes sense to disable it when communicating with local servers. See
    also "force-sslv3", "force-tlsv*".
    
    Supported in default-server: No

• ssl:

  • This option enables SSL ciphering on outgoing connections to the server. It
    is critical to verify server certificates using "verify" when using SSL to
    connect to servers, otherwise the communication is prone to trivial man in
    the-middle attacks rendering SSL useless. When this option is used, health
    checks are automatically sent in SSL too unless there is a "port" or an
    "addr" directive indicating the check should be sent to a different location.
    See the "check-ssl" option to force SSL health checks.
    
    Supported in default-server: No

• verify [none|required]:

  • This setting is only available when support for OpenSSL was built in. If set
    to 'none', server certificate is not verified. In the other case, The
    certificate provided by the server is verified using CAs from 'ca-file'
    and optional CRLs from 'crl-file'. If 'ssl_server_verify' is not specified
    in global  section, this is the default. On verify failure the handshake
    is aborted. It is critically important to verify server certificates when
    using SSL to connect to servers, otherwise the communication is prone to
    trivial man-in-the-middle attacks rendering SSL totally useless.
    
    Supported in default-server: No

• verifyhost <hostname>:

  • This setting is only available when support for OpenSSL was built in, and
    only takes effect if 'verify required' is also specified. When set, the
    hostnames in the subject and subjectAlternateNames of the certificate
    provided by the server are checked. If none of the hostnames in the
    certificate match the specified hostname, the handshake is aborted. The
    hostnames in the server-provided certificate may include wildcards.
    
    Supported in default-server: No

(7.3.4) Fetching samples at Layer 5

• ssl_bc : boolean:

  • Returns true when the back connection was made via an SSL/TLS transport
    layer and is locally deciphered. This means the outgoing connection was made
    other a server with the "ssl" option.

• ssl_bc_alg_keysize : integer:

  • Returns the symmetric cipher key size supported in bits when the outgoing
    connection was made over an SSL/TLS transport layer.

• ssl_bc_cipher : string:

  • Returns the name of the used cipher when the outgoing connection was made
    over an SSL/TLS transport layer.

• ssl_bc_protocol : string:

  • Returns the name of the used protocol when the outgoing connection was made
    over an SSL/TLS transport layer.

• ssl_bc_unique_id : binary:

  • When the outgoing connection was made over an SSL/TLS transport layer,
    returns the TLS unique ID as defined in RFC5929 section 3. The unique id
    can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".

• ssl_bc_session_id : binary:

  • Returns the SSL ID of the back connection when the outgoing connection was
    made over an SSL/TLS transport layer. It is useful to log if we want to know
    if session was reused or not.

• ssl_bc_use_keysize : integer:

  • Returns the symmetric cipher key size used in bits when the outgoing
    connection was made over an SSL/TLS transport layer.

• ssl_c_ca_err : integer:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the ID of the first error detected during verification of the client
    certificate at depth > 0, or 0 if no error was encountered during this
    verification process. Please refer to your SSL library's documentation to
    find the exhaustive list of error codes.

• ssl_c_ca_err_depth : integer:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the depth in the CA chain of the first error detected during the
    verification of the client certificate. If no error is encountered, 0 is
    returned.

• ssl_c_err : integer:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the ID of the first error detected during verification at depth 0, or
    0 if no error was encountered during this verification process. Please refer
    to your SSL library's documentation to find the exhaustive list of error
    codes.

• ssl_c_i_dn([<entry>[,<occ>]]) : string:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the full distinguished name of the issuer of the certificate
    presented by the client when no <entry> is specified, or the value of the
    first given entry found from the beginning of the DN. If a positive/negative
    occurrence number is specified as the optional second argument, it returns
    the value of the nth given entry value from the beginning/end of the DN.
    For instance, "ssl_c_i_dn(OU,2)" the second organization unit, and
    "ssl_c_i_dn(CN)" retrieves the common name.

• ssl_c_key_alg : string:

  • Returns the name of the algorithm used to generate the key of the certificate
    presented by the client when the incoming connection was made over an SSL/TLS
    transport layer.

• ssl_c_notafter : string:

  • Returns the end date presented by the client as a formatted string
    YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
    transport layer.

• ssl_c_notbefore : string:

  • Returns the start date presented by the client as a formatted string
    YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
    transport layer.

• ssl_c_s_dn([<entry>[,<occ>]]) : string:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the full distinguished name of the subject of the certificate
    presented by the client when no <entry> is specified, or the value of the
    first given entry found from the beginning of the DN. If a positive/negative
    occurrence number is specified as the optional second argument, it returns
    the value of the nth given entry value from the beginning/end of the DN.
    For instance, "ssl_c_s_dn(OU,2)" the second organization unit, and
    "ssl_c_s_dn(CN)" retrieves the common name.

• ssl_c_serial : binary:

  • Returns the serial of the certificate presented by the client when the
    incoming connection was made over an SSL/TLS transport layer. When used for
    an ACL, the value(s) to match against can be passed in hexadecimal form.

• ssl_c_sha1 : binary:

  • Returns the SHA-1 fingerprint of the certificate presented by the client when
    the incoming connection was made over an SSL/TLS transport layer. This can be
    used to stick a client to a server, or to pass this information to a server.
    Note that the output is binary, so if you want to pass that signature to the
    server, you need to encode it in hex or base64, such as in the example below:
    
        http-request set-header X-SSL-Client-SHA1 %[ssl_c_sha1,hex]

• ssl_c_sig_alg : string:

  • Returns the name of the algorithm used to sign the certificate presented by
    the client when the incoming connection was made over an SSL/TLS transport
    layer.

• ssl_c_used : boolean:

  • Returns true if current SSL session uses a client certificate even if current
    connection uses SSL session resumption. See also "ssl_fc_has_crt".

• ssl_c_verify : integer:

  • Returns the verify result error ID when the incoming connection was made over
    an SSL/TLS transport layer, otherwise zero if no error is encountered. Please
    refer to your SSL library's documentation for an exhaustive list of error
    codes.

• ssl_c_version : integer:

  • Returns the version of the certificate presented by the client when the
    incoming connection was made over an SSL/TLS transport layer.

• ssl_f_i_dn([<entry>[,<occ>]]) : string:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the full distinguished name of the issuer of the certificate
    presented by the frontend when no <entry> is specified, or the value of the
    first given entry found from the beginning of the DN. If a positive/negative
    occurrence number is specified as the optional second argument, it returns
    the value of the nth given entry value from the beginning/end of the DN.
    For instance, "ssl_f_i_dn(OU,2)" the second organization unit, and
    "ssl_f_i_dn(CN)" retrieves the common name.

• ssl_f_key_alg : string:

  • Returns the name of the algorithm used to generate the key of the certificate
    presented by the frontend when the incoming connection was made over an
    SSL/TLS transport layer.

• ssl_f_notafter : string:

  • Returns the end date presented by the frontend as a formatted string
    YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
    transport layer.

• ssl_f_notbefore : string:

  • Returns the start date presented by the frontend as a formatted string
    YYMMDDhhmmss[Z] when the incoming connection was made over an SSL/TLS
    transport layer.

• ssl_f_s_dn([<entry>[,<occ>]]) : string:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the full distinguished name of the subject of the certificate
    presented by the frontend when no <entry> is specified, or the value of the
    first given entry found from the beginning of the DN. If a positive/negative
    occurrence number is specified as the optional second argument, it returns
    the value of the nth given entry value from the beginning/end of the DN.
    For instance, "ssl_f_s_dn(OU,2)" the second organization unit, and
    "ssl_f_s_dn(CN)" retrieves the common name.

• ssl_f_serial : binary:

  • Returns the serial of the certificate presented by the frontend when the
    incoming connection was made over an SSL/TLS transport layer. When used for
    an ACL, the value(s) to match against can be passed in hexadecimal form.

• ssl_f_sha1 : binary:

  • Returns the SHA-1 fingerprint of the certificate presented by the frontend
    when the incoming connection was made over an SSL/TLS transport layer. This
    can be used to know which certificate was chosen using SNI.

• ssl_f_sig_alg : string:

  • Returns the name of the algorithm used to sign the certificate presented by
    the frontend when the incoming connection was made over an SSL/TLS transport
    layer.

• ssl_f_version : integer:

  • Returns the version of the certificate presented by the frontend when the
    incoming connection was made over an SSL/TLS transport layer.

• ssl_fc : boolean:

  • Returns true when the front connection was made via an SSL/TLS transport
    layer and is locally deciphered. This means it has matched a socket declared
    with a "bind" line having the "ssl" option.
    
    Example :
        # This passes "X-Proto: https" to servers when client connects over SSL
        listen http-https
            bind :80
            bind :443 ssl crt /etc/haproxy.pem
            http-request add-header X-Proto https if { ssl_fc }

• ssl_fc_alg_keysize : integer:

  • Returns the symmetric cipher key size supported in bits when the incoming
    connection was made over an SSL/TLS transport layer.

• ssl_fc_alpn : string:

  • This extracts the Application Layer Protocol Negotiation field from an
    incoming connection made via a TLS transport layer and locally deciphered by
    haproxy. The result is a string containing the protocol name advertised by
    the client. The SSL library must have been built with support for TLS
    extensions enabled (check haproxy -vv). Note that the TLS ALPN extension is
    not advertised unless the "alpn" keyword on the "bind" line specifies a
    protocol list. Also, nothing forces the client to pick a protocol from this
    list, any other one may be requested. The TLS ALPN extension is meant to
    replace the TLS NPN extension. See also "ssl_fc_npn".

• ssl_fc_cipher : string:

  • Returns the name of the used cipher when the incoming connection was made
    over an SSL/TLS transport layer.

• ssl_fc_has_crt : boolean:

  • Returns true if a client certificate is present in an incoming connection over
    SSL/TLS transport layer. Useful if 'verify' statement is set to 'optional'.
    Note: on SSL session resumption with Session ID or TLS ticket, client
    certificate is not present in the current connection but may be retrieved
    from the cache or the ticket. So prefer "ssl_c_used" if you want to check if
    current SSL session uses a client certificate.

• ssl_fc_has_sni : boolean:

  • This checks for the presence of a Server Name Indication TLS extension (SNI)
    in an incoming connection was made over an SSL/TLS transport layer. Returns
    true when the incoming connection presents a TLS SNI field. This requires
    that the SSL library is build with support for TLS extensions enabled (check
    haproxy -vv).

• ssl_fc_npn : string:

  • This extracts the Next Protocol Negotiation field from an incoming connection
    made via a TLS transport layer and locally deciphered by haproxy. The result
    is a string containing the protocol name advertised by the client. The SSL
    library must have been built with support for TLS extensions enabled (check
    haproxy -vv). Note that the TLS NPN extension is not advertised unless the
    "npn" keyword on the "bind" line specifies a protocol list. Also, nothing
    forces the client to pick a protocol from this list, any other one may be
    requested. Please note that the TLS NPN extension was replaced with ALPN.

• ssl_fc_protocol : string:

  • Returns the name of the used protocol when the incoming connection was made
    over an SSL/TLS transport layer.

• ssl_fc_unique_id : binary:

  • When the incoming connection was made over an SSL/TLS transport layer,
    returns the TLS unique ID as defined in RFC5929 section 3. The unique id
    can be encoded to base64 using the converter: "ssl_bc_unique_id,base64".

• ssl_fc_session_id : binary:

  • Returns the SSL ID of the front connection when the incoming connection was
    made over an SSL/TLS transport layer. It is useful to stick a given client to
    a server. It is important to note that some browsers refresh their session ID
    every few minutes.

• ssl_fc_sni : string:

  • This extracts the Server Name Indication TLS extension (SNI) field from an
    incoming connection made via an SSL/TLS transport layer and locally
    deciphered by haproxy. The result (when present) typically is a string
    matching the HTTPS host name (253 chars or less). The SSL library must have
    been built with support for TLS extensions enabled (check haproxy -vv).
    
    This fetch is different from "req_ssl_sni" above in that it applies to the
    connection being deciphered by haproxy and not to SSL contents being blindly
    forwarded. See also "ssl_fc_sni_end" and "ssl_fc_sni_reg" below. This
    requires that the SSL library is build with support for TLS extensions
    enabled (check haproxy -vv).
    
    ACL derivatives :
        ssl_fc_sni_end : suffix match
        ssl_fc_sni_reg : regex match

• ssl_fc_use_keysize : integer:

  • Returns the symmetric cipher key size used in bits when the incoming
    connection was made over an SSL/TLS transport layer.

(7.3.5) Fetching samples from buffer contents (Layer 6)

• req.ssl_hello_type : integer / req_ssl_hello_type : integer (deprecated):

  • Returns an integer value containing the type of the SSL hello message found
    in the request buffer if the buffer contains data that parse as a complete
    SSL (v3 or superior) client hello message. Note that this only applies to raw
    contents found in the request buffer and not to contents deciphered via an
    SSL data layer, so this will not work with "bind" lines having the "ssl"
    option. This is mostly used in ACL to detect presence of an SSL hello message
    that is supposed to contain an SSL session ID usable for stickiness.

• req.ssl_sni : string / req_ssl_sni : string (deprecated):

  • Returns a string containing the value of the Server Name TLS extension sent
    by a client in a TLS stream passing through the request buffer if the buffer
    contains data that parse as a complete SSL (v3 or superior) client hello
    message. Note that this only applies to raw contents found in the request
    buffer and not to contents deciphered via an SSL data layer, so this will not
    work with "bind" lines having the "ssl" option. SNI normally contains the
    name of the host the client tries to connect to (for recent browsers). SNI is
    useful for allowing or denying access to certain hosts when SSL/TLS is used
    by the client. This test was designed to be used with TCP request content
    inspection. If content switching is needed, it is recommended to first wait
    for a complete client hello (type 1), like in the example below. See also
    "ssl_fc_sni".
    
    ACL derivatives :
        req_ssl_sni : exact string match
    
    Examples :
        # Wait for a client hello for at most 5 seconds
        tcp-request inspect-delay 5s
        tcp-request content accept if { req_ssl_hello_type 1 }
        use_backend bk_allow if { req_ssl_sni -f allowed_sites }
        default_backend bk_sorry_page

• res.ssl_hello_type : integer / rep_ssl_hello_type : integer (deprecated):

  • Returns an integer value containing the type of the SSL hello message found
    in the response buffer if the buffer contains data that parses as a complete
    SSL (v3 or superior) hello message. Note that this only applies to raw
    contents found in the response buffer and not to contents deciphered via an
    SSL data layer, so this will not work with "server" lines having the "ssl"
    option. This is mostly used in ACL to detect presence of an SSL hello message
    that is supposed to contain an SSL session ID usable for stickiness.

• req.ssl_ver : integer / req_ssl_ver : integer (deprecated):

  • Returns an integer value containing the version of the SSL/TLS protocol of a
    stream present in the request buffer. Both SSLv2 hello messages and SSLv3
    messages are supported. TLSv1 is announced as SSL version 3.1. The value is
    composed of the major version multiplied by 65536, added to the minor
    version. Note that this only applies to raw contents found in the request
    buffer and not to contents deciphered via an SSL data layer, so this will not
    work with "bind" lines having the "ssl" option. The ACL version of the test
    matches against a decimal notation in the form MAJOR.MINOR (eg: 3.1). This
    fetch is mostly used in ACL.
    
    ACL derivatives :
        req_ssl_ver : decimal match

(3) Global parameters

• ssl-server-verify [none|required]:

  • The default behavior for SSL verify on servers side. If specified to 'none',
    servers certificates are not verified. The default is 'required' except if
    forced using cmdline option '-dV'.

• ssl-default-bind-ciphers <ciphers>:

  • This setting is only available when support for OpenSSL was built in. It sets
    the default string describing the list of cipher algorithms ("cipher suite")
    that are negotiated during the SSL/TLS handshake for all "bind" lines which
    do not explicitly define theirs. The format of the string is defined in
    "man 1 ciphers" from OpenSSL man pages, and can be for instance a string such
    as "AES:ALL:!aNULL:!eNULL:+RC4:@STRENGTH" (without quotes). Please check the
    "bind" keyword for more information.

• ssl-default-server-ciphers <ciphers>:

  • This setting is only available when support for OpenSSL was built in. It
    sets the default string describing the list of cipher algorithms that are
    negotiated during the SSL/TLS handshake with the server, for all "server"
    lines which do not explicitly define theirs. The format of the string is
    defined in "man 1 ciphers". Please check the "server" keyword for more
    information.

(5.1) Bind options

• alpn <protocols>:

  • This enables the TLS ALPN extension and advertises the specified protocol
    list as supported on top of ALPN. The protocol list consists in a comma-
    delimited list of protocol names, for instance: "http/1.1,http/1.0" (without
    quotes). This requires that the SSL library is build with support for TLS
    extensions enabled (check with haproxy -vv). The ALPN extension replaces the
    initial NPN extension.

• ecdhe <named curve>:

  • This setting is only available when support for OpenSSL was built in. It sets
    the named curve (RFC 4492) used to generate ECDH ephemeral keys. By default,
    used named curve is prime256v1.

(3.2) Performance tuning

• tune.ssl.cachesize <number>:

  • Sets the size of the global SSL session cache, in a number of blocks. A block
    is large enough to contain an encoded session without peer certificate.
    An encoded session with peer certificate is stored in multiple blocks
    depending on the size of the peer certificate. A block uses approximately
    200 bytes of memory. The default value may be forced at build time, otherwise
    defaults to 20000.  When the cache is full, the most idle entries are purged
    and reassigned. Higher values reduce the occurrence of such a purge, hence
    the number of CPU-intensive SSL handshakes by ensuring that all users keep
    their session as long as possible. All entries are pre-allocated upon startup
    and are shared between all processes if "nbproc" is greater than 1. Setting
    this value to 0 disables the SSL session cache.

• tune.ssl.force-private-cache:

  • This boolean disables SSL session cache sharing between all processes. It
    should normally not be used since it will force many renegotiations due to
    clients hitting a random process. But it may be required on some operating
    systems where none of the SSL cache synchronization method may be used. In
    this case, adding a first layer of hash-based load balancing before the SSL
    layer might limit the impact of the lack of session sharing.

• tune.ssl.lifetime <timeout>:

  • Sets how long a cached SSL session may remain valid. This time is expressed
    in seconds and defaults to 300 (5 min). It is important to understand that it
    does not guarantee that sessions will last that long, because if the cache is
    full, the longest idle sessions will be purged despite their configured
    lifetime. The real usefulness of this setting is to prevent sessions from
    being used for too long.

• tune.ssl.maxrecord <number>:

  • Sets the maximum amount of bytes passed to SSL_write() at a time. Default
    value 0 means there is no limit. Over SSL/TLS, the client can decipher the
    data only once it has received a full record. With large records, it means
    that clients might have to download up to 16kB of data before starting to
    process them. Limiting the value can improve page load times on browsers
    located over high latency or low bandwidth networks. It is suggested to find
    optimal values which fit into 1 or 2 TCP segments (generally 1448 bytes over
    Ethernet with TCP timestamps enabled, or 1460 when timestamps are disabled),
    keeping in mind that SSL/TLS add some overhead. Typical values of 1419 and
    2859 gave good results during tests. Use "strace -e trace=write" to find the
    best value. Haproxy will automatically switch to this setting after an idle
    stream has been detected (see tune.idletimer above).

• tune.ssl.default-dh-param <number>:

  • Sets the maximum size of the Diffie-Hellman parameters used for generating
    the ephemeral/temporary Diffie-Hellman key in case of DHE key exchange. The
    final size will try to match the size of the server's RSA (or DSA) key (e.g,
    a 2048 bits temporary DH key for a 2048 bits RSA key), but will not exceed
    this maximum value. Default value if 1024. Only 1024 or higher values are
    allowed. Higher values will increase the CPU load, and values greater than
    1024 bits are not supported by Java 7 and earlier clients. This value is not
    used if static Diffie-Hellman parameters are supplied via the certificate file.