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 -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 -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 permissionOwner can specify on create the permissions allowed though the usage attributeIf usage attribute is not supplied, then key will be created with all permissions | Yes, if owner has create permission granted through a groupOwner can specify on create the permissions allowed though the usage attributeIf usage attribute is not supplied, then key will be created with all permissions | N/A | N/A |
| Import | Yes, if owner has import permissionOwner can specify on import the permissions allowed though the usage attributeIf usage attribute is not supplied, then key will be imported with all permissions | Yes, if owner has import permission granted through a groupOwner can specify on import the permissions allowed though the usage attributeIf 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 |
