1. Administrator's Guide
  2. Managing Certificates

16 Managing Certificates

In addition to Oracle Key Vault-generated certificates, you can manage third-party certificates.

16.1 Rotating Certificates

You can rotate both Oracle Key Vault-generated certificates or third-party certificates.

Parent topic: Managing Certificates

16.1.1 About Rotating Certificates

The certificate rotation process captures all certificates in the Oracle Key Vault server. This operation does not rotate the console certificates.

A certificate in Oracle Key Vault lasts 730 days. If you do not rotate the certificate (both server and endpoint certificates), then the endpoints that use the certificate cannot connect to the Oracle Key Vault server. When this happens, you must re-enroll the endpoint. To avoid this scenario, you can configure an alert to remind you to rotate the certificate before the 730-day limit is up. The rotation process handles the rotation for all certificates in one operation. You can find how much time the Oracle Key Vault server certificate has before it expires by checking the OKV Server Certificate Expiration setting on the Configure Alerts page in the Oracle Key Vault management console. To find the expiry time of the endpoints' certificates, you must to navigate to the Endpoints page and check the Certificate Expires field.

In addition to standalone environments, you can rotate certificates in primary-standby and multi-master cluster environments. In both, Oracle Key Vault automatically synchronizes the certificates in both systems in a primary-standby configuration, and in all nodes in a multi-master cluster configuration. You do not have to perform any extra configuration.

Related Topics

Parent topic: Rotating Certificates

16.1.2 Advice for Managing Certificate Rotations

Oracle Key Vault provides advice on the best ways to rotate certificates.

  • Do not initiate a certificate rotation while a node addition is in progress.
  • Do not try node operations (such as adding or disabling nodes) while a certificate rotation is in process.
  • You cannot initiate certificate rotation unless all nodes in the cluster are active. You can check if a node is active by checking the Cluster Monitoring page. (Click the Cluster tab, and then select Monitoring from the left navigation bar.)
  • In a primary-standby configuration, do not perform certificate rotation if the primary database is in read-only restricted mode. Only initiate a certificate rotation when both servers in the configuration are active and synchronized with each other.
  • If you are performing certificate rotation on a system that was upgraded from a previous release, ensure that you upgrade the endpoints as well. Endpoints whose software has not been upgraded will not receive updated credentials.
  • You cannot perform a certificate rotation while a backup operation or a restore operation is in progress.
  • Before performing a certificate rotation, back up the Oracle Key Vault system.
  • In order for the certificate rotation process to fully complete, you must delete and re-enroll all endpoints that are not in the Enrolled state. If you no longer need the endpoint, then you only need to delete it.

Parent topic: Rotating Certificates

