Guidelines for Updating the External Certificates

If the external certificate that the data store uses has expired, or is no longer valid, you may need to replace the SSL key and certificate. This section describes the procedure to complete this task.

You can update the external certificates using one of the following two methods:

Use the plan update-tls-credentials command
Use the manual process in each of the SNs to create a certificate, merge the truststore entries, copy the store.keys file to the security directory, and stop and start each Storage Node sequentially as part of a rolling restart, if needed. You need to restart the SNs only if the data store has not yet been fully upgraded to Oracle NoSQL Database 24.4 or later. Once all SNs have been upgraded, they will notice the key and certificate changes without needing a restart.

Use the plan command

The plan update-tls-credentials command retrieves and installs the credential updates to the set of shared TLS (Transport Layer Security, earlier known as SSL) credentials used by Storage Node Agents (SNA) in the data store. You should use this plan only with data stores where all SNAs share the same credentials, and not for data stores with host-specific credentials.

plan update-tls-credentials  [-retrieve-only|-install-only] [-force]

The plan command can be used in multiple ways depending on your requirements.

You can manually copy the new credentials and use the plan update-tls-credentials command with the -install-only flag. This is the best choice which you can use by default.
If you need to automate the entire process of updating SSL credentials and keys, you could use the plan update-tls-credentials command without specifying any options or flags. Then the plan command retrieves the credentials and installs them.
You could use the plan update-tls-credentials command with the -retrieve-only flag if you just want to retrieve the credentials and plan to install it later.

See plan update-tls-credentials for more details on how the SSL Keys and certificates are updated automatically using this plan command.

Manual process of updating external certificates

Follow these steps to update the external certificates for a secure installation that is already using external certificates.

Note:

This procedure assumes you already have a Java keystore and truststore setup having the updated external certificates. For more information see Java KeyStore Preparation.

Create a new security configuration that uses external certificates.

security-> config create -root $NEW_KVROOT \
-pwdmgr wallet -kspwd password \
-param "client:serverIdentityAllowed=dnmatch
(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown,
ST=California, C=US)" \
-param "internal:serverIdentityAllowed=dnmatch
(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown,
ST=California, C=US)" \
-param "internal:clientIdentityAllowed=dnmatch
(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown,
ST=California, C=US)" \
-param "ha:serverIdentityAllowed=dnmatch
(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown,
ST=California, C=US)" \
-param "ha:clientIdentityAllowed=dnmatch
(CN=myhost, OU=TeamA, O=MyCompany, L=Unknown,
ST=California, C=US)"

Replace the keystore and server truststores with your own:
```
copy store.keys store.trust $NEW_KVROOT/security/ 
```
On the configuration host, merge the truststore entries with the $NEW_KVROOT directory. Check that all Replication Nodes are online and then restart each Storage Node one by one using the following commands. If the updated external certificate uses a different distinguished name, update the dnmatch value in the security configuration to a compatible one using the procedures found in Guidelines for Configuring External Certificates for an Existing Default Secure Installation.

Note:

Before starting the SNA, set the environment variable MALLOC_ARENA_MAX to 1. Setting MALLOC_ARENA_MAX to 1 ensures that the memory usage is restricted to the specified heap size.
```
java -Xmx64m -Xms64m \
-jar $KVHOME/lib/kvstore.jar securityconfig \
config merge-trust -root $KVROOT \
-source-root $NEW_KVROOT

java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT
java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar start -root $KVROOT& 
```
Note:

You do not need to update the client truststore if the new certificates are signed by the same Certificate Authority (CA).

You need to restart the SNs only if the data store has not yet been fully upgraded to Oracle NoSQL Database 24.4 or later. Once all SNs have been upgraded, they will notice the key and certificate changes without needing a restart.
Copy the updated store.keys file to the security directory on each host. Then, check that all Replication Nodes are online and restart each Storage Node one by one using the following commands:
```
java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar stop -root $KVROOT
java -Xmx64m -Xms64m -jar $KVHOME/lib/kvstore.jar start -root $KVROOT& 
```
Note:
You need to restart the SNs only if the data store has not yet been fully upgraded to Oracle NoSQL Database 24.4 or later. Once all SNs have been upgraded, they will notice the key and certificate changes without needing a restart.

For all Storage Nodes, remove the obsolete certificate mykey in store.trust. Also, rename the new certificate mykey_2 to mykey using the following command:

keytool -delete -keystore $KVROOT/security/store.trust \
-alias mykey

keytool -changealias -keystore \
$KVROOT/security/store.trust -alias mykey_2 -destalias mykey