Reference
add ssl crt-list
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
outputbash
Inserting certificate '/etc/hapee-2.8/certs/new_certificate.pem' in crt-list '/etc/hapee-2.8/certificate-list.txt'.Success!
outputbash
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 theca-file
orca-verify-file
parameter. The argument passed to theca-file
parameter can be a specific CA file or a directory containing CA files. The file or directory must already exist.haproxyfrontend fe_mainmode httpbind :80bind :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.crthttp-request redirect scheme https unless { ssl_fc }default_backend servershaproxyfrontend fe_mainmode httpbind :80bind :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.crthttp-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.
-
To replace the CA file contents with new certificates, use the
set ssl ca-file
command.bashecho -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:9999bashecho -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:9999outputbashtransaction created for CA /etc/hapee-2.8/intermediate-ca.crt!outputbashtransaction created for CA /etc/hapee-2.8/intermediate-ca.crt! -
To add an entry to a CA file, use the
add ssl ca-file
command.bashecho -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:9999bashecho -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:9999outputbashtransaction updated for CA /etc/hapee-2.8/intermediate-ca.crt!outputbashtransaction updated for CA /etc/hapee-2.8/intermediate-ca.crt! -
Updates to the CA file in memory do not take effect until the transaction is committed. Commit the transaction:
bashecho -e "commit ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999bashecho -e "commit ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999outputbashCommitting /etc/hapee-2.8/intermediate-ca.crtSuccess!outputbashCommitting /etc/hapee-2.8/intermediate-ca.crtSuccess! -
Use
show ssl ca-file
to verify that the CA file was updated correctly:bashecho "show ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999bashecho "show ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999outputbashFilename: /etc/hapee-2.8/intermediate-ca.crtStatus: UnusedCertificate #1:Serial: 03BB662E4A45FE7E576F3C22195ADDC0notBefore: Nov 9 00:00:00 1994 GMTnotAfter: Jan 7 23:59:59 2010 GMTSubject Alternative Name:Algorithm: RSA1000SHA1 FingerPrint: 4463A531B4BCA1004794612BC646D3BF8233846FSubject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityIssuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityCertificate #2:Serial: 04BB662E4A45FE7E576F3C22195AEDC0notBefore: Nov 9 00:00:00 1994 GMTnotAfter: Jan 7 23:59:59 2010 GMTSubject Alternative Name:Algorithm: RSA1000SHA1 FingerPrint: 2463A531B4BCA1004794212BC646D3BF8233846DSubject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityIssuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityoutputbashFilename: /etc/hapee-2.8/intermediate-ca.crtStatus: UnusedCertificate #1:Serial: 03BB662E4A45FE7E576F3C22195ADDC0notBefore: Nov 9 00:00:00 1994 GMTnotAfter: Jan 7 23:59:59 2010 GMTSubject Alternative Name:Algorithm: RSA1000SHA1 FingerPrint: 4463A531B4BCA1004794612BC646D3BF8233846FSubject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityIssuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityCertificate #2:Serial: 04BB662E4A45FE7E576F3C22195AEDC0notBefore: Nov 9 00:00:00 1994 GMTnotAfter: Jan 7 23:59:59 2010 GMTSubject Alternative Name:Algorithm: RSA1000SHA1 FingerPrint: 2463A531B4BCA1004794212BC646D3BF8233846DSubject: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification AuthorityIssuer: /C=US/O=RSA Data Security, Inc./OU=Secure Server Certification Authority -
To delete a CA file in memory, use
del ssl ca-file
.bashecho -e "del ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999bashecho -e "del ssl ca-file /etc/hapee-2.8/intermediate-ca.crt" | \sudo socat stdio tcp4-connect:127.0.0.1:9999outputbashCA file '/etc/hapee-2.8/intermediate-ca.crt' deleted!outputbashCA 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 filehaproxybackend web_serversmode httpserver s1 192.168.1.25:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crtserver s2 192.168.1.26:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crtserver s3 192.168.1.27:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crthaproxybackend web_serversmode httpserver s1 192.168.1.25:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crtserver s2 192.168.1.26:80 ssl verify required ca-file /etc/hapee-2.8/server-trusted-ca.crtserver 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.