Uploading Keys to AWS KMS
Use the post /v1/cckm/aws/upload-key API to upload a key created on the CipherTrust Manager to the AWS KMS.
Syntax
curl -k '<IP>/api/v1/cckm/aws/upload-key' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "source_key_tier": "<source_key_tier>",\n "source_key_identifier": "<source_key_identifier>",\n "region": "<region>",\n "kms": "<kms_identifier>",\n "key_expiration": <boolean>,\n "aws_param": {<aws parameters>}' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| kms | string | Name or ID of the KMS where the key will be uploaded. |
| region | string | Name of the region. |
| source_key_tier | string | Tier of the source. Possible options are: • local for CipherTrust Manager (default)• dsm for Data Security Manager• hsm-luna for Luna HSM (FM-enabled Luna HSM is not supported as a key source)• external-cm for external CipherTrust Manager |
| source_key_identifier | string | Name or ID of the key to be uploaded. • If source_key_tier is local, this is the ID of the CipherTrust Manager key to be uploaded.• If source_key_tier is dsm, this parameter is the ID of the DSM key to be uploaded (only AES keys are supported).• If source_key_tier is hsm-luna, this parameter is the ID of the Luna HSM key to be uploaded.• If source_key_tier is external-cm, this parameter is the ID of the external CipherTrust Manager key to be uploaded. |
| aws_param | JSON | AWS key parameters such as alias, description, and usage. Refer to AWS Key Parameters for details. |
| external_accounts | array of strings | AWS accounts that can use this key. |
| key_admins | array of strings | IAM users who can administer this key using the KMS API. |
| key_admins_roles | array of strings | IAM roles that can administer this key using the KMS API. |
| key_users | array of strings | IAM users who can use this key in cryptographic operations. |
| key_users_roles | array of strings | IAM roles that can use the CMK in cryptographic operations. |
| policytemplate | string | ID of the policy template to apply. Note: When a policy template is applied to an AWS key, CCKM adds the template tag ( cckm_policy_template_id) to the key. Do not modify or delete this tag on the AWS cloud. |
| key_expiration (optional) | boolean | Whether to enable key expiration. |
Note
Specify Policy, policytemplate, or one of key_admins, key_admins_roles, key_users, key_users_roles, and external_accounts. They are mutually exclusive. If no parameters are specified, the default policy is used.
AWS Key Parameters
| Parameter | Type | Description |
|---|---|---|
| Alias | string | Alias of the key. |
| BypassPolicyLockoutSafetyCheck | boolean | Flag to bypass the key policy lockout safety check. |
| CustomerMasterKeySpec | string | Type of the key. Whether the KMS key contains a symmetric key or an asymmetric key pair. Refer to Supported Key Types. Depending on the selected key type, you might need to specify KeyUsage. |
| KeyUsage | string | Intended use of the key. Specify the cryptographic operations to be performed by the key. Suported operations are: • ENCRYPT_DECRYPT • SIGN_VERIFY • GENERATE_VERIFY_MAC Refer to Key Usage for more information. |
| Description | string | Description of the key. |
| MultiRegion | boolean | Whether the key can be replicated in multiple AWS regions. The base key will be referred to as the multi-region primary key. Set to true to allow key replication in multiple regions. |
| Policy | string | Key policy to attach to the CMK. |
| Tags | array of JSONs | An optional parameter to add additional information to the key. The value must be specified as the key-value pair. CCKM allows the following characters in tag values: • Alphanumeric characters • Special characters ** _ . / = + - @ ** |
| ValidTo | string | Key expiration time, must be formatted as per RFC3339. |
Note
Specify Policy, policytemplate, or one of key_admins, key_users, and external_accounts. They are mutually exclusive. If no parameters are specified, the default policy is used.
Supported Key Types
Note
CipherTrust Manager as a local or external key source supports AES (SYMMETRIC_DEFAULT), RSA, EC, and HMAC keys.
Luna HSM supports only AES, RSA, and EC keys.
DSM as a key source supports only AES keys.
Expand to view supported key types
CipherTrust Manager (Local or External)
SYMMETRIC_DEFAULT (Default)
RSA_2048 (Asymmetric)
RSA_3072 (Asymmetric)
RSA_4096 (Asymmetric)
ECC_NIST_P256 (secp256r1) (Asymmetric)
ECC_NIST_P384 (secp384r1) (Asymmetric)
ECC_NIST_P521 (secp521r1) (Asymmetric)
ECC_SECG_P256K1 (secp256k1) (Asymmetric)
HMAC_224
HMAC_256
HMAC_384
HMAC_512
Luna HSM
SYMMETRIC_DEFAULT (Default)
RSA_2048 (Asymmetric)
RSA_3072 (Asymmetric)
RSA_4096 (Asymmetric)
ECC_NIST_P256 (secp256r1) (Asymmetric)
ECC_NIST_P384 (secp384r1) (Asymmetric)
ECC_NIST_P521 (secp521r1) (Asymmetric)
ECC_SECG_P256K1 (secp256k1) (Asymmetric)
Data Security Manager (DSM)
- SYMMETRIC_DEFAULT (Default)
Key Usage
For the SYMMETRIC_DEFAULT and HMAC key types, you don't need to specify the usage explicitly. The default usage for SYMMETRIC_DEFAULT is ENCRYPT_DECRYPT, and for HMAC, the default usage is GENERATE_VERIFY_MAC.
Asymmetric RSA keys support SIGN_VERIFY and ENCRYPT_DECRYPT key usages. You need to specify a usage explicitly.
For asymmetric ECC keys, you don't need to specify the usage explicitly. The default key usage for ECC keys is SIGN_VERIFY.
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/upload-key' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjZlZWE0NWJlLTc5NTMtNGUzZS1iNWJjLWZlZDEwMmZhNGNiYSIsImlhdCI6MTYwNDU1OTMxOSwiZXhwIjoxNjA0NTU5NjE5fQ.8BNfjt82PmwBoIzFsUk2eh4AvWwrjZxRiewK9Hyp67A' -H 'Content-Type: application/json' --data-binary $'{\n "source_key_identifier": "test-key",\n "region": "ap-south-1",\n "kms": "kms",\n "aws_param": {\n "Alias": "test-upload-key-1",\n "Tags": [\n {\n "TagKey": "key",\n "TagValue": "value"\n }\n ]\n }\n}' --compressed
Example Response
{
"id": "02c40491-f5bd-4204-93f3-5f9077740116",
"uri": "kylo:kylo:cckm:aws-key:02c40491-f5bd-4204-93f3-5f9077740116",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T07:00:53.99845058Z",
"updatedAt": "2020-11-05T07:00:54.504758124Z",
"kms_id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"kms": "kms",
"synced_at": "2020-11-05T07:00:53.990295894Z",
"rotation_status": "",
"local_key_id": "361d928ac7e340d093e7d231c80ca934acc62528601647ce86a219c9a82f4f93",
"local_key_name": "test-key",
"cloud_name": "aws",
"key_type": "symmetric",
"basic_view_enabled": false,
"region": "ap-south-1",
"gone": false,
"key_material_origin": "cckm",
"aws_param": {
"AWSAccountId": "123456789012",
"Arn": "arn:aws:kms:ap-south-1:123456789012:key/a3d6b6ab-e953-45f7-8275-e915277f5ee2",
"CustomerMasterKeySpec": "SYMMETRIC_DEFAULT",
"Enabled": true,
"EncryptionAlgorithms": [
"SYMMETRIC_DEFAULT"
],
"KeyID": "a3d6b6ab-e953-45f7-8275-e915277f5ee2",
"KeyManager": "CUSTOMER",
"KeyState": "Enabled",
"KeyUsage": "ENCRYPT_DECRYPT",
"Origin": "EXTERNAL",
"CreationDate": "2020-11-05T07:00:41Z",
"Policy": {
"Version": "2012-10-17",
"Id": "key-default-1",
"Statement": [
{
"Sid": "Enable IAM User Permissions",
"Effect": "Allow",
"Principal": {
"AWS": "arn:aws:iam::123456789012:root"
},
"Action": "kms:*",
"Resource": "*"
}
]
},
"Alias": [
"alias/test-upload-key-1"
],
"Tags": [
{
"TagKey": "key",
"TagValue": "value"
}
],
"KeyRotationEnabled": false,
"ExpirationModel": "KEY_MATERIAL_DOES_NOT_EXPIRE"
}
}
The sample output shows that a key (with alias test-upload-key-1) is uploaded to the AWS KMS. As the key is not created on the AWS KMS, its origin is EXTERNAL. A unique ID (02c40491-f5bd-4204-93f3-5f9077740116) for the uploaded key is returned.
To know more about response parameters, refer to Response Parameters of Key Life Cycle Management APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
