add ssl ca-file

Add a new payload of certificates to an existing CA file.

Description Jump to heading #

Add a new payload of certificates to an existing CA file. This command may be preferable to the set ssl ca-file command, which resets (clears) the CA file, requiring you to resubmit all certificates in a single CA file. With the add ssl ca-file command, you can add certificates without first clearing the CA file.

This command stages the changes in a temporary transaction. Use the add ssl crt-list command to add the CA file to a cert list in memory. To commit the transaction to runtime memory, use the commit ssl ca-file command.

Optionally, you can use abort ssl ca-file to abort the transaction.

This operation adds certificates only to the CA list in memory. To make the change permanent, also add the certificates to the CA file on disk.

Examples Jump to heading #

nix
echo -e "add ssl ca-file cafile.pem <<\n$(cat intermediate1.crt)\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo -e "add ssl ca-file cafile.pem <<\n$(cat intermediate1.crt)\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo -e "add ssl ca-file cafile.pem <<\n$(cat intermediate2.crt)\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo -e "add ssl ca-file cafile.pem <<\n$(cat intermediate2.crt)\n" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "commit ssl ca-file cafile.pem" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

nix
echo "commit ssl ca-file cafile.pem" | \
  sudo socat stdio tcp4-connect:127.0.0.1:9999

Begin a transaction and add certificates to a CA file from two intermediate crt files. Commit the transaction to finalize the upload.

The intermediate crt files in this example could contain multiple certificates. As an alternative, the crt files could be combined into a single file so that only one add ssl ca-file command is required.

Example workflow 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-3.0/ssl.pem alpn h2 verify required ca-file /etc/hapee-3.0/intermediate-ca.crt ca-verify-file /etc/hapee-3.0/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-3.0/ssl.pem alpn h2 verify required ca-file /etc/hapee-3.0/intermediate-ca.crt ca-verify-file /etc/hapee-3.0/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.

   nix
   echo -e "set ssl ca-file /etc/hapee-3.0/intermediate-ca.crt <<\n$(cat ./new_certificate.pem)\n" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo -e "set ssl ca-file /etc/hapee-3.0/intermediate-ca.crt <<\n$(cat ./new_certificate.pem)\n" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   transaction created for CA /etc/hapee-3.0/intermediate-ca.crt! 

   output
   text
   transaction created for CA /etc/hapee-3.0/intermediate-ca.crt! 

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

   nix
   echo -e "add ssl ca-file /etc/hapee-3.0/intermediate-ca.crt <<\n(cat ./new_certificate2.pem)\n" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo -e "add ssl ca-file /etc/hapee-3.0/intermediate-ca.crt <<\n(cat ./new_certificate2.pem)\n" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   transaction updated for CA /etc/hapee-3.0/intermediate-ca.crt!

   output
   text
   transaction updated for CA /etc/hapee-3.0/intermediate-ca.crt!

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

   nix
   echo -e "commit ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo -e "commit ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   Committing /etc/hapee-3.0/intermediate-ca.crt
   Success!

   output
   text
   Committing /etc/hapee-3.0/intermediate-ca.crt
   Success!

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

   nix
   echo "show ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo "show ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   Filename: /etc/hapee-3.0/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
   text
   Filename: /etc/hapee-3.0/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.

   nix
   echo -e "del ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   nix
   echo -e "del ssl ca-file /etc/hapee-3.0/intermediate-ca.crt" | \
     sudo socat stdio tcp4-connect:127.0.0.1:9999

   output
   text
   CA file '/etc/hapee-3.0/intermediate-ca.crt' deleted!

   output
   text
   CA file '/etc/hapee-3.0/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-3.0/server-trusted-ca.crt
    server s2 192.168.1.26:80 ssl verify required ca-file /etc/hapee-3.0/server-trusted-ca.crt
    server s3 192.168.1.27:80 ssl verify required ca-file /etc/hapee-3.0/server-trusted-ca.crt

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

See also Jump to heading #

• abort ssl ca-file
• commit ssl ca-file
• del ssl ca-file
• new ssl ca-file
• set ssl ca-file
• show ssl ca-file