Configuring Certificate Authorities

This section provides basic information that will help you configure certificate authorities (CA)s and manage certificate revocation checking for client authentication.

Enabling or Disabling the Standard Domain Validation Certificate Authorities List

The standard domain validation CAs list is a pre-populated list of standard, trusted domain validation root certificates used to verify the server name for all outgoing TLS connections and cannot be modified. By default, the standard domain CAs list is enabled. If you want to use only the domain CA list, you can disable the standard domain validation list.

To disable the standard domain validation CAs list, enter the following command:

solace(configure)# no ssl standard-domain-certificate-authorities

To enable the standard domain validation CAs list, enter the following command:

solace(configure)# ssl standard-domain-certificate-authorities

In versions earlier than 9.8.0, the client authentication CAs list is the only list and it is used for both incoming and outgoing TLS connections.

Configuring the Domain Validation Certificate Authorities List

The domain validation CAs list is used in combination with the standard domain validation list to verify the server name for all outgoing TLS connections. The domain validation CAs list is initially empty in new deployments. In deployments upgrading to version 9.8.0+ the event broker copies the contents of the existing CA list to both the domain CA list and the client authentication CA list. You can configure the CAs in this list to suit your deployment.

Here are the Solace CLI commands for domain validation CA creation and configuration.

To create a domain CA, enter the following commands:

solace(configure)# ssl
solace(configure/ssl)# create domain-certificate-authority <ca-name>

To configure an existing domain CA, enter the following command:

solace(configure/ssl)# domain-certificate-authority <ca-name>

Each certificate in the chain must be configured for authentication. To configure a CA certificate, enter the following command:
```
solace(configure/ssl/domain-certificate-authority)# certificate file <ca-certificate>
```

Where:

ca-name is the name of the CA. You can use a maximum of 64 characters for a ca-name. Acceptable characters are alpha-numeric characters, period (.), hyphen (-), and under score (_).

ca-certificate is the filename of the CA certificate. This file must be located in the /usr/sw/jail/certs directory on the event broker. Once the certificate is in the certs directory, you can individually add certificates to the list of trusted CA certificates. The maximum number of trusted CA certificates that may be loaded is 64.

The no version of the certificate command, no certificate, removes the domain CA from the event broker.

In versions earlier than 9.8.0, the client authentication CAs list is the only list and it is used for both incoming and outgoing TLS connections.

Configuring the Client Authentication Certificate Authorities List

Solace PubSub+ event brokers allow clients to authenticate over TLS by presenting a valid client certificate. The event broker authenticates the client certificate by constructing a full certificate chain (from the client certificate to intermediate CAs to a configured root CA). The intermediate CAs in this chain can be provided by the client, or configured in the event broker. The root CA must be configured on the event broker.

For Solace PubSub+ appliances using version 8.2.0+ and Solace PubSub+ software event brokers using version 8.7.0+, CA certificates must be configured to validate incoming certificates for all SSL connections.

The certificate files for a CA can only contain a single certificate. There are a couple of other considerations depending on whether you're also using SSL/TLS authentication and / or revocation checking:

SSL/TLS Authentication

At a minimum you must configure the root CA on the broker.

Certificate Authority Revocation Checking

The root CA and all the intermediate CAs that complete the chain must be configured on the broker.

Here are the Solace CLI commands for client authentication CA creation and configuration.

To create a client authentication CA, enter the following commands:
solace(configure)# authentication
solace(configure/authentication)# create client-certificate-authority <ca-name>
To configure an existing client authentication CA, enter the following command:
solace(configure/authentication)# client-certificate-authority <ca-name>
Each certificate in the chain must be configured for authentication. To configure a CA certificate, enter the following command:
solace(configure/authentication/client-certificate-authority)# certificate file <ca-certificate>

Where:

ca-name is the name of the CA. You can use a maximum of 64 characters for a ca-name. Acceptable characters are alpha-numeric characters, period (.), hyphen (-), and under score (_).

