CCKM API

Note

APIs might change from version to version. Refer to the API playground URL of your CipherTrust Manager for updated APIs.

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, Luna HSM partitions, DSM domains, Google Cloud key rings, Salesforce organizations, SAP Data Custodian groups, Oracle Cloud Infrastructure (OCI) vaults, OCI External Key Management (EKM) (or external) vaults, CipherTrust (external) domains, SAP EKM to CCKM

• Manage AWS, Azure, Luna HSM, DSM, Google CMEK, Google Cloud EKM keys, Salesforce tenant secrets, SAP, OCI keys, OCI EKM keys, CipherTrust (external) keys, Microsoft Double Key Encryption (DKE) endpoints, SAP EKM keys on CCKM

• Manage AWS custom key stores on CCKM

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

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

It is assumed, for this document, that you have already configured the CipherTrust Manager appliance. Refer to the CipherTrust Manager Deployment Guide for instructions.

The next step is to activate and install the CCKM license. Refer to Licensing for details.

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

   • An external CipherTrust Manager domain

   • A Luna HSM partition

   • A DSM domain

   • 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 CipherTrust Manager IP address or domain name, followed by /api/. For example, if the CipherTrust Manager is configured with www.mycompany.com as the domain name, the base URL would be https://www.mycompany.com/api/.

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 is with a username and password. This authenticates a local user to the root domain. There can be additional login options to authenticate to another domain, authenticate with a certificate, authenticate using LDAP, or authenticate using OIDC. These options require additional user management configuration from a user in the User Admins group.

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 and password for a given domain, outside of the embedded API guide. This is useful if you have created a custom REST API client.

To copy and paste the following example commands, set an environment variable to point to your CipherTrust Manager instance:

$ export KSCTL_URL=https://{addr}               # sh/bash
$ set -x KSCTL_URL=https://{addr}               # fish

For example, this command will use the root admin's credentials to create an API token:

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

Note

By default, this command creates a token for the root domain. You can specify a child domain to log in to with "{\"name\":\"domain_user\",\"password\":\"domain_user_password\", \"domain\":\"domain_name\"}"

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.