16.1.3 Factors That May Affect the Certificate Rotation Process

  • Each cluster node only generates certificates for a small set of endpoints. These endpoints are those whose creator node (the node on which the certificates are generated) it is. (You can find an endpoint's creator node in the Oracle Key Vault management console by going to the Endpoints page, and then looking for the creator node for each endpoint.) If all endpoints were created before an upgrade from Oracle Key Vault release 12.2, then it is possible that they may all be associated with one single cluster node. This can make the rotation process slower than if the endpoints had been created on different cluster nodes.
  • During the rotation process, Oracle Key Vault rotates endpoints in batches on each node of the cluster, with a maximum number of endpoints that are allowed to be in the rotated state at any one time. At least one of those rotated endpoints must receive its new certificates and acknowledge receipt (involving at least two communications with the server) before the server moves on to processing another endpoint. If all endpoints are considered to have been created on a single Oracle Key Vault cluster node, then the rotation process may degenerate to rotating a few endpoints at a time across the cluster.
  • In order to receive the new certificates, the endpoint must reach out to the node on which its certificates have been generated (that is, the creator node). In a multi-master cluster configuration, whenever the endpoint attempts to make a connection to Oracle Key Vault, it performs the following actions:
    • First, it obtains the list of server IPs from its configuration file (okvclient.ora).
    • Next, it picks one at random from those in the cluster subgroup to which the endpoint’s creator node belongs.

      The endpoint reaches out to a random Oracle Key Vault cluster node, and not necessarily to its creator node. This means that even if the Oracle Key Vault management console shows that the endpoint has had its certificates rotated, the endpoint may not receive the new certificates for some considerable period of time, despite making repeated attempts to reach out to the Oracle Key Vault cluster.

  • If a given endpoint does not receive its rotated certificates due to network or other issues, or is in the "Suspended" state, Oracle recommends that you re-enenroll the endpoint, or even delete it. This will allow the certificate rotation process to continue on to completion. You can find the current certificate rotation status by going to the Endpoints page and looking for Common Name of Certificate Issuer.

Related Topics

Parent topic: Rotating Certificates

16.1.4 Rotating All Certificates

You can use the Oracle Key Vault management console to rotate certificates.

Before beginning certificate rotation, ensure that the recovery passphrase is the same across all multi-master cluster nodes.
  1. Back up Oracle Key Vault.
  2. Log in to Oracle Key Vault management console as a user who has the System Administrator role.
    In a primary-standby environment, log in to the primary Oracle Key Vault server. In a multi-master cluster environment, you can log in to any node in the cluster. Oracle recommends that you initiate the rotation from one node at a time. Do not perform multiple rotations on different nodes at once.
  3. Select the System tab.
  4. Select Manage Server Certificate.
  5. In the Manage Server Certificate page, click Generate System Certificate.
  6. In the confirmation dialog box, select OK.
    This creates a new CA certificate, but does not enable it. At this stage, endpoints can still use their old credentials to connect using the previous certificate. The Old Certificate area shows the details of the currently active CA. The New Certificate area shows that the certificate has been rotated and displays its common name. If you want to cancel the rotation process, click Abort to cancel the process and clean up the new CA directory that was generated.
    In a mult-master cluster environment:
    • After the certification rotation process is initiated, the details of the new certificate that was generated are shown on the node on which you initiated the rotation. After a few minutes, if you refresh the Manage Server Certificate page on all of the other nodes, this page should show that a message saying that the new certificate is being propagated to that node.
    • The certificate will be propagated to all nodes, but not activated. Depending on the number of nodes in the cluster, it may take some time to complete the propagation process.
    • You can cancel the certificate rotation only up to the point that 1) all nodes in the cluster have received the certificates, and 2) each node has notified the other nodes that it has received the certificate. At this point, the Abort button will disappear and only Activate Certificate remains. The certificate activation process can only take place when all nodes in the cluster no longer have the Abort button appearing.
    • Periodically refresh the Manage Server Certificate page, in case there have been changes to the status. For example, you should refresh this page if you want to determine that the Abort button is no longer showing and the Activate Certificate button has appeared. To access this page, select the System tab and then select Manage Server Certificate from the left menu.
  7. When the Activate Certificate button appears and is enabled, click it.
    Clicking Activate Certificate begins the process of putting the new Oracle Key Vault CA into use. When it completes, the endpoints should be able to connect to the Oracle Key Vault server using either the new or the old Oracle Key Vault CA. This process may take a few minutes to complete. You cannot cancel the rotation process after you click Activate Certificate.
    In a multi-master cluster environment, Activate Certificate applies the certificate to all nodes in the cluster. The certificate activation process can only take place when all nodes in the cluster no longer have the Abort button appearing. It takes a few minutes for the remaining nodes to be updated. Ensure that you click Activate Certificate on only one node before you refresh the Manage Server Certificates page on the other nodes. Wait a few minutes for the screen to refresh. (You only need to click Activate Certificate on one node, not multiple nodes.) Note that the Manage Server Certificates page on all nodes other than the one that you clicked Activate Certificate on may show no change in status for a few minutes, until the process starts to take effect on those nodes.
  8. In the confirmation dialog box, click OK.
    A message appears saying that the automatic certificate update of the endpoints is in progress. In the background, Oracle Key Vault starts regenerating certificates for its endpoints, for a few endpoints at a time (so that not all endpoints are updated at once). To check if the credentials for an endpoint have been updated, click the Check Endpoint Progress button. The Endpoints page appears. If, for a given endpoint, the Common Name of Certificate Issuer field shows the common name of the old CA, the new credentials have not yet been generated. However, if, for existing endpoints, the field shows Updating to Current Certificate Issuer, the process has begun. Endpoints should be able to retrieve updated credentials a few minutes after this status has changed.
    After the new credentials have been generated for a given endpoint, when the endpoint next makes a connection to the Oracle Key Vault server, the new credentials for the certificate are sent over to the endpoint. After an endpoint has received its updated credentials from the Oracle Key Vault server, it must try to connect to the Oracle Key Vault server to let the server know that it has successfully received the credentials. You should periodically check the status of replication across the cluster by viewing either the Cluster Monitoring page or the Cluster Management page. (To access either of these pages, click the Cluster tab, and then select either Management or Monitoring in the left navigation bar.) When the endpoint successfully receives the credentials, the value in the Common Name of Certificate Issuer field for that endpoint on the Endpoints page should reflect the common name of the new Oracle Key Vault CA certificate.
  9. If you had previously downloaded the Oracle Key Vault RESTful services software utility (okvrestservices.jar), then download it again so that you can continue to use the RESTful services utility.

    If you are using KMIP REST, then you do not need to perform this step because the okvutil endpoint that contains the okvclient.ora has received the updates.

