Reference

add ssl crt-list

On this page

Available since

  • HAProxy 2.2
  • HAProxy Enterprise 2.2r1

Add an entry to an SSL CRT list.

Description Jump to heading

CRT lists are text files that describe the SSL certificates used in your load balancer configuration. In addition to listing the path to the actual certificate, these files can optionally include metadata related to cipher suite support, as well as SNI matching and exclusion patterns.

An example CRT list, stored at /etc/hapee-2.8/certificate-list.txt follows:

bash
/etc/hapee-2.8/certs/default.pem
/etc/hapee-2.8/certs/test.local.pem [alpn h2 ssl-min-ver TLSv1.2] test.local
bash
/etc/hapee-2.8/certs/default.pem
/etc/hapee-2.8/certs/test.local.pem [alpn h2 ssl-min-ver TLSv1.2] test.local

The first line lists a certificate, whereas the second line lists a certificate, cipher suite parameters, and the SNI, which lists a single domain explicitly. Note that the SNI filter supports wildcard filters and negation filters such as *.domain.tld and !secure.domain.tld.

For the cert list to take effect, it must be declared in a frontend bind directive using the crt-list parameter.

Changes to the certificates and crt-list made using the Runtime API are in memory only and not written to disk. They will therefore be lost when the load balancer stops.

Examples Jump to heading

In this example, we add the line /etc/hapee-2.8/certs/new_certificate.pem [alpn h2] mysite.local to the CRT list at /etc/hapee-2.8/certificate-list.txt.

Note the syntax for setting the extra ALPN attributes, [alpn h2], and SNI value, mysite.local.

bash
echo -e "add ssl crt-list /etc/hapee-2.8/certificate-list.txt <<\n/etc/hapee-2.8/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
bash
echo -e "add ssl crt-list /etc/hapee-2.8/certificate-list.txt <<\n/etc/hapee-2.8/certs/new_certificate.pem [alpn h2] mysite.local\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999
output
bash
Inserting certificate '/etc/hapee-2.8/certs/new_certificate.pem' in crt-list '/etc/hapee-2.8/certificate-list.txt'.
Success! 
output
bash
Inserting certificate '/etc/hapee-2.8/certs/new_certificate.pem' in crt-list '/etc/hapee-2.8/certificate-list.txt'.
Success!

Contextual Example Jump to heading

This operation is generally performed as part of a series of transactions used to manage CA files. You can manage CA files for different domains by passing them to the add ssl crt-list command.

The example in this section demonstrates how to upload a new CA file and attach it to the load balancer’s running configuration.

Verify client certificates Jump to heading

The simplest way to configure an application to use a CA file for verifying client certificates is to specify the CA file or directory in the frontend configuration.

  • Declare the CA file or directory in the frontend bind directive using the ca-file or ca-verify-file parameter. The argument passed to the ca-file parameter can be a specific CA file or a directory containing CA files. The file or directory must already exist.

    haproxy
    frontend fe_main
      mode http
      bind :80
      bind :443 ssl crt /etc/hapee-2.8/ssl.pem alpn h2 verify required ca-file /etc/hapee-2.8/intermediate-ca.crt ca-verify-file /etc/hapee-2.8/root-ca.crt
      http-request redirect scheme https unless { ssl_fc }
      default_backend servers
    haproxy
    frontend fe_main
      mode http
      bind :80
      bind :443 ssl crt /etc/hapee-2.8/ssl.pem alpn h2 verify required ca-file /etc/hapee-2.8/intermediate-ca.crt ca-verify-file /etc/hapee-2.8/root-ca.crt
      http-request redirect scheme https unless { ssl_fc }
      default_backend servers

Use the Runtime API to update a CA file Jump to heading

There are Runtime API commands for modifying CA file contents during runtime.

You can:

  • replace the contents of a CA file entirely using the set ssl ca-file command
  • add certificates to the existing content using the add ssl ca-file command
  • remove the contents of a CA file in memory using del ssl ca-file

These commands initiate a transaction, and the modifications are not in effect until the transaction is committed with the commit ssl ca-file command. Alternatively, you can abandon the changes with the abort ssl ca-file command.

Changes made to the runtime CA file exist only in the memory of the running proxy process and are not reflected in the CA file on disk. If you need CA changes to be persisted beyond the current proxy session, you must modify the CA file on disk.

