Certificate Details

In KeySafe 5 Service, certificates are used to secure communications. The following sections provide details about the different types of certificates used in KeySafe 5.

WebUI/API Interface Certificates

Certificates are used to secure the API and WebUI interface. These certificates are found in the %NFAST_DATA_HOME%/keysafe5/server/https directory.

Unless configured otherwise, %NFAST_DATA_HOME% is located at /opt/nfast on Linux and %ProgramData%\nCipher on Windows.
File Name Description

server.crt

The TLS certificate for the WebUI/API interface.

server.key

The private key for the WebUI/API interface.

On initial installation, a self-signed certificate is created. It is recommended to replace this with a certificate from a trusted Certificate Authority (CA). To replace the HTTPS certificate, follow these steps:

  1. Optional - Replace the private key located at %NFAST_DATA_HOME%/keysafe5/server/https/server.key with one that meets your requirements.

  2. Generate a Certificate Signing Request (CSR) using the private key located at %NFAST_DATA_HOME%/keysafe5/server/https/server.key.

  3. Submit the CSR to a trusted CA to obtain a signed certificate.

  4. Replace the existing server.crt file with the new signed certificate.

  5. Ensure the new certificate is in PEM format and includes the full certificate chain if required by your CA.

  6. Restart the KeySafe 5 service to apply the changes.

  7. Verify the WebUI/API interface is functioning correctly with the new certificate.

Agent Communication Certificates

TLS certificates are used to secure communication between the KeySafe 5 Service and KeySafe 5 Agents. These certificates are found in multiple directories under the %NFAST_DATA_HOME%/keysafe5/server/tls directory.

Unless configured otherwise, %NFAST_DATA_HOME% is located at /opt/nfast on Linux and %ProgramData%\nCipher on Windows.

Server Certificates

The server certificates are used by KeySafe 5 Service to secure the communication to KeySafe 5 Agents. The CA certificate is used to verify that connecting KeySafe 5 Agents have permission to connect. These certificates are found in the %NFAST_DATA_HOME%/keysafe5/server/tls/server directory.

File Name Description

server.crt

The TLS certificate for the KeySafe 5 Agent communication interface.

server.key

The private key for the KeySafe 5 Agent communication interface.

ca.crt

The CA certificate used to sign KeySafe 5 Agent certificates. KeySafe 5 Agents not signed by this CA will not be able to connect to the KeySafe 5 Service.

On initial installation, a self-signed CA and server certificate are created. It is recommended to replace these with certificates from a trusted Certificate Authority (CA). To replace the TLS certificates, follow these steps:

  1. Optional - Replace the private key located at %NFAST_DATA_HOME%/keysafe5/server/tls/server/server.key with one that meets your requirements.

  2. Generate a Certificate Signing Request (CSR) using the private key located at %NFAST_DATA_HOME%/keysafe5/server/tls/server/server.key.

  3. Submit the CSR to a trusted CA to obtain a signed certificate.

  4. Replace the existing server.crt file with the new signed certificate.

  5. Obtain the CA certificate from your trusted CA and replace the existing ca.crt file with it. This is used to ensure that only KeySafe 5 Agents signed by this CA can connect to the KeySafe 5 Service.

  6. Ensure the new certificates are in PEM format and include the full certificate chain if required by your CA.

  7. Restart the KeySafe 5 service to apply the changes.

  8. Any KeySafe 5 Agents that were connected to the KeySafe 5 Service will need to be updated with new certificates signed by the new CA.

Client Certificates

Client certificates are used by KeySafe 5 Server internally to authenticate the connection to the Agent Communication interface. These certificates are found in the %NFAST_DATA_HOME%/keysafe5/server/tls/clients directory.

The TLS certificate that KeySafe 5 uses for connection to the Agent Communications interface must contain keysafe5-backend-services in the certificate’s Distinguished Name so that the Agent Communications interface can properly limit permissions for this certificate. If the certificate’s DistinguishedName does not contain keysafe5-backend-services then KeySafe 5 Service will be unable to connect to the Agent Communication interface.
File Name Description

tls.crt

