CCKM API

CCKM Resources and Use Cases

Refer to the CCKM Administration Overview for more details on the CCKM prerequisites, use cases, and resources.

This document explains how to:

• Add AWS KMS accounts, Azure vaults, Google Cloud key rings, Salesforce organizations, SAP Data Custodian groups, and Oracle Cloud Infrastructure (OCI) vaults to CCKM

• Manage AWS, Azure, Google CMEK, Google Cloud External Key Manager (EKM) keys, Salesforce tenant secrets, SAP, and OCI keys on CCKM

• Manage AWS custom key stores on CCKM

• Schedule key rotation for AWS, Azure, Google Cloud, Salesforce, SAP, and OCI keys

• Schedule key refresh for AWS, Azure, Google Cloud, Salesforce, SAP, and OCI keys

Workflow

This section describes the high level steps to manage keys using CCKM:

1. Add a connection between the CipherTrust Manager and the desired cloud or key source. This is needed to grant CCKM the access to any of the cloud service or key source users with valid user credentials.

2. Test the connection. The connection must be in the ready state.

3. Add the KMS container that contains the keys to be managed. A KMS container can be:

   • An AWS account

   • An Azure vault

   • A Google Cloud key ring

   • A Salesforce organization

   • A SAP group

   • An OCI vault

   When adding a KMS container, you need to select the corresponding connection.

4. Refresh the KMS container to download its keys to CCKM. Refreshing a KMS container might take significant amount of time depending on the number of keys stored in it.

   CCKM provides options to refresh keys of an individual or all KMS containers of a cloud service or key source.

   After a KMS container is refreshed successfully, the downloaded keys can be managed on CCKM itself.

5. Manage keys. With CCKM, you can perform supported key operations such as adding, editing, and rotating keys.

CCKM also provides options to schedule key operations and generate reports for the supported clouds. Refer to relevant sections in the CCKM Administration and CCKM API documentation for more details about the steps listed above and other CCKM features.

Base URL

The base URL for all endpoints is the assigned hostname for the service, followed by /api. The hostname depends on your region.

In this API Reference, request syntaxes show the base URL as <IP>/api/ and example requests show the base URL as https://127.0.0.1/api/ for demonstration.

Authenticating to the Embedded API Guide

The embedded API Guide shares authentication with the CipherTrust Web UI. To authenticate to both the API Guide and the CipherTrust Web UI, visit https://<ciphertrust_manager_IP_or_hostname> in a web browser. Alternatively, click the Log In link in the top right corner of the API Guide when you are unauthenticated.

The simplest login, applicable to a user created within the CDSPaaS service, is providing a username and password. You can also create and login Data Protection on Demand single-sign on users with DPoD credentials.

After login, the API Guide is accessible through the API button in the upper right corner.

There, you can make API calls in the established authentication context. You are logged out after 10 minutes of inactivity with the API Guide open. If you close the browser window, you are logged out after 30 minutes of your last login.

Manual API Token Generation for User Credentials

You can generate an API token with a user's username, password, and tenant, outside of the embedded API guide. This is useful if you have created a custom REST API client.

For example, this command uses the user admin's credentials to create an API token for the my_tenant CSDPaaS tenant:

$ curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
     -H "Content-Type: application/json" \
     -d "{\"name\":\"admin\",\"password\":\"admin\", \"auth_domain\":\"my_tenant\"}"

The response:

{
  "jwt":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4",
  "duration":300
}

Copy the value of the jwt property into another environment variable:

(sh)  $ export KSCTL_JWT=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4
(fish)$ set -x KSCTL_JWT eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJkMzEzYzcwZS01NmYyLTQ5MTUtOGJkNy01ZmMyYmUyNzk2YzEiLCJzdWIiOiJsb2NhbHxiM2ZjOGZlNy1hN2ZlLTQ1YzEtOWU1OS0zYmUxNTRkMTZjYmQiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsImN1c3QiOnsiZ3JvdXBzIjpbImFkbWluIl19LCJpYXQiOjE0ODExMjQxMzcsImV4cCI6MTQ4MTEyNDQzN30.Z9GU0YyOImHMdPmbZx66vL0NLQfeLvNGkyGkZpVbfx4

Using the jq tool, we can fetch, extract, and export the token in a single shell command:

(sh)  $ export KSCTL_JWT=$(curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                    -H "Content-Type: application/json" \
                                    -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')
(fish)$ set -x KSCTL_JWT (curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ \
                                   -H "Content-Type: application/json" \
                                   -d "{\"name\":\"admin\",\"password\":\"admin\"}" | jq -r '.jwt')

We can use that API token to make other calls:

$ curl -k "$KSCTL_URL/api/v1/vault/keys2?limit=20" \
     -H "Authorization: Bearer $KSCTL_JWT"

API Response Codes

RESTful APIs included in CCKM are based on HTTP protocol. They return standard HTTP response status codes. The response codes returned by APIs included in CCKM are:

Refer to HTTP status codes for details.