17 Managing Certificates

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

• Rotating Certificates
  You can rotate both Oracle Key Vault-generated certificates or third-party certificates.
• Managing Console Certificates
  You can use the Oracle Key Vault management console to manage console certificates.

17.1 Rotating Certificates

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

• About Rotating Certificates
  The certificate rotation process captures all certificates in the Oracle Key Vault server. This operation does not rotate the console certificates.
• Advice for Managing Certificate Rotations
  Oracle Key Vault provides advice on the best ways to rotate certificates.
• Factors That May Affect the Certificate Rotation Process
  Factors that affect the certificate rotation process occur in all Oracle Key Vault environments.
• Rotating All Certificates
  You can use the Oracle Key Vault management console to rotate certificates.
• Checking the Overall Certificate Rotation Status
  You can use the Oracle Key Vault management console to check the overall status of a certificate rotation.
• Checking the Certificate Rotation Status for Endpoints
  You can use the Oracle Key Vault management console to check the status of a certificate rotation for endpoints.
• Post-Certificate Rotation Tasks
  After you have completed the certificate rotation, you should perform post-rotation tasks.

17.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 reenroll 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 navigate to the Endpoints page and check the Certificate Expires field.

Note:

If you do not rotate certificates before their expiration date, then all endpoints will experience downtime. In addition, upgrades and communication between the Oracle Key Vault multi-master cluster nodes will also fail. Ensure that you rotate certificates well in advance of their expiration date. You can find the expiration date of your site's certificates by selecting the System tab, then Status, and then checking the Server Certificate Expiration Date 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.

17.1.2 Advice for Managing Certificate Rotations

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

• The default alert time for a certificate expiration is 90 days, but Oracle recommends that you set it to 60 days or earlier. A certificate rotation can take time, so setting the value to a higher number enables an administrator to receive the alert early enough to plan for downtime and to take action.
• 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 server 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 reenroll all endpoints that are not in the Enrolled state. If you no longer need the endpoint, then you only need to delete it.
• In a multi-master cluster environment, do not perform any major operations in a single-node cluster where the single remaining node is in read-only restricted mode.
• After the certificate rotation is completed, you must download the RESTful services utility again so that you can have access to the updated software with the latest server certificate.

  Important: Do not use this feature if the certificates have already expired. Contact Oracle Support if you have tried using the RESTful services utility when certificates have expired.

• Do not attempt to upgrade the systems if certificates have already expired. Doing so would cause the upgrades to fail.
• Contact Oracle Support if certificates have expired and you have tried endpoint operations, using the RESTful services utility, taking backups, node operations, and so on.

17.1.3 Factors That May Affect the Certificate Rotation Process

Factors that affect the certificate rotation process occur in all Oracle Key Vault environments.

• 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 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. An endpoint can only successfully receive an update if it has at least one object uploaded to the Oracle Key Vault server. You can check if the endpoint has objects by executing the okvutil list command.

• 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 reenroll 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.

17.1.4 Rotating All Certificates

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

The rotation process is initiated when you generate the server certificate. When you activate the process of rotating the certificates, in a multi-master cluster environment, the certificates in all endpoints are rotated as well. After the endpoints have received their new certificates, Oracle Key Vault rotates its own server certificates. Perform the steps in this topic to complete the rotation process throughout the Oracle Key Vault environment.

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, then Settings from the left navigation side bar.
4. In the Certificates area, click Server Certificate.
   By default, Server Certificate is selected.
5. In the Manage Server Certificate window, select Generate Server 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 multi-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. ("Activated" means that the new certificate will not be put into use until the next step of this process.) 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, select Settings in the left navigation bar, and then select Manage Server Certificate in the Certificates area.
7. In the Manage Server Certificate window, 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.

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 Status 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. In a multi-master cluster environment, after the process of activation has begun, the Manage Server Certificate page on each node only shows the status of rotation on that individual node. For example, it switches from showing two certifications listed to one when the process of rotation on that node has completed. To check if rotation is complete across the cluster, you must go to each individual node and check the Manage Server Certificate page on that node.

