HAProxy Enterprise Documentation 12.5

TLS

The SSL tab in the ALOHA Web user interface allows you to oversee various TLS/SSL-related tasks, such as:

  • List available SSL/TLS certificates

  • Update / delete an existing SSL/TLS certificate

  • Create a new SSL/TLS certificate

List available SSL/TLS certificates

When you open the SSL tab, the ALOHA displays the list of the SSL/TLS certificate it contains, including the following information:

Name

Label used to reference this certificate in HAProxy's configuration

Domain

Common Name (or CN) of the certificate

Not Before

Date from when the certificate is valid

Not After

Date until when the certificate is valid. When a certificate expires, this date appears in bold red.

Verify

State of the validation of the certificate. The following states are available:

Broken chain

When a certificate chain is incomplete or the full chain cannot be validated (outdated intermediary, etc.)

CA only (no key)

When a certificate can be used to validate client certificates only.

Incomplete

When either the private Key and the certificate or the certificate is missing

Valid

When everything is fine and safe

Self-Signed

When the certificate was generated and signed by the ALOHA itself

Example of an SSL tab output:

https://cdn.haproxy.com/documentation/aloha/12-5/assets/ssl_tab_index-fa6796d872d299d91d4d43f3069c43ddfd96889f881c12d16ddf84c46b5dbb8e.png

Create a new SSL/TLS certificate

The creation of a new certificate involves three main steps:

  1. Give a Name to this certificate: this is the reference of this certificate. This name is used in HAProxy's configuration to point to this certificate.

  2. Handle the private key. You have two options:

    • Generation of a new private key

    • Upload of an existing private key

  3. Handle the certificate itself, either by:

    • generating a certificate request (CSR), and then generating a self-signed certificate

    • uploading an existing certificate

Choose a certificate name

  1. Open the SSL tab and click on the new button.

  2. Fill in the box choose SSL certificate name. Only letters, digits and underscore are allowed.

Generate a new private key

  1. Ensure that the button generate a private key is checked.

  2. Choose the size of the new key.

  3. Click on the "Generate" button.

Note

If the certificate will be public facing, we recommend 2048 bits. For internal use, 1024 bits is enough.

Upload an existing private key

  1. Ensure that the button generate a private key is checked.

  2. You can either:

    • Copy/paste the key in the dedicated text area

    • Upload the key using the form below:

      https://cdn.haproxy.com/documentation/aloha/12-5/assets/ssl_tab_upload-d670ee362598b4720b2926d27000c95596bfdaa26919a1520fc80726ee40b8f8.png

      Note

      If the file is password-protected, type the password in the box file or key password.

  3. Click on the "Upload" button.

Generate a certificate request

  1. Ensure the button generate a private key is checked.

  2. Complete the form below:

    https://cdn.haproxy.com/documentation/aloha/12-5/assets/ssl_tab_csr_form_331x123-a66ee467b3950147d555d8b918cbad753a696791719ec0c32caeee30d7b5cdf4.png

    Note

    Only the Domain (CN) is required. However, if the certificate is to be published over the internet, you must complete all information.

  3. Click on the "Request" button.

  4. Copy/paste the CSR and send it to your certification authority to receive the permanent certificate.

    In the meantime, you can start working with a self-signed certificate.

    When your certificate authority replies with the permanent certificate, you can upload the certificate using the form available on the same page, or follow the procedure to update an existing certificate.

Generate a self-signed certificate

  1. Ensure that the radio button auto-sign request is checked.

  2. Choose the number of days you want this self-signed certificate to be valid.

  3. Click on the "Sign" button.

  4. Upload the certificate.

Upload an existing certificate

  1. Ensure that the button upload certificate is checked.

  2. You can either:

    • Copy/paste the certificate in the dedicated text area

    • Upload the key using the form below:

      https://cdn.haproxy.com/documentation/aloha/12-5/assets/ssl_tab_upload1_438x20-1b612ffd3de06ae9a37b7d2aaa3a344a5944e79c4bb16f84fc1d5540cfb83c53.png

      Note

      If the file is password-protected, type the password in the box file or key password.

  3. Click on the "Upload" button.

Create a TLS certificate to validate client certificates

To validate TLS certificates from clients, the ALOHA Load-balancer only needs a TLS certificate and not the associated private key.

  1. Follow the procedure to create a new SSL/TLS certificate.

  2. At the private key generation step, choose a key size of 0 bits.

  3. Upload the certificate.

Update an existing certificate

You may need to update an existing certificate in any of the following cases:

  • When a certificate expires

  • To replace a temporary self-signed certificate with a permanent one from the certification authority

To update an existing certificate:

  1. Open the SSL tab and click on the edit_icon icon.

    Two options are available:

    • Copy/paste the certificate in the dedicated text area and check the button update certificate above.

    • Upload the key using the form below and check its button:

    Note

    If the file is password-protected, type the password in the box file or key password.

  2. Click on the "Upload" button.

Delete an existing certificate

  1. Open the SSL tab and click on the delete_icon icon.

  2. A prompt displays for confirmation. Click on OK.

Manage chained certificates

When a certificate relies on intermediaries and/or a root certificate, it is called a chain.

Generally, you build this chain when a certificate is validated by a certification authority. The certification authority must provide a valid chain.

To update a chain:

  1. Update the certificate

  2. Copy/paste intermediaries and/or root certificates below it. The chain must lo**OK** like this:

    Server certificate
            |
            v
    Intermediary certificate #1
            |
            v
    Intermediary certificate #2
            |
            v
    root certificate
Server certificate

It is the one signed by the certification authority. It is dedicated to host the service.

Other certificates

Are provided by the certification authority. They are used to build a valid chain.

More information

