Previous Next JavaScript must be enabled to correctly display this content

## 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.

1. 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)"

2. Replace the keystore and server truststores with your own:

       copy store.keys store.trust $NEW_KVROOT/security/

3. 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.

4. 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.

5. 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