After you complete the rotation, you should configure an alert for the next time the new certificate should be rotated.

17.1.5 Checking the Overall Certificate Rotation Status

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

After all the endpoints have been updated to using the new certificate, the Oracle Key Vault server begins the process of fully rotating its own server certificates in the background.

1. Log in to Oracle Key Vault management console as a user who has the System Administrator role.
2. Select the System tab, then Settings in the left navigation side bar.
3. In the Certificates area, select Server Certificate.
   By default, Server Certificate is selected.
4. Check the Manage Server Certificate page.
   The certificate rotation process is deemed complete when the Manage Server Certificate page no longer shows two certificates listed, but only a single one that reflects the new certificate. The OKV Server Expiration Date field in the System Status page should reflect the expiration time of the new certificate 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.

17.1.6 Checking the Certificate Rotation Status for Endpoints

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

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 reenroll the endpoint.

17.1.7 Post-Certificate Rotation Tasks

After you have completed the certificate rotation, you should perform post-rotation tasks.

Do the following:

• If you had previously downloaded the Oracle Key Vault RESTful services software utility (okvrestclipackage.zip), then download it again so that you can continue to use the RESTful services utility.

  Ensure that you have fully rotated the certificate (across all nodes in a multi-master cluster environment and in the servers of a primary-standby environment) before you download okvrestclipackage.zip.

  To do so, select the Endpoint Enrollment and Software Download link on the Oracle Management console login page. Select the Download RESTful Service Utility tab, and then click Download to download the okvrestclipackage.zip file to a secure location.

  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.

• Back up all systems across the Oracle Key Vault configuration.

  It is important that you perform this backup operation after the certificate rotation is complete. Later on, if you rotate certificates in your configuration (so that the endpoints have been updated to using new certificates as well), but then restore the Oracle Key Vault server from a backup that was taken before the certificate rotation was performed, then the endpoints will not be able to connect to the restored Oracle Key Vault system.

• If the Oracle Key Vault public key has changed, re-copy the public key that appears in the Public Key field and then paste it in the appropriate configuration file, such as authorized_keys, on the destination server. Be aware that certain events may trigger a change of the public key, which means that Oracle Key Vault cannot use the backup destination until the new public key is re-copied from Oracle Key Vault to the appropriate configuration file. These events include but are not limited to certificate rotation, changing the IP address, and conversion to a cluster node.

17.2 Managing Console Certificates

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

• About Managing Console Certificates
  Oracle Key Vault enables you to install a certificate signed by a Certificate Authority (CA) for more secure connections.
• Step 1: Download the Certificate Request
  When you request the console certificate, you can suppress warning messages.
• Step 2: Have the Certificate Signed
  After you download the Oracle Key Vault certificate.csr file, you can have it signed.
• 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.
• Console Certificates in Special Use Case Scenarios
  Depending on the situation, you must perform additional steps when you use console certificates.

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

17.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. Select the System tab, and then Settings from the left navigation bar.
3. In the Certificates area, click Console Certificate.
4. In the Console Certificate page, click Generate Certificate Request.
   
   Description of the illustration 21_generate_cert_request.png
5. If you need to change the host name of the Oracle Key Vault server, which appears next to Common Name, then click Change.
   The Network Details window appears, where you can change the Host Name setting. Click Save afterward.
6. 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.
7. 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.
8. 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.

17.2.3 Step 2: Have the Certificate Signed

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

• Use any out-of-band method to have the certificate.csr file signed by a CA of your choice.

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

17.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. Select the System tab, and then Settings from the left navigation bar.
3. In the Certificates area, click Console Certificate.
4. Click Upload Certificate at the top right to display the Upload Certificate page.
5. Select Choose File to display a directory window on your local system.
6. 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.
7. 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.

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

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