The TLS certificate for the KeySafe 5 Service to authenticate to the Agent Communication interface. This certificate is signed by the CA used to sign KeySafe 5 Agent certificates.

tls.key

The private key for the KeySafe 5 Service to authenticate to the Agent Communication interface.

ca.crt

The CA certificate used to sign the Agent Communication Server certificates.

On initial installation, a self-signed certificate is created. If you are replacing the Agent Communication Server certificates and/or the CA used to sign the KeySafe 5 Agent certificates, it is necessary to also replace these with certificates signed by the same CA.

Certificate Authority (CA)

The CA certificate is used to sign KeySafe 5 Agent certificates. This certificate is found in the %NFAST_DATA_HOME%/keysafe5/server/tls/ca directory.

This directory is created during initial installation if existing certificates are not detected. It is created and managed by the keysafe5-server-admin utility. If you wish to use your own CA, you can remove this directory.

File Name Description

ca.key

The private key for the CA used to sign KeySafe 5 Agent certificates.

ca.crt

The CA certificate used to sign KeySafe 5 Agent certificates.

Please see the keysafe5-server-admin utility section below for details on how to reinitialize this CA and sign KeySafe 5 Agent certificates.

keysafe5-server-admin Utility

The keysafe5-server-admin tool is installed with KeySafe 5 Service to aid management of the certificate infrastructure used to secure communication between the KeySafe 5 Service and KeySafe 5 agents.

keysafe5-server-admin is invoked on initial install if existing certificates are not detected to ensure a working instance post installation.

keysafe5-server-admin can be used to initialise a self-signed CA, update CA and server certificates, and sign KeySafe 5 Agent CSR requests.

By default, generated certificates are valid for 30 days.

If you use keysafe5-server-admin to update any certificates, you must then restart KeySafe 5 Server to apply the updated certificates.

Updating the CA certificate will require any KeySafe 5 Agent certificates signed by the old CA certificate to be re-signed with the new CA certificate.

Initialise TLS certificates for KeySafe 5

keysafe5-server-admin init [-y|-n] [--ca DAYS] [--server DAYS] [ADDRESSES...]

  • -y : Always overwrite an existing configuration.

  • -n : Always preserve the existing configuration.

  • --ca DAYS : (Optional) The number of days that the CA certificate will be valid for (default 30).

  • --server DAYS : (Optional) The number of days that the server certificates will be valid for (default 30).

  • [ADDRESSES] : (Optional) Comma-separated list of IP addresses to include in the generated server certificate. If not provided, all local and loopback IPv4 and IPv6 addresses are added automatically.

Example:

keysafe5-server-admin init 127.0.0.1,172.26.0.1,192.168.0.1,::1

Update the CA certificate

Update the Certificate Authority certificate. The certificate will be valid for 30 days unless specified otherwise.

keysafe5-server-admin ca [DAYS]

  • [DAYS] : (Optional) The number of days that the signed certificate will be valid for (default 30).

Example:

keysafe5-server-admin ca 365

Update the server certificates

Update the server TLS certificate for the KeySafe 5 Agent communication interface and the client TLS certificate for the KeySafe 5 Service to authenticate to the Agent Communication interface. The certificates will be valid for 30 days unless specified otherwise.

keysafe5-server-admin server [DAYS] [ADDRESSES...]

  • [DAYS] : (Optional) The number of days that the server certificates will be valid for (default 30).

  • [ADDRESSES] : (Optional) Comma-separated list of IP addresses to include in the generated server certificate. If not provided, all local and loopback IPv4 and IPv6 addresses are added automatically.

Example:

keysafe5-server-admin server 60 127.0.0.1,172.26.0.1,192.168.0.1,::1

Sign a CSR for a KeySafe 5 Agent.

keysafe5-server-admin sign PATH_TO_CSR [DAYS] [TLS_DIRECTORY]

  • PATH_TO_CSR : Path to the Certificate Signing Request file.

  • [DAYS] : (Optional) The number of days that the signed certificate will be valid for (default 30).

  • [TLS_DIRECTORY] : (Optional) Directory to save the signed certificates.

Example:

keysafe5-server-admin sign demo.csr 365