Managing Cryptographic Keys

The event broker uses three categories of cryptographic keys, each for a different purpose:

  • TLS server keys for TLS server authentication on inbound connections.
  • TLS client keys for TLS client authentication on outbound connections with these types of connections:
    • bridges
    • replication
    • REST/RDP
    • DMR
    • MNR
  • TLS pre-shared keys for mutually authenticating TLS connections between redundancy group members (starting with release 9.2.0).

You must use a unique key for each purpose. The event broker uses a key only for the purpose for which it is configured.

TLS server certificates must contain appropriate keyUsage and extendedKeyUsage extensions for server authentication. TLS client certificates must contain appropriate keyUsage and extendedKeyUsage extensions for client authentication.

Key Generation

You must generate the keys and obtain their certificates (no certificates are needed for pre-shared keys). TLS client and server keys are RSA private keys, while TLS pre-shared keys are symmetric.

Key Transfer

You can load keys using different mechanisms as described below.

To deploy a software event broker: 

  • with a pre-installed TLS server key, use a secret . For details, see Configuring Secrets
  • with a TLS pre-shared key, use the following configuration keys: 
    • redundancy/authentication/presharedkey/key
    • redundancy/authentication/presharedkey/keyfilepath
  • with TLS client and server keys, use SEMPv2. However, the process depends on the kind of key you're using. For details, see SEMP API Reference.

Overall, the process for loading TLS client and server keys includes setting up:

  • a write-only attribute that contains a PEM (.pem) encoded certificate chain and a password-encrypted key
  • a separate write-only attribute that provides that password

For example, if you set up a TLS server key using tlsServerCertContent and tlsServerCertPassword attributes of the root object, the event broker uses the supplied password to decrypt the key once only. Before the event broker stores the key, it re-encrypts it using a unique key.

You can copy TLS client and server keys from one event broker to another in opaque encrypted form. In this method, the event broker uses an SEMPv2 opaque write-only retrieval mechanism for configuration keys. This mechanism is encrypted with a provided password. For details, see SEMP API Reference.

The process for loading TLS client keys using CLI depends on the key purpose:

In general, to load TLS client and server keys on the event broker, do the following:

  1. Using encrypted connection such as scp, copy a PEM (.pem) file that contains a certificate and a password-protected key (a private key) to the event broke. For details, see Event Broker File Management.
  2. Configure the event broker to use that key pair for your purpose.

    At this point, the event broker prompts for and uses a password to decrypt the private key. The event broker then re-encrypts the loaded private key using a unique broker key and stores it in the event broker configuration. If the broker key doesn’t exist already, the event broker generates a unique broker key and stores it separately from configuration.

  3. Delete the PEM file from the event broker.

To review the detailed process for loading TLS pre-shared keys using the CLI, see Pre-Shared Authentication Keys for Software Event Brokers.

Key Storage

The event broker stores keys in configuration files and encrypts them using a unique key that it stores separately.

For additional protection, you can use the capabilities of the underlying infrastructure (such as a cloud provider) to encrypt the volume the event broker uses.

Key Lifetime

You must determine the lifetime for each key. Typically, this lifetime corresponds to the certificate expiry date. You should replace the keys (and certificates) before the certificate expiry date to avoid service disruption.