ALOHA 7.0


Handling SSL/TLS

Before starting

SSL/TLS is quite complicated to understand and introduces a lot of new keywords.

It is recommended to read the SSL/TLS glossary at the end of this page to get a better understanding of these new notions.

Managing TLS/SSL certificates

Browse the SSL tab of the ALOHA Load-Balancer GUI, then follow instructions to manage SSLT/LS certificates

Configuring HAProxy for SSL/TLS

This chapter introduces all the keywords related to TLS/SSL available in HAProxy.

Global section settings

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

    string which describes the list of cipher suite algorithms supported by HAProxy. It applies to all bind where ssl is enabled

    Note

    Mozilla proposes a page with modern, intermediate and old backward compatibility cipher lists: Mozilla TLS recommended configurations . Just copy/paste the one you need.

  • ssl-default-bind-options [<option>]... :

    SSL/TLS options to apply to all bind lines where ssl is enabled. <options> are the one from the frontend bind directive

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

    string which describes the list of cipher suite algorithms. It applies to all server where ssl is enabled

    Note

    Mozilla proposes a page with modern, intermediate and old backward compatibility cipher lists: Mozilla TLS recommended configurations . Just copy/paste the one you need.

  • ssl-default-server-options [<option>]... :

    SSL/TLS options to apply to all bind lines where ssl is enabled. <options> are the one from the backend server directive

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

    default behavior for TLS connection verification on the server side. When set to none, certificate errors are ignored.

    Default is required, which means in case of error, HAProxy refuses the connection to a server if its certificate is in error (selfsigned, outdated, etc…).

  • tune.ssl.cachesize <number> :

    Sets the size of the global SSL/TLS session cache. Default number is 20000.
    When the cache is full and a new entry is required, the least recently used entry is removed.

  • tune.ssl.lifetime <timeout> :

    Sets the life time of a SSL/TLS session in the cache. timeout is expressed in seconds, and its default value is 300 (5 minutes). After timeout, the session is purged from the cache and a new one is generated.

  • tune.ssl.maxrecord <number> :

    Sets the maximum <number> of bytes passed to the SSL/TLS layer at a time. By default <number> is 0, means no limit.

    The client can’t start deciphering the stream until it has received a full segment. Reducing this value may improve application response time on the client side.

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

    Sets the maximum size of the Diffie-Hellman parameters used to generate the ephemeral/temporary Diffie-Hellman key when DHE key exchange is used. Default <number> value is 1024. Higher value increases CPU load and may not be supported by some clients (IE: Java 7).

frontend: bind directive settings

