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 Data Security Platform Service. This provides greater control over encryption keys that protect your data in the Oracle cloud.

CipherTrust Cloud Key Manager (CCKM) on the CipherTrust Data Security Platform Service uses external keys for performing cryptographic (encrypt/decrypt) operations on demand, while preserving end-user control to manage external keys. The lifecycle of external keys on the CipherTrust Data Security Platform Service is managed by CCKM only. The OCI KMS does not have any control over these keys.

The CipherTrust Data Security Platform Service exposes a network endpoint. This allows the OCI KMS to forward any cryptographic requests to the CipherTrust Data Security Platform Service for processing.

Prerequisites

Before integrating the CipherTrust Data Security Platform Service as an External Key Manager (EKM), make sure the following.

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

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

3. Connectivity to CipherTrust Data Security Platform Service requires FQDN configuration.

   FQDN configuration requires a private API Gateway in a private subnet. The private subnet must have a NAT Gateway to route requests from the API Gateway to EKM. This requires creation of some objects on OCI.

   1. Create an OCI API gateway with FQDN.

      • In the Certificate section, provide a custom TLS certificate from your chosen Certificate Authority (CA), for example by using openssl.

      • You do not need to provide Certificate authorities under ShowAdvancedOptions for CipherTrust Data Security Platform Service. The CipherTrust Data Security Platform Service server certificate is issued by a CA known to OCI.

   2. Deploy the API gateway with FQDN.

4. A private endpoint is created. Refer to Creating a Private Endpoint for details.

   Provide the IP Address of the OCI API Gateway in the External Key Management Private IP address field.

After ensuring the prerequisites, perform the steps described in the subsequent sections.

Add OCI Tenancy on CipherTrust Data Security Platform Service

On the CipherTrust Data Security Platform Service, add an OCI tenancy. You can add OCI tenancies manually (without Oracle connection) or using an Oracle connection configured on the CipherTrust Data Security Platform Service. Refer to Adding Oracle Tenancies for details.

After adding the OCI tenancy, register the CipherTrust Data Security Platform Service with OCI Identity Domain as a confidential application.

Register CipherTrust Data Security Platform Service with OCI Identity Domain

Register the CipherTrust Data Security Platform Service (an External Key Manager) as a confidential resource application with Oracle Identity Domain and enable the client credentials grant, if the Identity Domain is protected.

While registering the CipherTrust Data Security Platform Service, add the oci_ekms scope. Refer to Creating Confidential Resource App for details.

After registration, the CipherTrust Data Security Platform Service 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 Data Security Platform Service

Register an identity provider on the CipherTrust Data Security Platform Service. Specify the JWKS URI or OpenID configuration URL (the Identity Domain URL and the suffix string, /.well-known/openid-configuration) and CipherTrust Data Security Platform Service application’s client credentials (if the OCI Identity Domain is protected). These details are generated during the step Register CipherTrust Data Security Platform Service with OCI Identity Domain.

To register the identity provider with the CipherTrust Data Security Platform Service:

1. Log on to the CipherTrust Data Security Platform Service GUI.

2. Add the identity provider. Refer to Creating Identity Providers for details.

CipherTrust Data Security Platform Service 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 Data Security Platform Service.

Register OCI KMS Application

Register the OCI KMS application as a confidential client application and enable the client credentials grant. Next, bind the CipherTrust Data Security Platform Service, which you registered as a confidential resource application. This binding is required to associate the OCI KMS client to the CCKM authorized resource (CipherTrust Data Security Platform Service).

Refer to the Oracle documentation for details.

On OCI:

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

2. Bind the OCI KMS Client application with the CipherTrust Data Security Platform Service application that you registered as a confidential resource 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 Data Security Platform Service.

Creating External Vaults

To create an external vault:

1. On the CipherTrust Data Security Platform Service, 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 Data Security Platform Service.

   During this step, an external vault is created locally on the CipherTrust Data Security Platform Service 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.

The vault created under EKM on the OCI KMS is mapped with the external vault created on the CipherTrust Data Security Platform Service.

Creating External Keys

To create an external key:

1. On the CipherTrust Data Security Platform Service, create a key in the external vault created on the CipherTrust Data Security Platform Service (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 Data Security Platform Service.

Rotating External Keys

To rotate an external key:

1. On the CipherTrust Data Security Platform Service, create a new key version in the external vault created on the CipherTrust Data Security Platform Service (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 Data Security Platform Service.

What Next?

After completing the prerequisites, you can manage external vaults and keys on the CipherTrust Data Security Platform Service.

Refer to the following sections:

• Issuers APIs

• External Vaults APIs

• External Keys APIs

• OCI Invoked APIs