To modify the runtime CA file, follow these steps.

  1. To replace the CA file contents with new certificates, use the set ssl ca-file command.

    bash
    echo -e "set ssl ca-file /etc/hapee-2.8/intermediate-ca.crt <<\n$(cat ./new_certificate.pem)\n" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo -e "set ssl ca-file /etc/hapee-2.8/intermediate-ca.crt <<\n$(cat ./new_certificate.pem)\n" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    transaction created for CA /etc/hapee-2.8/intermediate-ca.crt! 
    output
    bash
    transaction created for CA /etc/hapee-2.8/intermediate-ca.crt!

  2. To add an entry to a CA file, use the add ssl ca-file command.

    bash
    echo -e "add ssl ca-file /etc/hapee-2.8/intermediate-ca.crt <<\n(cat ./new_certificate2.pem)\n" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo -e "add ssl ca-file /etc/hapee-2.8/intermediate-ca.crt <<\n(cat ./new_certificate2.pem)\n" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    transaction updated for CA /etc/hapee-2.8/intermediate-ca.crt!
    output
    bash
    transaction updated for CA /etc/hapee-2.8/intermediate-ca.crt!

  3. Updates to the CA file in memory do not take effect until the transaction is committed. Commit the transaction:

    bash
    echo -e "commit ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo -e "commit ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    Committing /etc/hapee-2.8/intermediate-ca.crt
    Success!
    output
    bash
    Committing /etc/hapee-2.8/intermediate-ca.crt
    Success!

  4. Use show ssl ca-file to verify that the CA file was updated correctly:

    bash
    echo "show ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo "show ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    Filename: /etc/hapee-2.8/intermediate-ca.crt
    Status: Unused
    Certificate #1:
    Serial: 03BB662E4A45FE7E576F3C22195ADDC0
    notBefore: Nov  9 00:00:00 1994 GMT
    notAfter: Jan  7 23:59:59 2010 GMT
    Subject Alternative Name:
    Algorithm: RSA1000
    SHA1 FingerPrint: 4463A531B4BCA1004794612BC646D3BF8233846F
    Subject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Issuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Certificate #2:
    Serial: 04BB662E4A45FE7E576F3C22195AEDC0
    notBefore: Nov  9 00:00:00 1994 GMT
    notAfter: Jan  7 23:59:59 2010 GMT
    Subject Alternative Name:
    Algorithm: RSA1000
    SHA1 FingerPrint: 2463A531B4BCA1004794212BC646D3BF8233846D
    Subject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Issuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    output
    bash
    Filename: /etc/hapee-2.8/intermediate-ca.crt
    Status: Unused
    Certificate #1:
    Serial: 03BB662E4A45FE7E576F3C22195ADDC0
    notBefore: Nov  9 00:00:00 1994 GMT
    notAfter: Jan  7 23:59:59 2010 GMT
    Subject Alternative Name:
    Algorithm: RSA1000
    SHA1 FingerPrint: 4463A531B4BCA1004794612BC646D3BF8233846F
    Subject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Issuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Certificate #2:
    Serial: 04BB662E4A45FE7E576F3C22195AEDC0
    notBefore: Nov  9 00:00:00 1994 GMT
    notAfter: Jan  7 23:59:59 2010 GMT
    Subject Alternative Name:
    Algorithm: RSA1000
    SHA1 FingerPrint: 2463A531B4BCA1004794212BC646D3BF8233846D
    Subject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority
    Issuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority

  5. To delete a CA file in memory, use del ssl ca-file.

    bash
    echo -e "del ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    bash
    echo -e "del ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \
      sudo socat stdio tcp4-connect:127.0.0.1:9999
    output
    bash
    CA file '/etc/hapee-2.8/intermediate-ca.crt' deleted!
    output
    bash
    CA file '/etc/hapee-2.8/intermediate-ca.crt' deleted!

Verify server certificates Jump to heading

To use CA files to verify server certificates, specify the CA file using the ca-file parameter in the backend server or default-server directive.

The server directive must also specify:

  • the ssl parameter to enable HTTPS communication

  • the verify required parameter to verify the server SSL certificate against the CA’s provided in the CA file

    haproxy
    backend web_servers
      mode http
      server s1 192.168.1.25:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt
      server s2 192.168.1.26:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt
      server s3 192.168.1.27:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt
    haproxy
    backend web_servers
      mode http
      server s1 192.168.1.25:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt
      server s2 192.168.1.26:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt
      server s3 192.168.1.27:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crt

See also Jump to heading

If this page was useful, please, Leave the feedback.

Previous page add ssl ca-file Next page clear acl
© 2023 HAProxy Technologies, LLC. All Rights Reserved
Manage Cookie Preferences