By design, HAProxy is a proxy, which means that it maintains two types of connections:

  • Client <==> HAProxy (front end)

  • HAProxy (back end) <==> Server

  • With this design, HAProxy can use different protocols on each type of connection.

From a SSL/TLS point of view, this allows the following design:

SSL/TLS pass-through

In this mode, HAProxy does not decipher the traffic. It simply opens a TCP tunnel between the client and the server to let them negotiate and handle the TLS traffic.

The diagram below illustrates this layout:

HAProxy SSL/TLS pass-through

Figure: HAProxy SSL/TLS pass-through

Here, HAProxy simply runs in mode tcp. The sample fetch methods that apply to this mode are those whose names starts with req.ssl_.

Simple HTTPs service load-balancing:

frontend ft_myapp
    bind 10.0.0.1:443
    mode tcp
    # ...
    default_backend bk_myapp

backend bk_myapp
    mode tcp
    # ...
    server app1 10.0.0.11:443 check
    server app2 10.0.0.12:443 check

Deny connection if the client forces using SSLv3:

frontend ft_myapp
    bind 10.0.0.1:443
    mode tcp
    acl sslv3 req.ssl_ver 3
    tcp-request inspect-delay 2s
    tcp-request content reject if sslv3
    # ...

Choose a farm based on the information found in the TLS SNI extension. If there is no SNI sent, then deny the connection. Resend the SNI information on the server side:

frontend ft_global
    bind 10.0.0.1:443
    mode tcp
    # ...
    acl webmail  req.ssl_sni -i webmail.domain.com
    acl extranet req.ssl_sni -i extranet.domain.com
    tcp-request inspect-delay 2s
    tcp-request content reject if !webmail !extranet
    use_backend bk_webmail if webmail
    use_backend bk_extranet if extranet

backend bk_webmail
    mode tcp
    # ...
    server mail1 10.0.0.11:443 check sni req.ssl_sni
    server mail2 10.0.0.12:443 check sni req.ssl_sni

backend bk_extranet
    mode tcp
    # ...
    server extranet1 10.0.0.13:443 check sni req.ssl_sni
    server extranet2 10.0.0.14:443 check sni req.ssl_sni

SSL/TLS bridging or re-encryption

In this mode, HAProxy deciphers the traffic on the client side and re-encrypts it on the server side. It can access the content of the request and the response and perform advanced processing over the traffic.

The diagram below illustrates this layout:

HAProxy SSL/TLS bridging or re-encryption

Figure: HAProxy SSL/TLS bridging or re-encryption

In this mode, HAProxy can run either in mode tcp or mode http and the keywords ssl and crt must be set up on the front end's bind line and at least ssl on the back end's server line (crt is available, but optional).

The sample fetch methods which that apply to this mode are those whose names start with ssl_c, ssl_f ssl_fc and ssl_bc.

Simple TLS bridging for an HTTPs application to perform cookie persistence; use host header as SNI information:

frontend ft_myapp
    bind 10.0.0.1:443 ssl crt myapp
    mode http
    # ...
    default_backend bk_myapp

backend bk_myapp
    mode http
    # ...
    cookie MYAPP insert indirect nocache
    server app1 10.0.0.11:443 ssl check cookie app1 sni req.hdr(Host)
    server app2 10.0.0.12:443 ssl check cookie app2 sni req.hdr(Host)

Use HAProxy to export a weak SSLv3 service on internet over a strong TLS1.2 protocol:

frontend ft_public
    bind 10.0.0.1:443 ssl crt myapp force-tlsv12
    mode tcp
    # ...
    default_backend bk_internal

backend bk_internal
    mode tcp
    # ...
    server sslv3server 10.0.0.11:443 check

SSL/TLS offloading

In this mode, HAProxy deciphers the traffic on the client side and gets connected in clear to the server.

The diagram below illustrates this layout:

HAProxy SSL/TLS offloading

Figure: HAProxy SSL/TLS offloading

In this mode, HAProxy can run either in mode tcp or mode http and the keywords ssl and crt must be set up on the front end's bind line.

The sample fetch methods that apply to this mode are those whose name start with ssl_c, ssl_f ssl_fc and ssl_bc.

Handle both HTTP and HTTPs on the client side, offloading TLS. Create a HTTP header X-Forwarded-Protocol containing the name of the protocol used on the client side:

frontend ft_myapp
    bind 10.0.0.1:80 name http
    bind 10.0.0.1:443 name https ssl crt myapp
    mode http
    acl http  ssl_fc,not
    acl https ssl_fc
    http-request set-header X-Forwarded-Protocol http if http
    http-request set-header X-Forwarded-Protocol https if https
    # ...
    default_backend bk_myapp

backend bk_myapp
    mode http
    # ...
    server app1 10.0.0.11:80 check
    server app2 10.0.0.12:80 check

SSL/TLS encryption

In this mode, HAProxy gets the traffic in clear on the client side and uses TLS to get connected to the server.

The diagram below illustrates this layout:

HAProxy SSL/TLS encryption

Figure: HAProxy SSL/TLS encryption

In this mode, HAProxy can run either in mode tcp or mode http and the keyword ssl must be set up on the back end's server line.

The sample fetch methods that apply to this mode are those whose names start with ssl_b.

Force TLS when reaching backup servers hosted in a third party data center and reachable only through internet:

frontend ft_internal
    bind 10.0.0.1:80 name http
    mode http
    # ...
    acl internal_ko nbsrv(bk_internal) eq 0
    use_backend bk_failover if internal_ko
    default_backend bk_internal

backend bk_internal
    mode http
    # ...
    server app1 10.0.0.11:80 check
    server app2 10.0.0.12:80 check

backend bk_failover
    mode http
    # ...
    server app1 90.a.b.c:443 check ssl
    server app2 90.a.b.d:443 check ssl

Next up

Traffic Routing