Please Note:

Cryptographic Operation Examples

This section shows the examples of the CipherTrust cryptographic operation along with the examples related to encryption, decryption, encrypting and decrypting large files, sign, verify, and random.

A user or group may perform each of the following cryptographic operations using a specific key if he or she has permissions to perform such as configured for each individual key from inside the CT-VL Administration UI.

The allowed cryptographic operations available are:

Encrypt - Encryption using a key.
Decrypt - Decryption using a key.
Sign - Sign with a given key.
Verify - Verify a signature with a given key.

Cryptographic Headers

Cryptographic headers is a convenient feature that allows a ciphertext to be decrypted without knowledge of the specific key name and/or version that was used to encrypt it. When encrypting with headers enabled, the ciphertext includes bytes containing key information inserted before the encrypted data.

To enable cryptographic headers, the header attribute must appear in the POST body for sign, verify, encrypt, and decrypt calls.

Verify and decrypt also take an all header attribute value to let the service figure out the header version in a more transparent way for the caller.

CipherTrust Cryptographic Operation Examples

Simple SHA-256 Digest Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/digest' \
-d '{"alg": "S256", "payload": "Ef+4MkU6ukzQSMbHxH4rxoVF/xKHyg=="}' \
-H 'content-type: application/json'

Response

{
    "digest": "RfdwuYKwBn0l03ZMGB7r59S+P+T9/s8ufPJfcSQXNfE="
}

Encryption Examples

AES-256 CBC Encryption Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/encrypt' \
-d '{"plaintext": "JLns9BI4Pa7TTrCaeJIjQQ==", "alg": "A256CBC", "params": {"iv": "tler+lrCnchFRJDCFs1F/A=="},"kid": "mykey123"}' \
-H 'content-type: application/json'

Response

{
    "ciphertext": "SZASu6Ts+01IMtb14+djhg==",
    "params": {}
}

Simple AES-256 CTR Encryption with Headers Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/encrypt' \
-d '{"plaintext": "JLns9BI4Pa7TTrCaeJIjQQ==", "alg": "A256CTR", "params":{"iv": "tler+lrCnchFRJDCFs1F/A=="}, "kid": "myversionedkey", "headers"="hdr_v2.7"}' \
-H 'content-type: application/json'

Response

{
    "ciphertext": "UktNQzIxMAD/////AAAABXV1aWQAAAAAEDkKfAiGhjeLkp50NDgjPQT/////AAAAA2l2AAAAABBhYmMxMjNkZWZnaDY3ODkw/////wAAAAVjc3VtAAAAACAbtDVcSesXu7SYqoZxNR+hC6Cq8H3gE5xv5vvSzRhUrKcwnBu8",
    "params": {}
}

Decryption Examples

Simple AES-256 CBC Encryption Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/decrypt' \
-d '{"ciphertext": "wInPTVRugkxP0KBm46yCo8lpQMaDDRol5bEWt9Mz629MKh7IqB9roh36ZkyIumLi", "alg": "A256CBC", "params": {"iv": "ek5LmcwOJATvux5PoSaZ6w=="}, "kid": "fookey"}' \
-H 'content-type: application/json'

Response

{
    "plaintext": "4Oidw01cBKKcF1tK4ZBdZg7yDe9KbvBP1npfs382HT+yz0Fb3CeCh/eBIhH7a1rb",
    "params": {}
}

Simple AES-256 CTR Decryption with Headers Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/decrypt' \
-d '{"ciphertext": "UktNQzIxMAD/////AAAABXV1aWQAAAAAEDkKfAiGhjeLkp50NDgjPQT/////AAAAA2l2AAAAABBhYmMxMjNkZWZnaDY3ODkw/////wAAAAVjc3VtAAAAACAbtDVcSesXu7SYqoZxNR+hC6Cq8H3gE5xv5vvSzRhUrKcwnBu8", \
"alg": "A256CTR", "params":{"iv": "tler+lrCnchFRJDCFs1F/A=="}, "headers"="all"}' \
-H 'content-type: application/json'

Response

{
    "plaintext": "JLns9BI4Pa7TTrCaeJIjQQ==",
    "params": {}
}

Encrypting and Decrypting Large Files

To handle files that are larger than the payload limit of 5 MB, use the following script to automatically break down a large file into a chain of smaller files for encryption, and to join these files and decrypt them. For files less than the payload limits, refer to Cryptographic Operation Examples.