After all the endpoints have been updated to using the new CA, the Oracle Key Vault server begins the process of fully rotating its own server certificates in the background. The process can be deemed to be complete when the Manage Server Certificate page no longer shows two certificates listed, but only a single one reflecting the new CA certificate. The OKV Server Expiration Date field in the System Settings page should reflect the expiration time of the new CA certificate as well. In a multi-master cluster environment, you can initiate another certificate rotation only after all the nodes have completed their certification rotation process.
After you complete the rotation, you should configure an alert for the next time the new certificate should be rotated. To configure the alert, in the Configure Alerts page, select the check box after OKV Server Certificate Expiration.

Related Topics

Parent topic: Rotating Certificates

16.1.5 Checking the Certificate Rotation Status

You can use the Oracle Key Vault management console to check the status of a certificate rotation.

You should also check the Manage Server Certificates page.
  1. Log in to Oracle Key Vault management console as a user who has the System Administrator role.
  2. Select the Endpoints tab.
  3. Select Endpoints.
    On the Endpoints page, you can see a status of the rotation process for the certificate (Updating to current certificate issuer) in the Endpoints page. When it is complete, it will show the name of the common name of the new Oracle Key Vault CA.
    If there are errors with the certificate rotation of an endpoint, then Oracle recommends that you re-enroll the endpoint.

Parent topic: Rotating Certificates

16.2 Managing Console Certificates

You can use the Oracle Key Vault management console to manage console certificates.

Parent topic: Managing Certificates

16.2.1 About Managing Console Certificates

Oracle Key Vault enables you to install a certificate signed by a Certificate Authority (CA) for more secure connections.

You can upload upload a certificate that was signed by a third-party CA to Oracle Key Vault to prove its identity, encrypt the communication channel, and protect the data that is exchanged throughout the Oracle Key Vault system.

To install a console certificate, you must generate a certificate request, get it signed by a CA, and then upload the signed certificate back to Oracle Key Vault.

Parent topic: Managing Console Certificates

16.2.2 Step 1: Download the Certificate Request

When you request the console certificate, you can suppress warning messages.

These warning messages appear when the browser detects a mismatch between the attributes of the server certificate and the attributes of the login session to the Oracle Key Vault management console.
  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
  2. Click the System tab, then Console Certificate from the System menu to display the Console Certificate page.
  3. Click Generate Certificate Request on the top right to display the Generate Certificate Request page.
  4. If you need to change the host name of the Oracle Key Vault server, which appears next to Common Name, then click Change.
    The System Settings page appears. Change the host name in the Network page.
  5. Check the box to the left of text Suppress warnings for IP based URL access if you want to suppress browser warnings for server IP address changes.
  6. Enter the required fields marked with an asterisk, Organization Name and Country/Region.
    You must enter values for these fields in order to proceed without errors. You may enter values in the rest of the optional fields as needed.
  7. Click Submit and Download to the top right.
    A directory window appears, where you can save the certificate.csr file. Select a directory and save the file to a secure location.

Parent topic: Managing Console Certificates

16.2.3 Step 2: Have the Certificate Signed

After you download the Oracle Key Vault certificate.csr file, you can have it signed.

To have the certificate signed, you can use any out-of-band method to have it signed by a CA of your choice.

Afterward, you can then upload the signed certificate back to Oracle Key Vault using the management console.

Parent topic: Managing Console Certificates

16.2.4 Step 3: Upload the Signed Certificate to Oracle Key Vault

In addition to uploading the signed certificate, you can optionally choose to deactivate and re-activate the certificate.

  1. Log in to the Oracle Key Vault management console as a user who has the System Administrator role.
  2. Click the System tab and then click Console Certificate in the left System menu to display the Console Certificate page.
  3. Click Upload Certificate at the top right to display the Upload Certificate page.
  4. Click Choose File to display a directory window on your local system.
  5. Navigate to the directory where you stored the signed certificate and select it. When you are done, you will see the file name to the right of text Choose File.
    After you select the certificate, you will see the file name to the right of Choose File.
  6. Click Upload.
    If the certificate is installed with no errors, then you will see its details appear in a new Uploaded Certificate Details panel just below Console Certificate.
At this stage, if you need to, you can deactivate the certificate by clicking Deactivate on the top right of the Uploaded Certificate Details section. When you deactivate the certificate, the Deactivate button is replaced by an Apply Certificate button. You can click this button to re-activate the certificate.

Parent topic: Managing Console Certificates

16.2.5 Console Certificates in Special Use Case Scenarios

Depending on the situation, you must perform additional steps when you use console certificates.

  • Primary-standby environments: If you want to use a console certificate in a primary-standby configuration, then you must install it on the primary and standby servers first, and then pair them.

  • RESTful services: When you install a console certificate, you must download the RESTful software utility again before you can use the new certificate.

  • Restored data from a backup: If you install a console certificate, perform a backup, and then restore another Oracle Key Vault appliance from that backup, you must re-install the console certificate on the new server before you can use it. The restore process does not copy the console certificate.

Parent topic: Managing Console Certificates