Encrypting Data Using External Keys
Use the post /v1/cckm/oci/ekm/v1/vaults/{vaultId}/keys/{keyId}/encrypt API to encrypt the specified base64 encoded plaintext data using an external key in an external key vault.
To encrypt the data using a specific version of the external key, specify the version ID (keyVersionId) of the key as an input parameter. If not specified, the latest version of the key is used to encrypt the data.
The API returns a JSON blob that includes the base64-encoded ciphertext and metadata that is used for CCKM internal housekeeping. The metadata can include the source key ID, the key version information, and other details, as appropriate. The API response may also include a base64-encoded Initialization Vector (IV), authentication tag, cryptographic mode, and additional authenticated data (AAD).
The JSON blob returned by the API can be passed to the post /v1/cckm/oci/ekm/v1/vaults/{vaultId}/keys/{keyId}/decrypt API when decrypting the encrypted data. Refer to Decrypting Data Using External Keys for details.
The supported scope value is oci_hyok_encrypt.
When running the API,
{vaultId}is the resource ID of the external vault on the CipherTrust Manager.{keyId}is the resource ID of the external key on the CipherTrust Manager.
Header
| Parameter | Type | Description |
|---|---|---|
| opc-request-id | String | Unique identifier for the request. If provided, the returned request ID will include this value. Otherwise, a random request ID will be generated by the service. |
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| plaintext | string | A byte array data to be encrypted. JSON encodes byte arrays to base64 strings. Therefore, the string in the JSON object should be a valid base64 string. |
| iv | string | A byte array used with CBC and GCM cryptographic algorithm modes. The IV appears as a base64 encoded string in the JSON blob. It is recommended to omit this field to let the server generate and return a secure IV using its random number generator. Otherwise, follow the security guidelines in "NIST SP800-38A" and "NIST SP800-38D" publications to ensure your IV construction is secure. |
| mode | string | The cryptographic mode to use for symmetric key operations (that is, use the AES or TDES algorithm).• AES: The valid values are CBC, ECB, and GCM (default).• TDES: The valid value is CBC. |
| aad | string | A byte array data to be authenticated. It should be a valid base64 string. |
| tag_len | string | Length of the GCM tag in byte. The length can range from 4 to 16. The default length is 16. |
| pad | string | The cryptographic padding algorithm to use. The valid values depend on the algorithm used. • For AES and TDES, the valid values are none, PKCS5, and PKCS7 (default). The default is PKCS7.• For asymmetric algorithms, the valid values are PKCS1, OAEP, OAEP256, OAEP384, and OAEP512. The default is OAEP. |
| keyVersionId | string | Resource ID of the external key version on the CipherTrust Manager to be used for encryption. |
Example Request
post https://<Host IP Address>/api/v1/cckm/oci/ekm/v1/vaults/{vaultId}/keys/{keyId}/encrypt
<authorization token and other headers>
{
"plaintext": "YWJjZGVmZ2hpamtsbW5vcHFyc3R1dnd4eXo=",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"aad": "fIs5D+kRE8r",
"tagLen": 16,
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"pad": "PKCS7"
}
Example Response
{
"ciphertext": "RpeAO2op/+bQD3FioKbuVi54yysO79e0SjY=",
"keyVersionId": "1272f6a0-9377-4e9a-9158-460860716eaf",
"keyId": "650e330b-47b1-4d9f-ab72-866b4e10df39",
"iv": "EYMbIM/MOv5q7Km1",
"mode": "AES_GCM",
"tag": "dk958fIs5D+kRE8rKKqtgA==",
"pad": "PKCS7",
"aad": "fIs5D+kRE8r"
}
Response Codes
| Response Code | Description |
|---|---|
| 200 | Ok |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Not found |
| 403 | Forbidden |
| 500 | Internal server error |
Refer to HTTP status codes for details.