#!/bin/bash
URL=http://localhost:8000/crypto/v1
KEY=cc01
IV="MTAwMDIwMDAzMDAwNDAwMA=="
CHUNKSIZE=256
FILE="/etc/hosts"
ALG="A256CTR"
BASE=`basename $FILE`
OIV=$IV
if [ ! -e ./$BASE ]
then
cp $FILE .
fi
rm -f ${BASE}-* *-${BASE}-*
split -b $CHUNKSIZE ./$BASE ${BASE}-
NOMORE=0
echo "=========================== Encryption ==========================="
for i in ${BASE}-*
do
if [ $NOMORE -eq 1 ]
then
break
fi
PTEXT=`cat $i | base64 -w 0`
PAYLOAD=$(jq -n -r \
--arg kid $KEY \
--arg iv $IV \
--arg pt "$PTEXT" \
--arg alg $ALG \
'{ plaintext: $pt, alg: $alg, kid: $kid, params: {iv: $iv} }'
)
RESULT=`echo $PAYLOAD | curl -u username: password -Ss -X POST -k -d @- -H "Accept: application/json"
$URL/encrypt`
NEWIV=`echo $RESULT | jq -r '.params.iv'`
CTEXT=`echo $RESULT | jq -r '.ciphertext'`
if [ -z "$NEWIV" ] || [ "$NEWIV" == "null" ]
then
NOMORE=1
fi
IV=$NEWIV
echo -n $CTEXT | base64 -d -w0 > ${i}.enc
done
cat ${BASE}-*.enc > ./${BASE}.enc
split -b $CHUNKSIZE ./${BASE}.enc enc-${BASE}-
IV=$OIV
NOMORE=0
echo "=========================== Decryption ==========================="
for i in enc-${BASE}-*
do
if [ $NOMORE -eq 1 ]
then
break
fi
CTEXT=`cat $i | base64 -w0`
PAYLOAD=$(jq -n -r \
--arg kid $KEY \
--arg iv $IV \
--arg ct "$CTEXT" \
--arg alg $ALG \
'{ ciphertext: $ct, alg: $alg, kid: $kid, params: {iv: $iv} }'
)
RESULT=`echo $PAYLOAD | curl -u username: password  -Ss -X POST -k -d @- -H "Accept: application/json"
$URL/decrypt`
NEWIV=`echo $RESULT | jq -r '.params.iv'`
PTEXT=`echo $RESULT | jq -r '.plaintext'`
if [ -z "$NEWIV" ] || [ "$NEWIV" == "null" ]
then
NOMORE=1
fi
IV=$NEWIV
echo -n $PTEXT | base64 -d -w0 > ${i}.dec
done
cat enc-${BASE}-*.dec > ${BASE}.dec
diff ${BASE}.dec ${BASE}
echo diff status = $?

The large file is broken into chunks of size whose modulo 16 equals 0 (that is, into chunk sizes that are multiples of 16 bytes).

When submitting the chunks to the encryption endpoint, the response includes an IV that is used to encrypt the next chunk. If the payload length is not 16-byte aligned, the response does not return the next IV, assuming that chaining is complete.

For decryption, the same rules apply. The first call must use the same IV as the call used for encrypting. The ciphertext chunk size can be a different size from the original plaintext encryption request, as long as the chunks are 16-byte aligned.

For example a 1030 byte file can be encrypted in 8 chunks of 128 bytes each and a last one of 6 bytes. The same file once encrypted can be split in 3 chunks of 320 bytes and a last one of 70 bytes.

Sign

Simple HMAC-SHA256 Sign Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/sign' \
-d '{"alg": "HS256", "payload": "aGVsbG8gd29ybGQh", "kid": "mykey"}' \
-H 'content-type: application/json'

Response

{
    "signature": "13pCxjIXjY8MNhsx69szyUOVraQc6Tn0C0irqCutOLs="
}

Verify

Simple HMAC-SHA256 Sign Example

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/verify' \
-d '{"alg": "HS256", "signature": "13pCxjIXjY8MNhsx69szyUOVraQc6Tn0C0irqCutOLs=", "payload": "aGVsbG8gd29ybGQh", "kid": "mykey"}' \
-H 'content-type: application/json'

Response

{
    "valid": 1
}

Random

Simple Random Example

The following example shows a simple request to generate an 8-byte random number:

Request

curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/crypto/v1/random' \
-d '{"seed": "q8qqyw==", "size": 8}' \
-H 'content-type: application/json'

Response

{
    "random": "152LM5GzL8U="
}

Authorization Operations

Below table shows the possible authorization operations when a key is / was created or imported via the API. The owner is the user who creates the key.

Operation	Owner	Group	Other User	Other Group
Create	Yes, if owner has `create` permission Owner can specify on `create` the permissions allowed though the usage attribute If usage attribute is not supplied, then key will be created with all permissions	Yes, if owner has `create` permission granted through a group Owner can specify on `create` the permissions allowed though the usage attribute If usage attribute is not supplied, then key will be created with all permissions	N/A	N/A
Import	Yes, if owner has `import` permission Owner can specify on `import` the permissions allowed though the usage attribute If usage attribute is not supplied, then key will be imported with all permissions	Yes, if owner has `import` permission granted through a group Owner can specify on `import` the permissions allowed though the usage attribute If usage attribute is not supplied, then key will be imported with all permissions	N/A	N/A
Destroy	Yes, if owner gave permission on `creation`	No	No	No
Export	Yes, if owner gave permission on `import` or `create`	No	No	No
Find	Yes, if owner gave permission on `import` or `create`	No	No	No
Modify	Yes, if owner gave permission on `import` or `create`	No	No	No
Encrypt	Yes, if owner gave permission on `import` or `create`	No	No	No
Decrypt	Yes, if owner gave permission on `import` or `create`	No	No	No
Sign	Yes, if owner gave permission on `import` or `create`	No	No	No
Verify	Yes, if owner gave permission on `import` or `create`	No	No	No

Cryptographic Operation Examples

Cryptographic Headers

CipherTrust Cryptographic Operation Examples

Simple SHA-256 Digest Example

Request

Response

Encryption Examples

AES-256 CBC Encryption Example

Request

Response

Simple AES-256 CTR Encryption with Headers Example

Request

Response

Decryption Examples

Simple AES-256 CBC Encryption Example

Request

Response

Simple AES-256 CTR Decryption with Headers Example

Request

Response

Encrypting and Decrypting Large Files

Sign

Simple HMAC-SHA256 Sign Example

Request

Response

Verify

Simple HMAC-SHA256 Sign Example

Request

Response

Random

Simple Random Example

Request

Response

Authorization Operations

On this page

Suggest A Change