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.
Please ensure that all certificate files and private keys are stored securely and have appropriate permissions set to prevent unauthorized access, as they contain sensitive information.
On Windows, Entrust recommends that the %NFAST_KEYSAFE5%\server directory is only accessible to Administrators.
The permissions for the KeySafe 5 server is then added by running %NFAST_HOME%\bin\keysafe5-server fix-permissions in an Administrator command prompt.
|
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.
This directory is created during the initial installation if no existing certificates are detected.
It is created and managed by the keysafe5-server-admin utility.
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:
-
Optional - Replace the private key located at
%NFAST_DATA_HOME%/keysafe5/server/https/server.keywith one that meets your requirements. -
Generate a Certificate Signing Request (CSR) using the private key located at
%NFAST_DATA_HOME%/keysafe5/server/https/server.key. -
Submit the CSR to a trusted CA to obtain a signed certificate.
-
Replace the existing
server.crtfile with the new signed certificate. -
Ensure the new certificate is in PEM format and includes the full certificate chain if required by your CA.
-
Restart the KeySafe 5 service to apply the changes.
-
Verify the WebUI/API interface is functioning correctly with the new certificate.
For details about creating self-signed KeySafe 5 certificates, see the keysafe5-server-admin utility section below.
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:
-
Optional - Replace the private key located at
%NFAST_DATA_HOME%/keysafe5/server/tls/server/server.keywith one that meets your requirements. -
Generate a Certificate Signing Request (CSR) using the private key located at
%NFAST_DATA_HOME%/keysafe5/server/tls/server/server.key. -
Submit the CSR to a trusted CA to obtain a signed certificate.
-
Replace the existing
server.crtfile with the new signed certificate. -
Obtain the CA certificate from your trusted CA and replace the existing
ca.crtfile with it. This is used to ensure that only KeySafe 5 Agents signed by this CA can connect to the KeySafe 5 Service. -
Ensure the new certificates are in PEM format and include the full certificate chain if required by your CA.
-
Restart the KeySafe 5 service to apply the changes.
-
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.
Multi-tier Certificates
To replace the initial certificate configuration with a multi-tier configuration, you must use an external CA.
For instructions on reinitializing the certificate configuration to use external CAs, see the keysafe5-server-admin utility.
This produces two key-and-CSR pairs, one in each of the %NFAST_DATA_HOME%/keysafe5/server/tls/client and %NFAST_DATA_HOME%/keysafe5/server/tls/server directories.
To verify the connection, the client must provide a certificate identity chain that can be verified against the server CA located in the %NFAST_DATA_HOME%/keysafe5/server/tls/server directory and
the server must provide a corresponding chain that can be verified against the client CA located in the %NFAST_DATA_HOME%/keysafe5/server/tls/client directory.
For example, to establish a connection between a client that is anchored by a root certificate and a server that is anchored by an intermediate certificate, the following configuration is required
Client Certificates:
| File Name | Description |
|---|---|
tls.crt |
The TLS certificate signed by the intermediate certificate |
tls.key |
The private key for the client identity certificate. |
ca.crt |
The root certificate |
Server Certificates:
| File Name | Description |
|---|---|
tls.crt |
The TLS certificate signed by the intermediate certificate appended with the intermediate CA. |
tls.key |
The private key for the server identity certificate |
ca.crt |
The intermediate certificate |
keysafe5-server-admin Utility
The keysafe5-server-admin tool is installed with the KeySafe 5 Service to help manage the certificate infrastructure that secures the API, the WebUI interface, and communications 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 initialize a self-signed CA, update CA, HTTPS, and server certificates, and sign CSR requests from KeySafe 5 agents.
By default, generated certificates are valid for 30 days.
|
If you use 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
Initialize TLS keys and CSRs for KeySafe 5 for external certificates
Generates TLS key-and-CSR pairs for both server and client, which can then be signed by an external Certificate Authority.
keysafe5-server-admin init --external [-y|-n] [ADDRESSES...]
-
--external: Generates server and client keys and writes a CSR for each instead of creating a CA. In this mode,--caand--serverare ignored. -
-y: Always overwrite an existing configuration. -
-n: Always preserve the existing configuration. -
[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.
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
Update the HTTPS certificates
Update the HTTPS TLS certificate used to secure the KeySafe 5 API and WebUI interface. By default, the certificates are valid for 30 days.
keysafe5-server-admin https [-y|-n] [DAYS]
-
-y: (Optional) Always overwrite an existing configuration. -
-n: (Optional) Always preserve the existing configuration. -
[DAYS]: (Optional) The number of days that the server certificates will be valid for (default 30).
Example:
keysafe5-server-admin https -y 30
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