CT-VL Cryptographic REST APIs

The CipherTrust Vaultless Cryptographic API consists of the following POST calls:

• Encryption - encrypts data using a key and an algorithm. User passes a base64-encoded plaintext, and CT-VL returns a base64-encoded ciphertext.

• Decryption - decrypts data using a key and an algorithm. User passes a base64-encoded ciphertext, and CT-VL returns a base64-encoded plaintext.

• Sign - signs data using a key and an algorithm. User passes a base64-encoded data, and CT-VL returns a base64-encoded signature.

• Verify - verifies signature data using a key and an algorithm. User passes a base64-encoded signature data, and CT-VL returns a base64-encoded plaintext.

• Hash (Digest) - gets a hash (digest) of a data and an algorithm. User passes a base64-encoded plaintext, and CT-VL returns a hash (digest) of the plaintext.

• Random Number Generation - A POST call that generates a random number. User passes the size of the random number to be generated along with an optional seed, and CT-VL returns a random number.

Payload limits and Batch (vectorized) Size

The maximum input data size for CT-VL Cryptographic REST APIs is given below:

Successful responses

• All successful requests return a 200 HTTP status.

• All calls return a response body, except for destroy (DELETE) of a specific key which has an empty body.

• In a batch or vectorized call, where a series of requests are done simultaneously, the result is always 200. Each element of the vector contains the corresponding result for each request, whether successful or not.

Error responses and error codes

Error responses from the cryptographic and key management layer only return a JSON body with the following format.

Error Response Attributes

• error - indicates an error is returned. The error codes starts with:

  • 'TES_' - for service related error encountered

  • 'CKR_' - for PKCS11 related error encountered

• status - provides the HTTP status code associated with the error.

• message - provides a user-friendly message about the error.

• timestamp - provides the date-time instance when the error occurred.

Error HTTP Status Codes

• 400 - An HTTP 400 Bad Request status indicates that the user supplied a malformed or invalid request.

• 401 - An HTTP 401 Unauthorized status indicates that the user needs to log in or authenticate before the request can be handled.

• 403 - An HTTP 403 Forbidden status indicates that a logged-in user is not authorized to access or perform an operation on the given resource.

• 404 - An HTTP 404 Not Found status indicates that the URL or resource (TESRN) references do not exist.

• 500 - An HTTP 500 Internal Server Error indicates that an error has occurred on the server side.

Cryptographic Operation Examples

SHA-256 Digest

Example Request

POST /vts/crypto/v1/digest
{ 
    "payload": "FOH297ooiUBw+ijps0gyXGNzZ8HYAGviAbhWamT+RHg=",
    "alg": "S256"
}

Example Response

200 OK
{ 
    "digest": "IZ29Vb3NdpTBy243K+Ar3OS5QdfaaSClHqzcNLUkY7E="
}

AES-256 CBC Encryption

Example Request

POST /vts/crypto/v1/encrypt
{ 
    "plaintext": "sFj7tYoWsmuoI7qn4bNoXw==",
    "alg": "A256CBC", 
    "kid": "key1", 
    "params": { "iv": "7PoRiKBfb+0X0yZz053bLA=="
    }
}

Example Response

200 OK
{ 
    "ciphertext": "bgzZ05rdtjyTQzfguBtZYA==",
    "tag": ""
}

AES-256 CBC Decryption

Example Request

POST /vts/crypto/v1/decrypt
{ 
    "ciphertext": "2HtX5IgNC5ji2wfJ7SjlgA==",
    "alg": "A256CBC", 
    "kid": "key1", 
    "params": { 
        "iv": "qbRHop7SGyUbKcpq3K+nyA=="
        }
}

Example Response

200 OK
{ 
    "plaintext":"sLHDpH+ftb0dt3VHjzbk9Q=="
}

HMAC-SHA256 Sign

Example Request

POST /vts/crypto/v1/sign
{ 
    "alg": "HS256", 
    "kid": "key1", 
    "payload": "NzEwODUwNDQwMzc4MzA0MQ=="
}

Example Response

200 OK
{ 
    "signature":"rkp3wK9IhMQVhdeX2un72mcloK4UVx66C1iOuiWwqVY="
}

HMAC-SHA256 Verify

Example Request

POST /vts/crypto/v1/verify
{ 
    "alg": "HS256", 
    "kid": "key1", 
    "payload": "NzEwODUwNDQwMzc4MzA0MQ==", 
    "signature": "rkp3wK9IhMQVhdeX2un72mcloK4UVx66C1iOuiWwqVY="
}

Example Response

200 OK
{ 
    "valid": true
}

Random Generator

Example Request

POST /vts/crypto/v1/random
{ 
    "seed": "q8qqyw==", 
    "size": 16
}

Example Response

200 OK
{ 
    "random":"zax87FYFH5F39iBtBXJCbQ=="
}

AES-256 CTR Encryption

Example Request

POST /vts/crypto/v1/encrypt
{ 
    "plaintext": "sFj7tYoWsmuoI7qn4bNoXw==",
    "alg": "A256CTR", 
    "kid": "key1", 
    "params": { "iv": "7PoRiKBfb+0X0yZz053bLA=="
    }
}

Example Response

200 OK
{ 
    "ciphertext": "bgzZ05rdtjyTQzfguBtZYA==",
    "tag": ""
}

AES-256 CTR Decryption

Example Request

POST /vts/crypto/v1/decrypt
{ 
    "ciphertext": "2HtX5IgNC5ji2wfJ7SjlgA==",
    "alg": "A256CTR", 
    "kid": "key1", 
    "params": { 
        "iv": "qbRHop7SGyUbKcpq3K+nyA=="
        }
}

Example Response

200 OK
{ 
    "plaintext":"sLHDpH+ftb0dt3VHjzbk9Q=="
}

AES-256 GCM Encryption

Example Request

POST /vts/crypto/v1/encrypt
{
    "plaintext": "sFj7tYoWsmuoI7qn4bNoXw==",
    "alg": "A256GCM",
    "kid": "key1",
    "params": {
        "iv": "7PoRiKBfb+0X0yZz053bLA==",
        "taglen": 128
        }
}

Example Response

200 OK
{   
    "ciphertext": "bgzZ05rdtjyTQzfguBtZYA==",
    "tag": "1tJYNiiBTQM+3m5tNuNBEA=="
}

AES-256 GCM Decryption

Example Request

POST /vts/crypto/v1/decrypt
{
    "ciphertext": "2HtX5IgNC5ji2wfJ7SjlgA==",
    "alg": "A256GCM",
    "kid": "key1",
    "tag": "1tJYNiiBTQM+3m5tNuNBEA=="
    "params": {
        "iv": "qbRHop7SGyUbKcpq3K+nyA=="
        }
}

Example Response

200 OK
{
    "plaintext":"sLHDpH+ftb0dt3VHjzbk9Q=="
}