Authenticating to the REST API

The REST API is hosted at this base URL: https://{addr}/api/v1

The specification is available here.

You can use the REST interface via curl, or from the API Guide embedded in the CipherTrust Data Security Platform Service UI.

To copy and paste the following example commands, set an environment variable to point to your CipherTrust Data Security Platform Service instance:

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

API token generation for User Credentials

You can generate an API token with a user's username and password.

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\"}"

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"

REST API Client Registration and API Token Generation for Client Credentials

You can register a REST API client to improve monitoring and traceability on the client's actions. Registered clients can exchange their client identities and client certificates for an API token for authentication through the REST API.

Registration is especially beneficial for automated clients which act without a person initiating operations.

If you register the REST client, its client identity is recorded in the DPoD audit query records. Theclient_id value is included in the audit query records whenever a registered or public client receives an authentication token.

Registering a REST API client

Registered clients require a client certificate which CipherTrust Data Security Platform Service recognizes. There are three options for creating a suitable certificate, in order of most to least secure:

• Provide a certificate signing request (CSR) issued by the client, to be signed by a CipherTrust Data Security Platform Service local certificate authority (CA).

• Sign a client-produced CSR with an external CA. The external CA must be added to CipherTrust Data Security Platform Service.

• If your client is not capable of generating a key pair or CSR, you can generate a CSR on CipherTrust Data Security Platform Service and use a local CA to sign it. You must then download the generated certificate and store it on the client.

The high level steps for registering are:

1. If possible, create a certificate signing request (CSRs) on the client.

2. Create a client profile on CipherTrust Data Security Platform Service.

   The client profile controls the CA and certificate settings used to create or renew client certificates for a particular client.

   Note

   If you need CipherTrust Data Security Platform Service to generate a CSR, we recommend providing CSR parameters when creating the client profile, and then providing the resulting client certificate in the registration request. If you provide CSR parameters at both stages, the client certificate returned in the registration response takes precedence over the certificate returned on client profile creation.

3. Create a registration token on CipherTrust Data Security Platform Service using the client profile. You must retain the registration token.

   The registration token is a randomly generated character string used to register a client.

4. With the REST client, make a POST /v1/client-management/clients to register the client.

   Provide the registration token and certificate-related parameters. The specification file and API Guide embedded in the CipherTrust Data Security Platform Service GUI has full schema descriptions for this endpoint. The example request demonstrates providing a CSR for CipherTrust Data Security Platform Service to sign.

   Example request

   curl -k "$KSCTL_URL/api/v1/client-management/clients/" -H 'Content-Type: application/json' -H 'accept: application/json' --data-binary $'{\n  "name": "REST_CLIENT",\n  "registration_token": "12345",\n  "csr": "-----BEGIN CERTIFICATE REQUEST-----\\nMIHNMHUCAQAwEzERMA8GA1UEAxMIVGVzdCBDU1IwWTATBgcqhkjOPQIBBggqhkjO\\nPQMBBwNCAATndOIgsTp7m4bOuixxuAt2XQ3oZqp8th/woAo51z7RiAAGdm7IfB1w\\n7uWr8o5PWKBatXIgvPp8hvRWHQPHCfcLoAAwCgYIKoZIzj0EAwIDSAAwRQIgVyvz\\nhFGCKV460fNJC0vC48gI268B68Xr6osFoy9Ouw8CIQCWN1LtcyxPIvul3XF1Pj7l\\navEeIqDBcfD6VHhbnpO2Ag==\\n-----END CERTIFICATE REQUEST-----",\n  "subject_dn_field_to_modify": "DNQ",\n  "do_not_modify_subject_dn": false\n}' --compressed
   

   Retain the ID value in the response. This represents the client identity required to obtain a token.

API Token Generation with Client Identity

To issue an API token for a client identity, you must specify grant_type:"client_credential" and client_id:<client_identity> in the data part of the request. The client identity is obtained during client registration.

In addition, the public certificate file path and private key file path are provided in the request to ensure that the client certificate is verified. These values correspond with the client certificate configuration that took place when creating a client profile and registering the client.

For example, this command generates an API token for the client 123456789, provided the presented identity and client certificate match the expected values in the client registration:

$ curl -k -X POST $KSCTL_URL/api/v1/auth/tokens/ -H "Content-Type: application/json" --cacert ".ssh/id_rsa.pub" --key ".ssh/id_rsa" -d "{\"grant_type\":\"client_credential\",\"client_id\":\"123456789\"}"

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

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"