Managing Server Certificates

To enable TLS/SSL-encryption, you must set the TLS/SSL server certificate file that the Solace PubSub+ event broker is to use. This server certificate is presented to clients during TLS/SSL handshakes. The server certificate must be an x509v3 certificate and include a private key. The server certificate and key use an RSA algorithm for private key generation, encryption and decryption, and they both must be encoded with a Privacy Enhanced Mail (PEM) format.

The single server certificate file set for the event broker can have a maximum chain depth of three (that is, the single certificate file can contain up to three certificates in a chain that can be used for the certificate verification).

The TLS/SSL certificate file to be used must be located in the /usr/sw/jail/certs directory on the event broker file system when the certificate is to be configured.

To use a TLS/SSL server certificate, you must perform the following steps:

Loading Server Certificate Files

To load a server certificate on an event broker, enter the following command:

solace# copy sftp://[<username>@]<ip-addr>/<remote-pathname> /certs/<certificate-file>

Where:

<username> is the SFTP username if a username is required to access the remote certificate file.

<ip-addr> is the address of the SFTP server where the remote certificate file is stored.

<remote-pathname> is the path to the certificate file from the server root directory.

<certificate-file> is the filename to use for the certificate on the event broker.

For more information on how to add files to the event broker file system, see Event Broker File Management.

Setting Server Certificates To Use

To set a server certificate for the event broker to use, enter the following commands:

solace(configure)# ssl
solace(configure/ssl)# server-certificate <filename>

Where:

<filename> is the filename of the certificate. This file must be located in the /usr/sw/jail/certs directory on the event broker. Once a certificate is configured, a copy of it is saved internally. The file in the certs directory is no longer required.

The no version of this command, no server-certificate, clears the server‑certificate that is set for the event broker.

  • To maintain private key security and to prevent unauthorized users from copying private keys from the event broker, Solace strongly recommends that only password‑protected private keys are used for the server certificate.
  • The certificate file that is used can be changed after clients have established TLS/SSL connections to the event broker. Any clients that already have established secure connections using the previous certificate are not affected. However, once they disconnect, they cannot reestablish a connection with the previous certificate.
  • If you want to replace the server certificate that was previously set with a new one, use the same command to set the new server certificate. Only one server certificate can be set for the event broker.
  • For PEM encoded certificates, the maximum size is 32 kilobytes. This limit applies to the total certificate including all components (certificate, certificate chain, private key, subject alternative names, etc).
  • For DER encoded certificates (a binary encoded version of the PEM format), the maximum size is 24 kilobytes.

Config-Sync will not automatically synchronize this object or property. Therefore, if the event broker is being used in a high-availability (HA) redundant configuration or in a replicated site, you must manually configure this object/property on each mate event broker or replicated Message VPN.

To determine whether an object/property is synchronized by Config-Sync, look up the command used to configure the object/property in the CLI Command Reference or type the command in the Solace CLI, ending the command with "?". The Help lists whether the object/property is synchronized.