Key Management Examples
This section shows the examples of the CipherTrust key management as listed below:
Key States
Symmetric and asymmetric keys support the following states:
Preactive - When a key was created to have a preactive state.
Active - Default when a key is created.
Suspended - A key has been suspended.
Compromised - Key is compromised.
Deactivated - Key is deactivated.
Destroyed - Key is destroyed.
Note
To set a key to the suspended, compromised, or deactivated state, call the modify endpoint (PATCH).
A key can be set to the active state again only if it is in the suspended state.
Creating and Importing Keys
This category covers both key import and key creation. A user or group that has import, create, or both permissions is allowed to add keys to CT-VL.
The difference between import from create is in the ability to add a wrapped key representing the key itself to the key creation request. This ability to create and import keys is set for each user through the CT-VL Administration UI.
Note
If a user or group has create and/or import permissions, invoking the corresponding API endpoint will create a key with all the permissions for CipherTrust key management and cryptographic operations.
Any other user needing to perform operations on such keys, can only be added through the CT-VL Administration UI.
If the user does not have permission to create or import, the corresponding creation endpoint will return an error.
Managing Keys
A user or group may perform each of the following key management operations if he or she has permissions to perform such. This can be configured for each individual key from inside the CT-VL Administration UI.
The allowed key management operations are:
Destroy - Destroy a key.
Modify - Modify a key’s attributes.
Find - Look up or retrieve a specific key.
Export - Export a specific key. This only applies to symmetric keys.
Valid Key Operations
Below table lists the valid key operations from the API. It does not include permissions related to authorization. See the Authorization Operations section for more details.
| Operation | Symmetric Key | Versioned Symmetric Key | Asymmetric Key | Opaque Object |
|---|---|---|---|---|
| Create | yes | yes | yes | yes |
| Import | yes | yes | no | yes |
| Destroy | Key delete custom attribute delete | Delete key by UUID or MUID only Delete key of version 0 deletes entire set Delete custom attribute | Key delete custom attribute delete | Key delete custom attribute delete |
| Modify | custom attributes add alias key states key migration to versioned key | custom attributes add alias key states key rotation lifespan interval | custom attributes | custom attributes add alias |
| Find | By label/name By UUID By MUID By alias | By label/name - last version By UUID By MUID By alias | public key only By label/name | By label/name By UUID By MUID By alias |
| Export | clear_key kid for plain bytes wrapping key with A256CBC or A256CBCPAD | clear_key kid for plain bytes wrapping key with A256CBC or A256CBCPAD | no | no |
| Encrypt | Standard encryption cryptographic headers | Standard encryption cryptographic headers | Standard encryption only | no |
| Decrypt | Standard decryption cryptographic headers | Standard decryption cryptographic headers | Standard decryption only | no |
| Sign | HMAC signing cryptographic headers | HMAC signing cryptographic headers | RSA signing only | HMAC signing cryptographic headers |
| Verify | HMAC verifying cryptographic headers | HMAC verifying cryptographic headers | RSA verifying only | HMAC verifying cryptographic headers |
Key Creation
Key creation allows to create a key whose contents (key material or bytes) is generated by the CM.
Note
You cannot create a key via the REST API and make it a seed key in one step.
You must create the key and add it via the CT-VL GUI in separate steps.
You cannot just pass in
seedkeyas a keyword to the create key REST API. If you do, the key is created, but it is not a seed key.
This example shows how to create an AES 128-bit key named foo123key:
Request
curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/km/v1/keys' \
-d '{"size": 128, "name": "foo123key", "kty": "oct"}' \
-H 'content-type: application/json'
Response
{
"attributes": {
"usage": [
"encrypt",
"decrypt",
"sign",
"verify",
"destroy",
"modify",
"find",
"export"
],
"size": 16
},
"metadata": {
"key_management": {
"uuid": "9f3c2775-405b-33e8-91af-904faa0e551f",
"caching_duration": 44640,
"state": "active",
"lifespan_unit": "days",
"muid": "9f3c2775-405b-33e8-91af-904faa0e551f39b6aee0-6821-39f9-a186-9a9904abff32",
"caching_enabled": true,
"name": "foo123key"
}
},
"kid": "tesrn:vts::label:foo123key"
}
Key Import
Key import is basically the same as a key create, however the request contains information on the wrapped key and the wrapping key.
This request imports an AES 128-bit key named foo1234key with key bytes equal to: “HelloWorldAlways”.
Request
curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/km/v1/keys' \
-d '{"size": 128, "name": "foo123key", "kty": "oct", "wrappedkey": "SGVsbG9Xb3JsZEFsd2F5cw=="}' \
-H 'content-type: application/json'
Response
{
"attributes": {
"usage":[
"encrypt",
"decrypt",
"sign",
"verify"
],
"size":16
},
"metadata": {
"key_management": {
"uuid": "9f3c2775-405b-33e8-91af-904faa0e551f",
"caching_duration":44640,
"state":"active",
"lifespan_unit" :"days",
"muid":"9f3c2775-405b-33e8-91af-904faa0e551f39b6aee0-6821-39f9-a186-9a9904abff32",
"caching_enabled": true,
"name": "foo123key"
}
},
"kid":"tesrn:cts::label:foo1234key"
}
Key Delete
This example deletes a key named foo123key.
Note
Upon success, the HTTP status code must be 200.
Request
curl -k -u vtsuser -X DELETE 'https://127.0.0.1/vts/km/v1/keys/foo123key'
Response
200 OK
Key Update
Request
curl -k -u vtsuser -X PATCH 'https://127.0.0.1/vts/km/v1/keys/fookey' \
-d '{"state": "suspended"}' \
-H 'content-type: application/json'
Response
{
"attributes": {
"usage": [
"encrypt",
"decrypt",
"sign",
"verify",
"destroy",
"find"
],
"size": 16
},
"metadata": {
"key_management": {
"uuid": "bfd2a7b7-20db-31d7-b22f-01e625a54961",
"caching_duration": 44640,
"state": "suspended",
"versioning_enabled": 1,
"lifespan_unit": "days",
"muid": "bfd2a7b7-20db-31d7-b22f-01e625a549618b0ce745-fcb2-3718-97b3-d4a0b415ac5d",
"caching_enabled":1,
"name":"fookey"
}
},
"kid":"tesrn:cts::label:fookey"
}
Key Retrieval
Request
curl -k -u vtsuser -X GET 'https://127.0.0.1/vts/km/v1/keys/fookey'
Response
{
"attributes": {
"usage": [
"encrypt",
"decrypt",
"sign",
"verify",
"destroy",
"find"
],
"size": 16
},
"metadata": {
"key_management": {
"uuid": "bfd2a7b7-20db-31d7-b22f-01e625a54961",
"caching_duration": 44640,
"state": "suspended",
"versioning_enabled": 1,
"lifespan_unit": "days",
"muid": "bfd2a7b7-20db-31d7-b22f-01e625a549618b0ce745-fcb2-3718-97b3-d4a0b415ac5d",
"caching_enabled":1,
"name":"fookey"
}
},
"kid":"tesrn:cts::label:fookey"
}
Key Export
Request
curl -k -u vtsuser -X POST 'https://127.0.0.1/vts/km/v1/keys/export/fookey' \
-d '{"alg": "A256CBCPAD", "params": {"iv":"RERERERERERERERERERERA=="}, "kid": "tesrn:cts::label:foo123key"}' \
-H 'content-type: application/json'
Response
{
"exported_key": {
"attributes": {
"usage": [
"encrypt",
"decrypt",
"sign",
"verify",
"destroy",
"find"
],
"size": 16
},
"metadata": {
"key_management": {
"uuid": "a0415d15-74d5-3d90-b755-53d88b6b2c31",
"caching_duration": 44640,
"state": "active",
"lifespan_unit": "days",
"muid": "a0415d15-74d5-3d90-b755-53d88b6b2c315276f6c8-ecde-30aa-87b9-17d63a432d94",
"caching_enabled": 1,
"name":"fookey"
}
},
"kid": "tesrn:cts::label:fookey"
},
"wrappedkey":"pXSyQ1eGDEucWA1Mvmwix5tTGezs73Hr92hecKtn5Bc="
}
Wrapping Keys
When importing or exporting a key, it is recommended to use a wrapping key in order not to compromise the key itself.
Note
In the current version of the CT-VL Key Management module, a wrapping key must be an AES 256-bit key, and only the CBC or CBCPAD ciphers may be used.
The ideal method for wrapping a key on both import and export is to use asymmetric keys.
Importing and exporting key requires that the user has a wrapping key, and such key is available on both client and the CT-VL.
Importing with Wrapping Key
When importing with a wrapping key, the following steps need to be taken:
Create a 256-bit AES key that is known to the caller and the CT-VL. This is the wrapping key.
Encrypt the key bytes with the wrapping key using an AES-CBC or AES-CBCPAD cipher. This is the wrapped key.
Call the create endpoint and supply the base64-encoded wrapped key and the wrapping key ID.
Exporting with Wrapping Key
When exporting with a wrapping key, the following steps need to be taken:
Create a 256-bit AES key that is known to the caller and the CT-VL. This is the wrapping key.
Call the export endpoint, supplying a wrapping key ID. This will return a wrapped key.
Decrypt the base64-encoded wrapped key using the wrapping key on the client side.
Importing and Exporting Using Clear Bytes
The API offers the ability to perform import and export functions using raw key bytes, however such method is not recommended.
To import a key using clear bytes, omit the wrapping key ID or give the clear_key label. For exporting, give the clear_key label as the wrapping key ID. In both cases, the alg and the iv attributes must be omitted.