The following directives are valid only if bind line also owns the statement ssl:

  • alpn <protocols> :

    Enables the TLS ALPN extension and advertises the <protocol> list (comma separated) supported by HAProxy itself and/or the server behind.

  • ca-file <ca-file> :

    Designates the CA certificate to use in order to validate certificates provided by clients

  • ca-ignore-err all|<errorid>,... :

    Sets a list of TLS error IDs to ignore when performing TLS handshakes at depth > 0. The TLS handshake is aborted when an error occurs.

    By default, no errors are ignored. When all is set, then all errors are ignore.

    Note

    the SSL handshake is ignored when an error is encountered.

  • ciphers :

    string describing the list of cipher suite algorithms

    Note

    Mozilla proposes a page with modern, intermediate and old backward compatibility cipher lists: Mozilla TLS recommended configurations . Just copy/paste the one you need.

  • crl-file <crlfile> :

    Designates a PEM file from which HAProxy can load ca certificate revocation list. The list is used to verify client certificates.

  • crt <pem-file> :

    Designates the file containing the certificate and its associated private key. Possibly, intermediaries and root certificates may be included as well. The <pem-file> format is PEM.

    Multiple crt <pem-file> certificates are loaded, then HAProxy use the SNI provided by the client to pick-up the best one. If no SNI is provided, then the default certificate is loaded. The default certificate is the first one in the list.

  • crt-ignore-err all|<errorid>,... :

    Sets a list of TLS errorIDs to ignore during verification of at depth 0. <errors> is a comma separated list.

    By default, no error is ignored. When all is used, all errors are ignored.

    Note

    the SSL handshake is ignored when an error is encountered.

  • crt-list <file> [[!]<snifilter ...] :

    Designates a file which contains a list of PEM file certificate and associated optional list of SNI filters.

    Each line in <file> follows the following scheme: <pemfile> [[!]<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.

  • force-sslv3 :

    Enforces the use of SSL protocol version SSLv3.

    Note

    Not recommended on Internet because of the poodle vulnerability: https://poodle.io/

  • force-tlsv10 :

    Enforces the use of TLS protocol version 1.0

  • force-tlsv11 :

    Enforces the use of TLS protocol version 1.1

  • force-tlsv12 :

    Enforces the use of TLS protocol version 1.2

  • no-sslv3 :

    Disables support of SSLv3 protocol

  • no-tls-tickets :

    Disables support of TLS tickets, used to resume TLS sessions with compatible clients

  • no-tlsv10 :

    Disables support of TLS 1.0 protocol

  • no-tlsv11 :

    Disables support of TLS 1.1 protocol

  • no-tlsv12 :

    Disables support of TLS 1.2 protocol

  • ssl :

    Enables a TLS/SSL endpoint on this listener in order to cipher/decipher the traffic.

  • strict-sni :

    The SSL/TLS negotiation is allowed only if the client provides a SNI which matches a certificate loaded by HAProxy.

    The default certificate is ignored in such case.

  • verify [none|optional|required] :

    Sets HAProxy‘s behavior regarding client side certificate:

    • none (default value) : client certificate is not requested
    • optional: A client certificate is requested by HAProxy, and TLS handshake is successful even if the client doesn’t provide one
    • required: A client certificate is requested by HAProxy, and TLS handshake is aborted if the client doesn’t provide one

backend: server directive settings

  • ca-file <ca-file> :

    Designates the CA certificate to use in order to validate certificates provided by servers

  • ciphers :

    string describing the list of cipher suite algorithms to use to get connected to the servers

    Note

    Mozilla proposes a page with modern, intermediate and old backward compatibility cipher lists: Mozilla TLS recommended configurations . Just copy/paste the one you need.

  • crl-file <crlfile> :

    Designates a PEM file from which HAProxy can load a certificate revocation list. The list is used to verify certificates provided by servers.

  • crt <pem-file> :

    Designates the file containing a client certificate and its associated private key. HAProxy will use it if the server asks for a client certificate.

  • force-sslv3 :

    Enforces the use of SSL protocol version SSLv3.

    Note

    Not recommended on Internet because of the poodle vulnerability: https://poodle.io/

  • force-tlsv10 :

    Enforces the use of TLS protocol version 1.0

  • force-tlsv11 :

    Enforces the use of TLS protocol version 1.1

  • force-tlsv12 :

    Enforces the use of TLS protocol version 1.2

  • no-sslv3 :

    Disables support of SSLv3 protocol

  • no-tls-tickets :

    Disables support of TLS tickets, used to resume TLS sessions with compatible clients

  • no-tlsv10 :

    Disables support of TLS 1.0 protocol

  • no-tlsv11 :

    Disables support of TLS 1.1 protocol

  • no-tlsv12 :

    Disables support of TLS 1.2 protocol

  • ssl :

    Creates a TLS/SSL socket when connecting to this server in order to cipher/decipher the traffic

  • verify [none|required] :

    Sets HAProxy‘s behavior regarding the certificated presented by the server:

    • none : doesn’t verify the certificate of the server
    • required (default value) : TLS handshake is aborted if the validation of the certificate presented by the server returns an error.

    Note

    The certificate of the server is validated using the server’s ca-file and crl-file directive.

  • veryfyhost <hostname> :

    Sets a <hostname> to look for in the Subject and SubjectAlternateNames fields provided in the certificate sent by the server. If <hostname> can’t be found, then the TLS handshake is aborted.

    Note

    only applies when verify required is configured

Configuration examples

SSL/TLS architectures

A guide which summarizes the SSL/TLS architectures doable with HAProxy is available.

Global settings

Examples involving the settings available in the global section:

  1. Disable SSLv3 everywhere:

    global
     ssl-default-bind-options no-sslv3
    
  2. Default cipher list to use:

    global
     ssl-default-bind-ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK
    
  3. Disable validation of certificates presented by servers (because of self-signed certificates):

    global
     ssl-server-verify none
    
  4. Force validation of certificates presented by servers:

    global
     ssl-server-verify required
    
  5. Increase TLS session cache size and lifetime to avoid computing too many symmetric keys:

    global
     tune.ssl.cachesize 100000
     tune.ssl.lifetime 600
    
  6. Set up a TLS record to match a TCP segment size, in order to improve client side rendering of content:

    global
     tune.ssl.maxrecord 1460
    

Listener settings

  1. Enable SSL processing on a bind line:

    frontend f_myapp
     bind 10.0.0.1:443 ssl crt mycrt
    
  2. Anounce supported protocols using TLS NPN or ALPN extension:

    frontend f_myapp
     bind 10.0.0.1:443 ssl crt mycrt alpn http/1.1,http/1.0
    

    or:

    frontend f_myapp
     bind 10.0.0.1:443 ssl crt mycrt npn http/1.1,http/1.0
    
  3. Enable SSL processing on a bind line and make client certificate mandatory for the connection:

    frontend f_myapp
     bind 10.0.0.1:443 ssl crt mycrt ca-file ./ca.crt verify required
    
  4. Load multiple certificates over a single IP:

    frontend f_myapp
     bind 10.0.0.1:443 ssl crt star.mydomain.com crt www.mydomain.net
    

    Note

    first one is use by default when the client doesn’t send any SNI or the SNI sent doesn’t match any loaded certificate

Server side settings

  1. don’t check the validity of a server ceritificate (could be dangerous):

    backend b_myapp
     [...]
     server app1 10.0.0.1:443 ssl verify none
    

    Note

    By default, the ALOHA does not verify server’s certificate.

  2. Use a company’s internal CA to check a server certificate:

    By default, the ALOHA does not verify server’s certificate, that’s why the verify option is set.
    Please also check the ssl-server-verify global option to force validation over all servers by default.

    backend b_myapp
     [...]
     server app1 10.0.0.1:443 ssl verify required ca-file /etc/haproxy/myca.pem
    
  3. Use a client certificate to get connected on a server:

    By default, the ALOHA does not verify server’s certificate, that’s why the verify option is set.
    Please also check the ssl-server-verify global option to force validation over all servers by default.

    backend b_myapp
     [...]
     server app1 10.0.0.1:443 ssl verify required ca-file /etc/haproxy/myca.pem crt /etc/haproxy/client.pem
    

    Note

    Please also check the ssl-server-verify global option

SSL/TLS glossary

  • certificate : This is a digital certificate which certifies the ownership of a public key by the named subject of the certificate. This allows third parties to rely upon signatures or on assertions made by the private key that corresponds to the certified public key
  • certificate authority : this is an entity that issues digital certificates
  • cipher suite : string describing the protocol used for key exchange, data ciphering and data integrity negotiated by two peers of a TLS connection
  • TLS extension : An extension made to the TLS protocol to add more features
  • private key : key generated and owned by the certificate owner. Used to generate certificate requests and during the establishment of a TLS connection
  • public key : key associated to the private key and sent to a client in order to create the TLS connection
  • Session ID : A unique ID which identifies the TLS session. Can be used to resume a previous session, avoiding a full heavy TLS handshake
  • SNI : Stands for Server Name Indication. It’s a string which contains the name of the service the client is trying to reach (usually, web browsers use the Host header). It is used by the server to present the right certificate and to host multiple certificates over the same IP address
  • SSL : Stands for Secured Socket Layer. Early and legacy name of the TLS protocol
  • symmetric key : A key generated during the TLS connection handshake phase using the public key (client) and the private key (server). A session id is associated to this key.
  • TLS : Stands for Transport Layer Security. New name of the SSL protocol