OCI External APIs

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.

Oracle Cloud Infrastructure (OCI)

1. A Virtual Cloud Network (VCN) is created in OCI Networking. Refer to the Creating a Virtual Cloud Network for details.

2. (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.

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

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

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

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:

1. Log on to the CipherTrust Manager GUI.

2. 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:

1. Register the OCI KMS Client application as a confidential client application.

2. 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:

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

2. 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:

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

2. 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:

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

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

Refer to the following sections:

• Issuers APIs

• External Vaults APIs

• External Keys APIs

• OCI Invoked APIs