The no version of the certificate command, no certificate, removes the CA from the event broker.

CA certificates are HA Config-Sync'ed, but not Replication Config-Sync'ed.
Once a CA certificate is configured, a copy of it is saved internally. The file in the /usr/sw/jail/certs directory is no longer required.
In versions earlier than 9.8.0, use the certificate-authority command. For more information, see Configuring Certificate Authorities.

Compatibility with Older Versions

For compatibility with versions prior to 9.8.0, the certificate-authority commands have been deprecated but will continue to work until January 2027 (6 years after the 9.8.0 release), operating on both the client authentication CAs list and the domain validation CAs list, or just the client authentication list as appropriate. After January 2027, these commands will be removed.

Commands that Participate in Config-Sync

The following commands participate in Config-Sync. Until January 2024 (3 years after the 9.8.0 release), the original commands will be emitted for Config-Sync purposes if the client authentication CA and domain validation CA lists contain the same certificates with the same CA names. If the lists differ, the new commands will be emitted. Between January 2024 and January 2027, the new commands will be emitted for Config-Sync purposes. After January 2027 the deprecated commands will be removed.

create certificate-authority <ca-name> (This is the same as running create client-certificate-authority <ca-name> and create domain-certificate-authority <ca-name>. If the specified CA name exists in either list or if either list is at capacity the event broker emits an error and does nothing .)
no certificate-authority <ca-name> (This is the same as running no client-certificate-authority <ca-name> and no domain-certificate-authority <ca-name>. If the specified CA name doesn't exist in both lists the event broker emits an error and does nothing .)
certificate-authority <ca-name> (This is the same as running client-certificate-authority <ca-name> and domain-certificate-authority <ca-name>. If the specified CA name doesn't exist in both lists the broker emits an error and does nothing.)
certificate-authority <ca-name> revocation-check (All commands under revocation-check are the same as the corresponding command for client-certificate-authority, in other words, client-certificate-authority <ca-name> revocation-check)

Other Commands

The following commands do not participate in Config-Sync. After January 2027 these commands will be removed.

show certificate-authority (If a CA with the same name and certificate exists in both the client authentication CAs list and the domain validation CAs list, this is the same as show client-certificate-authority. If the name or certificate is not the same, the result will be empty.
admin certificate-authority <ca-name> refresh-crl (This is the same as running admin client-certificate-authority <ca-name> refresh-crl)
clear certificate-authority stats (This is the same as running clear client-certificate-authority stats)

Upgrades from 9.7.0 and Earlier to 9.8.0+

Upgrades to version 9.8.0+ will copy the contents of the current CA list to both the domain validation CA list and the client authentication CA list. You can modify the certificates from either list after the upgrade.

Configuring Certificate Revocation Checking

An event broker can check the revocation status of the certificate that clients use when attempting to authenticate. You can configure certificate revocation checking on a per-event broker basis. However, you can also configure overrides on a per-Message VPN basis to ignore the results of the revocation check, and to allow authentication of certificates with unknown revocation status.

You can configure event brokers to check the revocation status of client certificates using one of the following methods:

Certificate Revocation List (CRL)
Online Certificate Status Protocol (OCSP)
OCSP-CRL (Combination of both)

For more information, see Certificate Revocation Checking Methods.

To enable certificate revocation checking, enter the following command:

solace(configure/authentication)# client-certificate-revocation-checking [none | ocsp | crl | ocsp-crl]

Where:

none (default) specifies to not check the revocation status of certificates during validation and all the certificates are considered valid.

ocsp specifies to use OCSP to verify the revocation status of the certificates during validation.

crl specifies to use CRL to verify the revocation status of the certificates during validation.

ocsp-crl specifies to use OCSP first to verify the revocation status of the certificates, if OCSP fails to return an unambiguous result, then CRL is used to check the revocation status of the certificates.

For a step-by-step procedure to configure OCSP, CRL, or OCSP-CRL certificate revocation checking, see the following.

Provide feedback