OCI External Resources
Caution
This feature is a public preview for evaluation in non-production environments. A public preview introduces new, limited functionality for customer feedback as we work on the feature. Details and functionality are subject to change. This includes API endpoints, UI elements, and CLI commands. We cannot guarantee that data created as part of a public preview will be retained after the feature is finalized.
Oracle Cloud Infrastructure (OCI) Key Management Service (KMS) with external vault capability allows you to use a third-party on-premises key management system like CipherTrust Manager. This provides greater control over encryption keys that protect your data in the Oracle cloud.
CipherTrust Cloud Key Manager (CCKM) on the CipherTrust Manager uses external keys for performing cryptogrpahic (encrypt/decrypt) operations on demand, while preserving end-user control to manage external keys. The lifecycle of external keys on the CipherTrust Manager is managed by CCKM only. The OCI KMS does not have any control over these keys.
The CipherTrust Manager exposes a network endpoint. This allows the OCI KMS to forward any cryptogrpahic requests to the CipherTrust Manager for processing.
Prerequisites
Before integrating the CipherTrust Manager as an External Key Manager (EKM), make sure the following.
CipherTrust Manager
A CipherTrust Manager is deployed. Refer to Getting Started for details.
The NTP server is added. Refer to Add an NTP Server for details.
The web interface must have a TLS certificate signed by an external or local Certificate Authority (CA). The CA bundle should be provided while creating a private endpoint on OCI.
The Subject Alternative Name (SAN) in the web interface certificate must have specific IP Addresses.
A good default value for the SAN is the IP address of the CipherTrust Manager.
If you are using a load balancer, and it is set to do SSL passthrough, include the IP address of the load balancer in the SAN.
Refer to SSL/TLS server certificate (NAE, KMIP, and WEB) for details.
Note
OCI does not provide any option to update the IP address or the CA bundle in private endpoints. If you change the CA of the web interface certificate or the IP address of the CipherTrust Manager or Load Balancer, the network connectivity is disrupted. As a result, OCI faces network connectivity issues and all operations with the CipherTrust Manager stop working. In this case, you need to reconfigure the complete setup on OCI.
It is recommended to use the IAM Domain version of Oracle Identity Cloud Service (IDCS) for managing OCI vaults under EKM and keys (OCI HYOK). To use OCI HYOK with the tenancy that doesn't support the IAM Domain version, please contact Thales Customer Support.
Oracle Cloud Infrastructure (OCI)
A Virtual Cloud Network (VCN) is created in OCI Networking. Refer to the Creating a Virtual Cloud Network for details.
(Optional, recommended) FastConnect (Co-lo) is created in OCI Networking. This is required to have direct connectivity between the OCI VCN and the CipherTrust Manager on premises. Refer to the FastConnect documentation for details.
Policies are created in OCI Identity.
A policy is a document that specifies who can access which OCI resources that your company has, and how. A policy simply allows a group to work in certain ways with specific types of resources in a particular compartment.
Refer to Getting Started with Policies for details.
A private endpoint is created. Refer to Creating a Private Endpoint for details.
After ensuring the prerequisites, perfom the steps described in the subsequent sections.
Note
Currently, only commercial OCI regions are supported.
Add OCI Tenancy on CipherTrust Manager
On the CipherTrust Manager, add an OCI tenancy. You can add OCI tenancies manually (without Oracle connection) or using an Oracle connection configured on the CipherTrust Manager. Refer to Adding Oracle Tenancies for details.
After adding the OCI tenancy, register the CipherTrust Manager with OCI Identity Domain as a confidential application.
Register CipherTrust Manager with OCI Identity Domain
Register the CipherTrust Manager (an External Key Manager) as a confidential application with Oracle Identity Domain and enable the client credentials grant, if the Identity Domain is protected.
While registering the CipherTrust Manager, add the following scopes:
oci_hyok_getVaultMetadata
oci_hyok_getKeyMetadata
oci_hyok_getKeyVersionMetadata
oci_hyok_generateRandomBytes
oci_hyok_encrypt
oci_hyok_decrypt
Note
Oracle has upgraded their KMS service to support single scope changes for confidential resource application in Identity. You might be receiving 5xx errors from KMS service while testing encrypt/decrypt operations. This could happen due to deprecation of multi-scopes support for the External Key Manager feature.
To manage OCI EKMS resources using CCKM, it is recommended to upgrade CipherTrust Manager to 2.14 or a higher version.
Refer to Add a Confidential Application for details.
After registration, the CipherTrust Manager application's client credentials are generated if the Identity Domain is protected. Note down the credentials and the Identity Domain URL. These will be required for registering the JWT issuer (identity provider).
Register Identity Provider with CipherTrust Manager
Register an identity provider on the CipherTrust Manager. Specify the JWKS URI or OpenID configuration URL (the Identity Domain URL and the suffix string, /.well-known/openid-configuration) and CipherTrust Manager application’s client credentials (if the OCI Identity Domain is protected). These details are generated during the step Register CipherTrust Manager with OCI Identity Domain.
To register the identity provider with the CipherTrust Manager:
Log on to the CipherTrust Manager GUI.
Add the identity provider. Refer to Creating Identity Providers for details.
CipherTrust Manager verifies the provided JWKS URI and credentials from the OCI Identity Domain and saves the credentials securely on successful verification.
A JWT issuer ID is generated. This ID is required when creating an external vault on the CipherTrust Manager.
Register OCI KMS Application
Register the OCI KMS application as a confidential client application and enable the client credentials grant. Next, bind the CipherTrust Manager, which you registered as a confidential application. This binding is required to associate the OCI KMS client to the CCKM authorized resource (CipherTrust Manager).
Refer to the Oracle documentation for details.
On OCI:
Register the OCI KMS Client application as a confidential client application.
Bind with the CipherTrust Manager application that you registered as a confidential application.
After the KMS client application registration and binding, a KMS client ID is generated. This ID is required for creating an external vault on the CipherTrust Manager.
Creating External Vaults
To create an external vault:
On the CipherTrust Manager, create an external vault using the KMS client ID created in Register OCI KMS Client Application and the JWT issuer ID generated in Register Identity Provider with CipherTrust Manager.
During this step, an external vault is created locally on the CipherTrust Manager and an external vault endpoint URI is generated. This URI can be found in the details of the external vault resource.
Refer to Adding External Vaults for details.
On OCI, create a vault under EKM using the external vault endpoint URI generated in the previous step. Refer to the External Key Management Service documentation for details.
Note
If the CipherTrust Manager's web interface is configured on a port other than 443, the port number should be added to the external vault endpoint URI while creating a vault under EKM on OCI.
The vault created under EKM on the OCI KMS is mapped with the external vault created on the CipherTrust Manager.
Creating External Keys
To create an external key:
On the CipherTrust Manager, create a key in the external vault created on the CipherTrust Manager (refer to the previous step). You can select an existing source key or create a new key.
An external key ID is generated. This external key ID can be found in the details of the external key resource.
Refer to Adding External Keys for details.
On OCI, create an external key reference using the external key ID generated in the previous step. Refer to the External Key Management Service documentation for details.
The external key reference created on the OCI KMS is mapped with the external key created on the CipherTrust Manager.
Rotating External Keys
To rotate an external key:
On the CipherTrust Manager, create a new key version in the external vault created on the CipherTrust Manager (refer to the previous step). You can select an existing source key or create a new key.
A version ID is generated. This version ID can be found in the details of the external key resource.
Refer to Adding a Key Version for details.
On OCI, rotate an external key reference using the version ID generated in the previous step. Refer to the External Key Management Service documentation for details.
The external key reference created on the OCI KMS is mapped with the version ID created on the CipherTrust Manager.
What Next?
After completing the prerequisites, you can manage external vaults and keys on the CipherTrust Manager.
