19 Managing Service Certificates
This chapter explains about Oracle Key Vault-generated certificates, you can learn how to manage self-signed and third-party certificates.
- Overview of Oracle Key Vault Certificates
Oracle Key Vault uses certificates for various purposes including endpoint authentication, server authentication, and securing the communication channels using the TLS protocol. - Certificates Validity Period
You can set the validity periods for Oracle Key Vault certificates to meet the security, compliance, and operational requirements. - Monitoring Certificates Expiry
Proactively set alerts and monitor the expiry dates of the Oracle Key Vault certificates and rotate them before they expire. - Managing CA Certificate Rotation
You can use the Oracle Key Vault management console to rotate the CA certificate before the certificate gets expired. The new CA certificate can be a self-signed Root CA certificate or an intermediate CA certificate. - Managing Server Certificates and Node Certificates Rotation
Use the Oracle Key Vault management console to rotate server or node certificates. - Managing the Oracle Key Vault CA Certificate After Expiry
You cannot start a CA certificate rotation when the Oracle Key Vault CA certificate has already expired. - Configuring Oracle Key Vault with an Alternate Hostname
You can configure Oracle Key Vault with an alternate hostname, that is, a fully-qualified domain name (FQDN) or a secondary IP address.
19.1 Overview of Oracle Key Vault Certificates
Oracle Key Vault uses certificates for various purposes including endpoint authentication, server authentication, and securing the communication channels using the TLS protocol.
The TLS protocol protects communication between the Oracle Key Vault server or node, and the endpoints. The TLS protocol also protects the back channel communication between the Oracle Key Vault nodes in the cluster deployment or Oracle Key Vault servers in the primary-standby deployment. The TLS certificates used by endpoints and the Oracle Key Vault servers or cluster-nodes are issued by the Oracle Key Vault itself using its CA certificate. The Oracle Key Vault’s CA certificate may be a self-signed Root CA or an intermediate CA.
Oracle Key Vault generates the TLS certificates with the exception of the intermediate CA certificate.
CA Certificate
The CA certificate is a self-signed Root CA or an intermediate CA certificate that the Oracle Key Vault uses to issue endpoint certificates, as well as server or node certificates. The self-signed Root CA certificate is generated at the time of Oracle Key Vault installation. Customers can choose to replace it with an intermediate CA certificate that is signed by the organization's own internal CA or a third-party CA post-installation or post-upgrade. The CA certificate is the same for all nodes in a multi-master cluster deployment and for both the primary and standby servers of a primary-standby deployment. The CA certificate is different from the console certificates.
If you do not rotate the CA certificate before it expires, none of the endpoints can communicate with the Oracle Key Vault server or any node of the Oracle Key Vault cluster and all the endpoints will face a downtime. In the cluster deployment none of the Oracle Key Vault nodes will be able to communicate with each other and in case of primary-standby, the communication between primary and standby servers will breakdown.
Note:
The CA Certificate must be rotated before it expires to prevent outage to endpoints. Start the CA certificate rotation several weeks in advance of CA certificate expiry to prevent outage to the Oracle Key Vault deployment and endpoints.Rotating CA certificates also rotates the server or node certificates and endpoint certificates.
Server and Node Certificate
Server or Node Certificate is the TLS certificate of the Oracle Key Vault server or a cluster node. While in a standalone or primary-standby deployment, Oracle Key Vault uses server certificates to communicate with its endpoints. In a multi-master deployment of Oracle Key Vault, each cluster node has its own node certificate. Oracle Key Vault cluster nodes use node certificates to communicate with each other and with the endpoints.
These certificates are referred to as server certificates for standalone and primary-standby systems and as node certificates in multi-master cluster configurations. The Oracle Key Vault CA certificate is used to issue these certificates.
Rotate the server or node certificate before they expire as described in section Managing Server Certificates and Node Certificates Rotation. The CA and endpoint certificates are not rotated when server or node certificates are rotated.
Note:
Rotating the node certificate in a multi-master cluster deployment is a per-node operation.If the server certificate is not rotated in a standalone deployment before it expires, none of the endpoints can communicate to the Oracle Key Vault server and all the endpoints will face a downtime. If you do not rotate the server certificate in a primary-standby deployment before it expires, then none of the endpoints can communicate to the primary server and all the endpoints face a downtime.
If you do not rotate the node certificate in cluster deployment before it expires, the endpoints use the other nodes for the endpoint operations like fetching a key. However, the inter-node communication will be impacted and operations like creating a new endpoint or creating a new wallet will be impacted.
Note:
If all of the node certificates in the cluster deployment have expired, endpoints cannot communicate with any node in the multi-master cluster.Endpoint Certificate
Each endpoint is issued a unique endpoint TLS certificate that is used to authenticate the endpoint with the Oracle Key Vault. The Oracle Key Vault Certificate Authority (CA) certificate is used to issue the endpoint certificates. Rotate an endpoint's certificate before it expires as described in section Rotating Endpoint Certificates . The CA or server or node certificates are not rotated when endpoint certificates are rotated.
If an endpoint is not rotated before its certificate expires, the endpoint experiences downtime and is required to be re-enrolled.
Related Topics
Parent topic: Managing Service Certificates
19.2 Certificates Validity Period
You can set the validity periods for Oracle Key Vault certificates to meet the security, compliance, and operational requirements.
- About Certificates Validity Period
Compliance and best security practices have different requirements for certificate validity depending upon the purpose and use of the certificate. - Setting Validity Period of Self-Signed Root CA Certificate
You can configure the validity period for the self-signed Root certificate authority (CA) certificate from the Oracle Key Vault management console. - Configuring Certificate Validity Period for Server and Node Certificates
You can configure the validity period for server or node certificates in the Oracle Key Vault management console. - About Configuring Certificate Validity Period for Endpoint Certificates
You can set the validity period for the endpoint certificates in the Global Endpoint Configuration parameters.
Parent topic: Managing Service Certificates
19.2.1 About Certificates Validity Period
Compliance and best security practices have different requirements for certificate validity depending upon the purpose and use of the certificate.
For simplicity, up until Oracle Key Vault release version 21.3 all the three certificates, the Oracle Key Vault CA, server or node, and endpoint certificate, including the self-signed Root CA certificate, are rotated together. However, the server or node, endpoint, and CA certificates can have different validity periods. Generally, the validity period requirements for the endpoint and server or node certificates are different than that of the CA certificate. You can configure the validity periods of the self-signed Root CA, the server or node certificates and the endpoint certificates independently with different values. You can rotate the server or node certificates independent of the CA certificate rotation. Starting in Oracle Key Vault release 21.5, you can rotate the endpoint certificate independently of the CA and server or node certificates.
The default and the range of the validity periods of the TLS certificates in Oracle Key Vault are described below.
Table 19-1 Certificates Validity Period
| Certificate | Default Validity (out of the box) | Minimum Validity | Maximum Validity |
|---|---|---|---|
|
|
1095 days or 3 years |
365 days or 1 year |
3650 days or 10 years |
Intermediate CA |
Defined by signing CA | Defined by signing CA | Defined by signing CA |
|
|
365 days or 1 year |
365 days or 1 year |
1095 days or 3 years |
|
|
365 days or 1 year |
365 days or 1 year |
1095 days or 3 years |
The certificate validity period automatically determines the certificate expiry. Rotate the certificates before they expire.
You can set different validity periods for each type of certificate to meet your requirements.
Setting the validity period of certificates does not affect the validity period of existing certificates. The configured validity periods take effect when a new certificate is generated either during the certificate rotation or when you set up a new endpoint or cluster node.
The CA signing authority sets the validity period of the intermediate CA certificate.
Note:
For simplicity, until Oracle Key Vault release 21.4, all three types of certificates - self-signed Root CA certificate, server or node certificate, and the endpoint certificate had the same certificate validity period. The server or node certificates could not be rotated independently of the CA certificate rotation, nor could they be configured with different certificate validity periods. Until Oracle Key Vault release 21.5, the endpoint certificates could not be rotated independently of the CA certificate rotation.19.2.2 Setting Validity Period of Self-Signed Root CA Certificate
You can configure the validity period for the self-signed Root certificate authority (CA) certificate from the Oracle Key Vault management console.
- Click Save.
Parent topic: Certificates Validity Period
19.2.3 Configuring Certificate Validity Period for Server and Node Certificates
You can configure the validity period for server or node certificates in the Oracle Key Vault management console.
The certificate validity period takes effect the next time you rotate the server or node certificates. It will also be taken into account when you generate the server or node certificates as part of a CA certificate rotation, or when you add a new node to the cluster, to the node certificates for that new node. Irrespective of the value that the server or node certificate validity is set to, when the certificates are eventually generated, Oracle Key Vault ensures that their expiry date is less than that of the CA certificate.
Parent topic: Certificates Validity Period
19.2.4 About Configuring Certificate Validity Period for Endpoint Certificates
You can set the validity period for the endpoint certificates in the Global Endpoint Configuration parameters.
The default value is 365 days (1 year). You can set a maximum validity period of 1095 days (3 years) and a minimum validity period of 365 days (1 year).
The certificate validity period takes effect the next time that an existing endpoint is rotated or re-enrolled, or when a new endpoint is added. Irrespective of the value that the endpoint certificate validity is set to, when the endpoint is eventually rotated, Oracle Key Vault ensures that the endpoint certificate expiry date is less than that of the CA certificate.
19.3 Monitoring Certificates Expiry
Proactively set alerts and monitor the expiry dates of the Oracle Key Vault certificates and rotate them before they expire.
- Monitoring Certificates Expiry Using Certificate Expiration Alerts
Set expiration alerts as reminders to rotate the certificates before their expiration date. - Finding the Expiration Date of Endpoint Certificates
You can find the expiration date of endpoint certificates in the Oracle Key Vault management console. - CA Certificate Expiration Date on Status Page
You can check the CA Certificate Expiration Date, which is the expiration date of the Oracle Key Vault CA certificate, from the Status page. - Server and Node Certificate Expiration on Status Page
You can check the Server Certificate Expiration Date (in a standalone or primary-standby environment) or the Node Certificate Expiration Date (in a multi-master cluster environment) from the Status page. - Finding the Expiration Date of the CA Certificate
You can find how much time the Oracle Key Vault CA certificate has before it expires by navigating to the Service Certificates page. - Finding the Expiration Date of Server Certificates and Node Certificates
You can find the expiration date of server certificates and node certificates in the Oracle Key Vault management console.
Parent topic: Managing Service Certificates
19.3.1 Monitoring Certificates Expiry Using Certificate Expiration Alerts
Set expiration alerts as reminders to rotate the certificates before their expiration date.
Expiration of a certificate, especially the CA certificate, breaks the endpoint and Oracle Key Vault communication, and impacts the operations of one or more endpoints to the extent of stopping of endpoint operations completely. In addition, upgrades and communication between the Oracle Key Vault multi-master cluster nodes may also fail. Ensure that you rotate certificates much before their expiration date.
To avoid this scenario, Oracle recommends that you configure alerts as a reminder to rotate the certificates before they expire. There are separate alerts for endpoint certificate expiration, server or node certificate expiration, and CA certificate expiration.
If using an intermediate CA certificate, monitor the certificate expiry of the CA certificate trust chain independently. The intermediate CA certificate must be rotated before any of the certificates in its certificate trust chain expires. This prevents an outage to endpoints. Start the CA certificate rotation several weeks in advance of CA certificate expiry to prevent outage to the Oracle Key Vault deployment and endpoints .
Note:
- If you are using an intermediate CA certificate, you must monitor the certificate expiry in the CA trust chain independently. The expiration of any certificate in the CA trust chain causes an outage to Oracle Key Vault.
- You must promptly address the certification expiration alerts by rotating the certificates indicated by the alert. Depending upon your deployment, the rotation of the Oracle Key Vault CA certificate, in particular, may take a very long time (in the order of several days). Begin the CA certificate rotation process well before CA certificate expiry to avoid outages.
19.3.2 Finding the Expiration Date of Endpoint Certificates
You can find the expiration date of endpoint certificates in the Oracle Key Vault management console.
Related Topics
Parent topic: Monitoring Certificates Expiry
19.3.3 CA Certificate Expiration Date on Status Page
You can check the CA Certificate Expiration Date, which is the expiration date of the Oracle Key Vault CA certificate, from the Status page.
The CA Certificate Expiration Date field in the System Status page reflects the expiration date of the CA certificate. The CA Certificate Expiring In on the System Status page shows how many days are left to expire for the CA certificate.
To navigate to the System Status page, select the System tab.
- Log in to the Oracle Key Vault management console as a System
Administrator.
In a multi-master cluster environment, you can log in to any node in the cluster.
- Select the System tab and then Status from the left navigation side bar.
- Check the CA Certificate Expiration Date field.
- Check the CA Certificate Expiring in field.
Description of the illustration 218_ca_certificate_details_status_page.png
Oracle Key Vault raises an alert for the CA certificate expiration when the CA Certificate Expiration Date falls within the alert threshold period. You can also monitor the CA Certificate Expiration Date over SNMP.
Related Topics
Parent topic: Monitoring Certificates Expiry
19.3.4 Server and Node Certificate Expiration on Status Page
You can check the Server Certificate Expiration Date (in a standalone or primary-standby environment) or the Node Certificate Expiration Date (in a multi-master cluster environment) from the Status page.
The Server Certificate Expiration Date field on the System Status reflects the expiration date of the server certificate. The Server Certificate Expiring In on the Status page shows how many days are left for the server certificate to expire. In a multi-master cluster environment, these fields are called Node Certificate Expiration Date and Node Certificate Expiring In. The Node Certificate Expiration Date field reflects the expiration date of the node certificate, while Node Certificate Expiring In shows how many days are left for the node certificate to expire.
Note:
In a multi-master cluster environment, log into the node whose node certificate expiration date you wish to check. Different nodes can have different node certificate expiration dates.
To navigate to the Status page, select the System tab.
- Log in to the Oracle Key Vault management console as a System Administrator.
- Select the System tab and then Status from the left navigation side bar.
- Check the Server Certificate Expiration Date field. In a multi-master cluster environment, this field is Node Certificate Expiration Date.
- Check the Server Certificate Expiring in field. In a multi-master cluster environment, this field is Node Certificate Expiring In.
Description of the illustration 218_ca_certificate_details_status_page.png
Oracle Key Vault raises an alert for the Server or Node certificate expiration, when the server or node certificate expiration date falls within the configured alert threshold period. You can also monitor the Server Certificate Expiration Date over SNMP.
Parent topic: Monitoring Certificates Expiry
19.3.5 Finding the Expiration Date of the CA Certificate
You can find how much time the Oracle Key Vault CA certificate has before it expires by navigating to the Service Certificates page.
- In the Current CA Certificate area, check the
End Date setting to know when the CA certificate is
expiring.The Expiring In setting shows the number of days left for the CA certificate to expire.
Note:
You can also check the CA certificate expiration date on the Oracle Key Vault System Status page.
Related Topics
Parent topic: Monitoring Certificates Expiry
19.3.6 Finding the Expiration Date of Server Certificates and Node Certificates
You can find the expiration date of server certificates and node certificates in the Oracle Key Vault management console.
- In a multi-master cluster environment:
- In the Current Node Certificate area, select Manage Node Certificate. Under Current Node Certificate, check the End Date setting. The Expiring In setting also shows the number of days left for the node certificate expiry.
-
You can view the end dates and time to expire of all the node certificates in the cluster in the Cluster Node Certificate Details area.
Note:
You can also check the Server Certificates and Node Certificates expiration date on the Oracle Key Vault System Status page.Related Topics
Parent topic: Monitoring Certificates Expiry
19.4 Managing CA Certificate Rotation
You can use the Oracle Key Vault management console to rotate the CA certificate before the certificate gets expired. The new CA certificate can be a self-signed Root CA certificate or an intermediate CA certificate.
- Steps for Managing CA Certificate Rotation
A user with the System Administrator role can perform CA certificate rotation when the CA is expiring. The user can set up a new self-signed Root CA or an intermediate certificate and put the new certificate into use. The server or node certificates, and the endpoint certificates are also rotated as part of this process. - Checking for Self-Signed Root CA or Intermediate CA Certificate
Oracle Key Vault uses either a self-signed root CA certificate or an intermediate CA certificate. - Setting the Key Length of the CA Certificate
You can select between the 2048-bits or 4096-bits key length values for the certificate authority (CA) certificate key length. - Setting the Validity of Self-Signed Root CA Certificate
You can set the number of days for the validity of a self-signed Root certificate authority (CA) certificate. - Setting Up the Intermediate CA Certificate
Use the Oracle Key Vault management console to generate the certificate signing request for the intermediate CA certificate, and upload the intermediate CA certificate signed by a trusted third party. - Rotating CA Certificate
Use the Oracle Key Vault management console to rotate CA certificate and enable either a self-signed root CA certificate or an intermediate CA certificate. - Setting the Endpoint Certificate Rotation Batch Size
The endpoint certificate rotation batch size value represents the number of endpoints that can be in theROTATEDstate on a given Oracle Key Vault server or node during the CA certification rotation process. - Setting the Endpoint Certificate Rotation Sequence
In a multi-master cluster environment, when you rotate certificate authority (CA) certificate, you broadly set the order in which endpoints can be rotated by ordering cluster subgroups. - Checking Overall Certificate Rotation Status
Use the Oracle Key Vault management console to check the overall status of a certificate rotation. - Checking Certificate Rotation Status for Endpoints
Use the Oracle Key Vault management console to check the status of a certificate rotation for endpoints. - Post-CA Certificate Rotation Tasks
After you complete the CA certificate rotation, perform the post-rotation tasks. - Factors Affecting CA Certificate Rotation Process
Consider these factors that affect the certificate authority (CA) certificate rotation process in cluster environments. - Guidelines for Managing CA Certificate Rotations
Consider these Oracle Key Vault guidelines for managing certificate authority (CA) certificate.
Parent topic: Managing Service Certificates
19.4.1 Steps for Managing CA Certificate Rotation
A user with the System Administrator role can perform CA certificate rotation when the CA is expiring. The user can set up a new self-signed Root CA or an intermediate certificate and put the new certificate into use. The server or node certificates, and the endpoint certificates are also rotated as part of this process.
Parent topic: Managing CA Certificate Rotation
19.4.2 Checking for Self-Signed Root CA or Intermediate CA Certificate
Oracle Key Vault uses either a self-signed root CA certificate or an intermediate CA certificate.
CA, or start with OKV_CA_, then the current CA certificate is a self-signed root CA. Otherwise, the current CA certificate is an intermediate CA. Additionally, in the intermediate CA certificate, the Certificate Issuer field displays the common name of the trusted third party.
Related Topics
Parent topic: Managing CA Certificate Rotation
19.4.3 Setting the Key Length of the CA Certificate
You can select between the 2048-bits or 4096-bits key length values for the certificate authority (CA) certificate key length.
Parent topic: Managing CA Certificate Rotation
19.4.4 Setting the Validity of Self-Signed Root CA Certificate
You can set the number of days for the validity of a self-signed Root certificate authority (CA) certificate.
Related Topics
Parent topic: Managing CA Certificate Rotation
19.4.5 Setting Up the Intermediate CA Certificate
Use the Oracle Key Vault management console to generate the certificate signing request for the intermediate CA certificate, and upload the intermediate CA certificate signed by a trusted third party.
Uploading the intermediate CA certificate does not enable it (that is, uploading the intermediate CA certificate does not put it into use). Perform the following steps to rotate the CA certificate and enable the uploaded intermediate CA certificate:
- Enter information about your organization in the following fields:
- Organization Name
- Country/Region
- Organization Unit
- City
- State/Province
- After Oracle Key Vault generates the certificate request, in the CA
Certificate Details area, select Download Certificate
Request to download the certificate request file.
The certificate signing request file is named as follows:
OKV_Intermediate_CA_Certificate.csrThe Intermediate CA Certificate Signing Request Details area shows the details of certificate signing request.
At this stage, the current CA certificate is still enabled in Oracle Key Vault. The Current Certificate area displays the details of the currently active CA. If you want to cancel the setup of the intermediate CA certificate, then click Abort.
Description of the illustration 214_ca_download_certificate_request.png - Upload the intermediate CA certificate. In the CA Certificate Details area, select Choose File for Intermediate CA Certificate to find and select the intermediate CA certificate file, and then click Upload. In a multi-master cluster environment, you must upload the intermediate CA certificate on the same node where the certificate signing request was downloaded.
- Upload the chain of trust for the intermediate CA certificate. In the
CA Certificate Details area, select Choose
File for Certificate Chain of Trust to
find and select the chain of trust file, and then click
Upload.
Description of the illustration 214_upload_ca_intermediate_and_trust_chain_certificate.pngThe chain of trust file is a PEM bundle that consists of the CA certificate used by the external signing authority to sign the intermediate certificate signing request,
OKV_Intermediate_CA_Certificate.csrfile, as well as all of the certificates in that CA's trust chain, in reverse order.For example, suppose that
OKV_Intermediate_CA_certificate.csrhas been signed by the external signing authority, and that the generated certificate is calledOKV_Intermediate_CA_certificate.crt. Also suppose that the external signing authority used its CA certificate, CACertA, to generateOKV_Intermediate_CA_certificate.crtfromOKV_Intermediate_CA_certificate.csr. CACertA was, in turn, issued by CACertB. CACertB was issued by CACertC. The certificate trust chain file that you must upload must consist of CACertA, CACertB, CACertC, in that order, in the PEM bundle format. It should NOT containOKV_Intermediate_CA_certificate.crt. For example, assuming that CACertA, CACertB, and CACertC are all certificates in PEM format, where each certificate file is of the form:-----BEGIN CERTIFICATE----- <cert contents> -----END CERTIFICATE----The certificate chain of trust would look like this:
-----BEGIN CERTIFICATE----- <CACertA contents> -----END CERTIFICATE---- -----BEGIN CERTIFICATE----- <CACertB contents> -----END CERTIFICATE---- -----BEGIN CERTIFICATE----- <CACertC contents> -----END CERTIFICATE----In a multi-master cluster environment, you must upload the certificate chain of trust on the same node where you uploaded the intermediate CA certificate.
As part of the upload, Oracle Key Vault performs the following validations:- The uploaded intermediate CA is verified using the uploaded certificate chain of trust.
- The certificate chain of trust has a depth of less than or equal to 8.
After the uploads are successful, the Rotate CA Certificate button is displayed.
Go to section Rotating CA Certificate to enable the uploaded intermediate CA certificate.
Note:
- If you choose to set up an intermediate CA certificate, it is recommended that the certificate signature algorithm is a valid SHA-2 algorithm, such as sha256.
- If you choose to set up an intermediate CA certificate, ensure that the certificate can be used as a CA for both TLS clients and servers. This can be verified by checking the certificate's properties.
Related Topics
Parent topic: Managing CA Certificate Rotation
19.4.6 Rotating CA Certificate
Use the Oracle Key Vault management console to rotate CA certificate and enable either a self-signed root CA certificate or an intermediate CA certificate.
Perform these steps to complete the CA certificate rotation process throughout the Oracle Key Vault environment.
- In the Manage CA Certificate page, you may set endpoint
certificate rotation controls - batch size and in multi-master cluster
deployments, sequence.
In a multi-master cluster environment, if necessary, choose the sequence in which the endpoint certificates should be rotated as described in section Setting the Endpoint Certificate Rotation Sequence
Description of the illustration 214_endpoint_certiface_rotation_and_ca_certificate.png - In the confirmation dialog box, click OK.
If you enable a self-signed root CA certificate, a new self-signed root CA certificate is created. In a multi-master cluster environment, Oracle Key Vault distributes and installs the newly created self-signed root CA certificate or uploaded intermediate CA certificate to all nodes of the cluster. In a primary-standby environment Oracle Key Vault distributes and installs these certificates to the standby. In case of a standalone environment, Oracle Key Vault simply installs the certificate that you enable.
At this stage, the endpoints continue to use the certificates issued using the previous CA certificate. The Old CA Certificate area displays the details of the currently active CA. The New CA Certificate area displays the certificate you have rotated along with its common name. Additionally, once a CA certificate rotation has begun, a banner is displayed, indicating that a CA certificate rotation is in progress and the number of days left to expiration of the old CA. It continues to be displayed until CA certificate rotation is complete. The banner is periodically updated with the number of days left to expiration of the old CA, and continues to be displayed until CA certificate rotation is complete.
If you want to cancel the rotation process, click Abort CA Certificate Rotation.
The Abort CA Certificate Rotation operation is available for initial few minutes. After this, when the Abort CA Certificate Rotation button is no longer visible, Oracle Key Vault automatically begins the process of enabling the new Oracle Key Vault CA certificate.
Note:
In Oracle Key Vault 21.4 and earlier, CA certificate rotation involved two steps: Start CA Certificate Rotation, followed by Activate CA Certificate. Starting with Oracle Key Vault 21.5, it is now a single-step process initiated by Start CA Certificate Rotation. Please exercise caution and initiate CA certificate rotation only when fully ready to do so.In a multi-master cluster environment, note the following:
- After the start of the certification rotation process, the details of the new certificate that was generated is displayed on the node on which you started the CA rotation. If you refresh the Manage CA Certificate page on all of the other nodes, this page displays a message that the new certificate is propagated to that node.
- To access this page, select the System tab, select Settings in the left navigation bar, select Service Certificates,and then select Manage CA Certificate in the Certificates area.
- The certificate is now distributed to all the nodes. The propagation process takes a few minutes to complete.
- You can abort the certificate rotation before the point
where:
- All nodes in the cluster have received the new CA certificates.
- Each node has notified the other nodes that it has received the certificate.
Periodically refresh the Manage CA Certificate page, in case there are any changes to the rotation status. For example, refresh the page to determine if the Abort CA Certificate Rotation button is no longer displayed.
Oracle Key Vault automatically initiates the activation when all nodes receive the new CA certificate and displays the message,
Automatic certificate update of the endpoints is in progress.After you click on Start CA Certificate Rotation, you have only a few minutes to cancel the CA certificate rotation process. When the Abort CA Certificate Rotation button is no longer visible, the certificate rotation cannot be aborted and will proceed. It is therefore recommended that you click on Start CA Certificate Rotation only when required.
The new CA certificate takes a few minutes to propagate to all the nodes and the Manage CA Certificate page on other nodes may show no change in status. Refresh the Manage CA Certificate page on the other nodes till the following message is displayed:
Automatic certificate update of the endpoints is in progress.The new CA certificate is now activated and the Oracle Key Vault servers or nodes begin issuing new endpoint certificates signed by the new CA certificate. The endpoints can now connect to the Oracle Key Vault server or nodes using the endpoint certificate issued by either the new or the old Oracle Key Vault CA. In the background, Oracle Key Vault starts issuing certificates for its endpoints, a few endpoints at a time.
When a new certificate is generated on Oracle Key Vault for an endpoint, it is not delivered to the endpoint right away. The endpoint receives the new certificate the next time it reaches out to Oracle Key Vault, and in particular, to the server or node that has generated the certificate. After the endpoint has received the new certificate, the endpoint must connect to Oracle Key Vault a second time to let the server know that the endpoint has successfully received (and is using) the new certificate. When Oracle Key Vault receives this acknowledgment from the endpoint, Oracle Key Vault updates the Common Name of Certificate Issuer“” field for that endpoint on the Endpoints page to the common name of the new Oracle Key Vault CA certificate.
Note:
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. - To check if the credentials for an endpoint are updated, click the Check Endpoint Progress button.
Click the Check Endpoint Progress button to display the Endpoints page.
For more information, see, Checking Certificate Rotation Status for Endpoints
Related Topics
Parent topic: Managing CA Certificate Rotation
19.4.7 Setting the Endpoint Certificate Rotation Batch Size
The endpoint certificate rotation batch size value represents the number of
endpoints that can be in the ROTATED state on a given Oracle Key
Vault server or node during the CA certification rotation process.
ROTATED state when Oracle Key Vault server or node has
issued the endpoint certificate using the new CA certificate but the new
endpoint certificate is either not yet received or acknowledged by the
endpoint.
Parent topic: Managing CA Certificate Rotation
19.4.8 Setting the Endpoint Certificate Rotation Sequence
In a multi-master cluster environment, when you rotate certificate authority (CA) certificate, you broadly set the order in which endpoints can be rotated by ordering cluster subgroups.
Cluster subgroups are usually used to group endpoints in a region or data center. Since the re-issue of endpoint certificates during CA certificate rotation could be a time consuming process, it is convenient to process endpoints per cluster subgroup for operations simplicity.
Parent topic: Managing CA Certificate Rotation
19.4.9 Checking Overall Certificate Rotation Status
Use the Oracle Key Vault management console to check the overall status of a certificate rotation.
Parent topic: Managing CA Certificate Rotation
19.4.10 Checking Certificate Rotation Status for Endpoints
Use the Oracle Key Vault management console to check the status of a certificate rotation for endpoints.
Parent topic: Managing CA Certificate Rotation
19.4.11 Post-CA Certificate Rotation Tasks
After you complete the CA certificate rotation, perform the post-rotation tasks.
- If you had previously downloaded the Oracle Key Vault RESTful services software
utility (
okvrestclipackage.zip), then download it again to continue to use the RESTful services utility.Ensure that you have fully rotated the certificate, across all the nodes in a multi-master cluster environment and in the servers of a primary-standby environment, before you download
okvrestclipackage.zip.To do this, select the Endpoint Enrollment and Software Download link on the Oracle Key Vault management console login page. Select the Download RESTful Service Utility tab, and then click Download to download the
okvrestclipackage.zipfile to a secure location. -
Update the backup destinations
After the CA certificate rotation, each server or node will have been issued a new certificate. The public key of the Oracle Key Vault node or server will also have changed. You need to copy the public key that appears in the Public Key field on the Backup Destination Details page and then paste it in the appropriate configuration file, such as
authorized_keys, on the backup destination server.To do so, navigate to the System tab, then Settings in the left navigation side bar. In the System Configuration area, select Backup and Restore. Click on the Manage Backup Destination to view all backup destinations. Click on the Create button. The Public Key field will have the new public key.
-
Back up all Oracle Key Vault nodes and servers.
It is important to perform this backup operation after the certificate rotation is complete. Later, if you have to restore a backup, the backup to restore must have been initiated after the CA certificate rotation. Restoring the backup before the CA certificate rotation can make the Oracle Key Vault server available but then the endpoints will not be able to connect to the restored Oracle Key Vault server. The CA certificate of the restored system may have expired and the endpoints would be using the endpoint certificates issued by the new CA not present in the backup done before CA certificate rotation.
Parent topic: Managing CA Certificate Rotation
19.4.12 Factors Affecting CA Certificate Rotation Process
Consider these factors that affect the certificate authority (CA) certificate rotation process in cluster environments.
The duration of CA certificate rotation is determined by how quickly the CA, node, and endpoint certificates are rotated. The endpoint certificate rotation takes the most time.
During the CA certificate rotation process, Oracle Key Vault rotates certificates for endpoints in batches on each node of the cluster, with an upper limit on the number of endpoints that are allowed to be in the ROTATED state at any one time. The number of endpoints that can be in a ROTATED state at any given time on an Oracle Key Vault node is defined by the endpoint certificate rotation batch size. The endpoint must receive its new certificate from the issuing node and acknowledge the receipt of the certificate back to the issuing node. An endpoint must have created at least one object for it to receive the certificate.
Note:
Generally, the node that issues an endpoint's certificate is one of those in the endpoint's affiliated cluster subgroup.The following factors affect the endpoint certificate rotation process:
- In order to receive the new certificates, the endpoint must reach out to the issuing node on which its certificates have been generated. Since the endpoint can communicate with any node in the endpoint node scan list, the endpoint may run many operations before it reaches the creator node and receives its certificate. The endpoint also has to acknowledge the receipt of the new certificates by reaching out to a node in the cluster.
- The endpoint certificate rotation times increases with the number of nodes in the cluster. The endpoints prioritize the nodes in the local subgroup, hence consider setting a different subgroup for each node during the CA certificate rotation.
- The endpoint certificate rotation batch size applies to each node of the cluster. So, if the endpoints are created on each node evenly, each node will rotate the number of endpoints equal to the batch size simultaneously. However, if all the endpoints are created on a single node, then the certificate rotation burden for all the endpoints will fall on that one node instead of being distributed across other nodes.
- For faster endpoint certification rotation and general load balancing in the cluster, consider distributing the endpoint creation among all nodes of the cluster.
- If the endpoints were created before an upgrade from Oracle Key Vault release 12.2, then the endpoints may all be associated with one single node. This can make the rotation process slower than if the endpoints had been created on different cluster nodes.
- 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 listcommand. - For any endpoint stalling the endpoint certificate rotation, consider
endpoint re-enroll or running the
okvutil listcommand. You can also suspend or delete the endpoint.
19.4.13 Guidelines for Managing CA Certificate Rotations
Consider these Oracle Key Vault guidelines for managing certificate authority (CA) certificate.
Guidelines for Endpoint Software Versions
- For self-signed root CA certificate rotation, ensure that all the endpoints software are at version 18.2.0.0.0 or later.
- For intermediate CA certificate rotation, ensure that all the endpoints software are at version 21.4.0.0.0 or later.
- Upgrade the endpoint software to the same version as Oracle Key Vault before initiating a CA certificate rotation to ensure that the latest fixes to certificate rotation are also available on the endpoint software.
Recommendations for CA Certificate Rotation
- In a multi-master cluster environment, Oracle recommends that you initiate the rotation from one node only. Use this node to complete the CA certificate rotation process. In case a node is made unavailable during certificate rotation, pick another node and use that node to complete the rest of the CA certificate rotation process. Do not switch nodes while performing certificate rotation.
- Before performing a CA certificate rotation, back up the Oracle Key Vault system.
- If a given endpoint does not receive its re-issued endpoint certificate due to network or other issues, Oracle recommends that you re-enroll the endpoint. If it is unused and no longer needed, you can also choose to suspend or delete it.
- If an endpoint uses the persistent master encryption key cache, it is recommended that the PKCS11 Persistent Cache Refresh Window parameter should be set to a large value before initiating a CA certificate rotation process. You can find the current certificate rotation status by going to the Endpoints page and looking for Common Name of Certificate Issuer.
Checks Before Initiating CA Certificate Rotation
- Before beginning certificate rotation, ensure that the recovery pass phrase is the same across all multi-master cluster nodes.
- You cannot perform a CA certificate rotation when a backup operation or a restore operation is in progress.
- Depending on the deployment, the CA certificate rotation process can take several days to complete, begin the CA certificate rotation well in advance of the CA certificate expiry.
- Before beginning the CA certificate rotation, identify all unused endpoints and either delete or suspend them. Suspended endpoints will be skipped during a CA certificate rotation and will not be issued with a new certificate issued by the new CA. If you do not delete or suspend such endpoints, the CA certificate rotation will stall and you will need to re-enroll those endpoints to allow the rotation to complete.
- You can identify unused endpoints from the Oracle Key Vault management console by navigating to Endpoints, then clicking on the Endpoints tab in the left navigation bar. This brings up the Endpoints page, listing all endpoints in the deployment. Check the Last Active Time column to determine when a given endpoint last reached out to Oracle Key Vault. You can delete or suspend all endpoints whose Last Active Time column shows that they have been inactive.
- Ensure node addition is not in progress. Do not initiate a CA certificate rotation while a node addition is in progress.
- Ensure any node operation is not in progress. Do not try node operations (such as adding or disabling nodes) when a CA certificate rotation is in process.
- In the multi-master cluster environment, ensure all the nodes are active. Do not initiate CA certificate rotation till 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 environment, ensure the primary server is active. Do not perform CA certificate rotation if the primary server is in read-only restricted mode. Only initiate a CA certificate rotation when both servers in the configuration are active and synchronized with each other.
- Ensure endpoint certificate rotation is not in progress. Do not initiate a CA certificate rotation while an endpoint certificate rotation is being performed.
Expired CA Certificate
- Do not upgrade Oracle Key Vault if the CA certificate has already expired. The upgrade will fail.
- In Oracle Key Vault release 21.5 and later, you cannot start a CA certificate rotation if the CA has already expired. You must generate a new CA certificate manually and re-enroll all endpoints instead. See section 17.6, Managing the Oracle Key Vault CA Certificate after it has expired, for details on how to do so. In Oracle Key Vault 21.4 and earlier, contact Oracle Support.
Certificate Rotation for Non-Oracle Database
- For an endpoint that does not automatically reach out to the
Oracle Key Vault server (for example, an ACFS endpoint), use the
okvutil listcommand to fetch the endpoint certificate. - You may need to run the
okvutil listmore than once to ensure that the command reaches the cluster node that regenerated the endpoint's certificate. Also, ensure that the endpoint has access to at least one security object.
Related Topics
Parent topic: Managing CA Certificate Rotation
19.5 Managing Server Certificates and Node Certificates Rotation
Use the Oracle Key Vault management console to rotate server or node certificates.
- About Server Certificates and Node Certificates Rotation
Oracle Key Vault uses server certificates to communicate with its endpoints. Oracle Key Vault cluster nodes use node certificates to communicate with each other and with the endpoints. - Configuring Certificate Validity Period for Server and Node Certificates
You can configure the validity period for server or node certificates in the Oracle Key Vault management console. - Rotating Server Certificates and Node Certificates
You can rotate server certificates and node certificates in the Oracle Key Vault management console. - Guidelines for Rotating Server Certificates and Node Certificates
Review these guidelines before you perform a rotation of server certificates or node certificates.
Parent topic: Managing Service Certificates
19.5.1 About Server Certificates and Node Certificates Rotation
Oracle Key Vault uses server certificates to communicate with its endpoints. Oracle Key Vault cluster nodes use node certificates to communicate with each other and with the endpoints.
These certificates are referred to as server certificates for standalone and primary-standby configurations and as node certificates in multi-master cluster configurations. The Oracle Key Vault certificate authority (CA) certificate issues these certificates.
You can rotate just these certificates, independently of the CA certificate rotation process. Doing so has no impact on the certificate expiry dates of the Oracle Key Vault CA or on any endpoints.
It is useful to rotate just the server and node certificates in situations where the Oracle Key Vault CA is still valid for much longer, but the server node certification will expire soon. This can happen because the CA validity is usually longer than the server or node certification validity.
- Set the validity of the server or node certificate
- Rotate server or node certificate
19.5.2 Configuring Certificate Validity Period for Server and Node Certificates
You can configure the validity period for server or node certificates in the Oracle Key Vault management console.
The certificate validity period takes effect the next time you rotate the server or node certificates. It will also be taken into account when you generate the server or node certificates as part of a CA certificate rotation, or when you add a new node to the cluster, to the node certificates for that new node. Irrespective of the value that the server or node certificate validity is set to, when the certificates are eventually generated, Oracle Key Vault ensures that their expiry date is less than that of the CA certificate.
19.5.3 Rotating Server Certificates and Node Certificates
You can rotate server certificates and node certificates in the Oracle Key Vault management console.
19.5.4 Guidelines for Rotating Server Certificates and Node Certificates
Review these guidelines before you perform a rotation of server certificates or node certificates.
- Do not perform a certificate authority (CA) certificate rotation while a server or node certificate rotation is in progress.
- Do not perform a server or node certificate rotation while a CA certificate rotation is in progress.
- Do not perform a server or node certificate rotation while a Endpoint certificate rotation is in progress.
- Do not perform a node certificate rotation on one node while another is in progress on a different node.
- Do not alter the CA certificate validity period while a CA certificate rotation is in progress.
- Do not attempt to rotate the server certificates if the CA certificate is already expired.
- Do not alter the Server Certificate Validity (in days) field (for standalone or primary-standby environments) or Node Certificate Validity (in days) field while either a CA certificate rotation or a server or node certificate rotation is in progress.
19.6 Managing the Oracle Key Vault CA Certificate After Expiry
You cannot start a CA certificate rotation when the Oracle Key Vault CA certificate has already expired.
When the endpoints cannot communicate with Oracle Key Vault it results in an outage. As a result, in a multi-master cluster environment, Oracle Key Vault nodes cannot communicate with each other. In such a scenario, you must regenerate a new CA certificate manually using the steps outlined below.
In a multi-master cluster environment, this new CA certificate must be distributed from the generating node to all other nodes. After the CA certificate has been distributed across the cluster, you must rotate the node certificates on each cluster node in turn.
Back up Oracle Key Vault before commencing with these steps.
To manually issue a new CA certificate after the current CA certificate has expired, perform the following steps.
- Click on Check Expired CA Certificate Rotation Status.
- On successful validation, the Generate New CA
Certificate button becomes active. In a multi-master cluster
environment, an additional button, Upload CA Certificate
Bundle, is shown.
Note:
These buttons are shown on each node of a multi-master cluster only if the checks are completed successfully on that node. If the checks are unsuccessful on any cluster node or if the Generate New CA Certificate and Upload CA Certificate Bundle buttons do not show on every node of the cluster, then do not proceed to the next step. Contact Oracle Support. - Refresh the page on the Oracle Key Vault management console on which the new CA
certificate was generated. The Complete CA Certificate
Rotation button is now active. Additionally, other details of
the new CA certificate, such as the certificate common name and certificate
fingerprint are displayed.
Description of the illustration 21.5_complete_ca_certificate_rotation.png
In a multi-master cluster environment, proceed to step 12. In standalone and primary-standby environments, proceed to step 15.
Parent topic: Managing Service Certificates
19.7 Configuring Oracle Key Vault with an Alternate Hostname
You can configure Oracle Key Vault with an alternate hostname, that is, a fully-qualified domain name (FQDN) or a secondary IP address.
- About Configuring Oracle Key Vault with an Alternate Hostname
An Oracle Key Vault system is configured with an IP address when it is first installed (modifiable until it is converted to a multi-master cluster node). - Configuring Oracle Key Vault Alternate Hostname on the Management Console
You can configure alternate hostnames on the Oracle Key Vault management console. The alternate hostname must be a valid IP address or a fully-qualified domain name (FQDN). - Choosing the Alternate Hostname to Use in Endpoint Configuration
After successfully configuring Oracle Key Vault with one or more alternate hostnames, you can choose one of these alternate hostnames as the identity that endpoints will use when connecting to the Oracle Key Vault server/multi-master cluster node. - Guidelines for Configuring Alternate Hostnames
Review these guidelines before configuring an alternate hostname for endpoints to communicate with Oracle Key Vault.
Parent topic: Managing Service Certificates
19.7.1 About Configuring Oracle Key Vault with an Alternate Hostname
An Oracle Key Vault system is configured with an IP address when it is first installed (modifiable until it is converted to a multi-master cluster node).
Its endpoints communicate with it via this IP address, which they read from their
configuration files (okvclient.ora or
okvrestcli.ini). The Oracle Key Vault IP address therefore
serves as the primary identity of the server/node for communication with its endpoints.
In the case of systems deployed on Oracle Cloud Infrastructure (OCI) compute instances,
which may have two IPs (a public IP and a private IP), endpoint communication is via the
private IP by default.
Note:
- This feature is available only in standalone and multi-master cluster deployments. It is not available in primary-standby deployments (deprecated in Oracle Key Vault release 21.5).
- The networking changes to set up an alternate IP address or fully-qualified domain name are out of scope of this document. The steps below refer only to changes that must be made on the Oracle Key Vault server/node to allow endpoint communication via the new alternate hostname.
Parent topic: Configuring Oracle Key Vault with an Alternate Hostname
19.7.2 Configuring Oracle Key Vault Alternate Hostname on the Management Console
You can configure alternate hostnames on the Oracle Key Vault management console. The alternate hostname must be a valid IP address or a fully-qualified domain name (FQDN).
Parent topic: Configuring Oracle Key Vault with an Alternate Hostname
19.7.3 Choosing the Alternate Hostname to Use in Endpoint Configuration
After successfully configuring Oracle Key Vault with one or more alternate hostnames, you can choose one of these alternate hostnames as the identity that endpoints will use when connecting to the Oracle Key Vault server/multi-master cluster node.
Parent topic: Configuring Oracle Key Vault with an Alternate Hostname
19.7.4 Guidelines for Configuring Alternate Hostnames
Review these guidelines before configuring an alternate hostname for endpoints to communicate with Oracle Key Vault.
- Configure the alternate hostname during initial setup of the Oracle Key Vault deployment, before registering endpoints.
- In a multi-master cluster environment, each node must be given its own (unique) alternate hostname. Configure the alternate hostname one node at a time, after all nodes have been added to the multi-master cluster.
- Alternate hostnames cannot be configured or used by endpoints in primary-standby deployments.
- Configuring an alternate hostname requires rotating the Oracle Key Vault server/node certificates. Follow the guidelines for rotating server/node certificates during the configuration.
- Up to two alternate hostnames can be configured for a given Oracle Key Vault server/node. However, only one of these values may be chosen as the hostname for endpoints to use when reaching out to the server/node.
- Before updating the Hostname to use in Endpoint Configuration, verify network connectivity using the desired alternate hostname.