AWS KMS Management APIs
This section describes how CCKM manages the AWS resources such as KMS and keys.
Prerequisites
An AWS connection must already exist on the CipherTrust Manager. Refer to the CipherTrust Manager Administrator Guide for details on adding an AWS connection to the CipherTrust Manager.
Appropriate permissions to manage KMS must be defined.
Permissions to list regions
The IAM permission ec2:DescribeRegions is needed to list the AWS regions.
For example:
{ "Version": "2012-10-17", "Statement": [ { "Sid": "VisualEditor0", "Effect": "Allow", "Action": "ec2:DescribeRegions", "Resource": "*" } ] }Permissions to manage AWS resources
The following IAM permissions are needed to manage AWS resources:
kms:CancelKeyDeletion
kms:CreateAlias
kms:CreateKey
kms:DeleteImportedKeyMaterial
kms:DescribeKey
kms:DisableKey
kms:DisableKeyRotation
kms:EnableKey
kms:EnableKeyRotation
kms:GetKeyPolicy
kms:GetParametersForImport
kms:ImportKeyMaterial
kms:ListAliases
kms:ListKeyPolicies
kms:ListKeys
kms:PutKeyPolicy
kms:ScheduleKeyDeletion
kms:TagResource
kms:UntagResource
kms:UpdateAlias
kms:UpdateKeyDescription
For example:
{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "kms:*Alias", "kms:CreateKey", "kms:DeleteAlias", "kms:Describe*", "kms:GenerateRandom", "kms:Get*", "kms:List*", "kms:TagResource", "kms:UntagResource", "iam:ListGroups", "iam:ListRoles", "iam:ListUsers" ], "Resource": "*" } ] }(Optional) Permissions needed to view reports
The following IAM permissions are needed to view reports:
logs:DescribeLogGroups
logs:FilterLogEvents
For example:
{ "Version": "2012-10-17", "Statement": [ { "Action": [ "logs:DescribeLogGroups", "logs:FilterLogEvents" ], "Effect": "Allow", "Resource": "*" } ] }
Use the AWS KMS APIs to perform the following tasks:
Listing AWS Account and Regions
Use the post /v1/cckm/aws/accounts API to list the account and regions associated with a connection added to the CipherTrust Manager.
If you specify only the mandatory parameter, connection, the API returns only the account (with its regions) associated with the specified connection. To view the details of the account associated with the assumed role, refer to Listing AWS Account and Regions by AssumeRole.
Syntax
curl -k '<IP>/api/v1/cckm/aws/accounts' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "connection": "<connection_identifier>"\n}' --compressed
Request Parameter
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| assume_role_arn | string | Updates the ARN of the role to be assumed. |
| assume_role_external_id | string | Updates the External ID for the role to be assumed. |
Request Query Parameters
| Parameter | Type | Description |
|---|---|---|
| connection | string | Name or ID of the connection in which the AWS account is managed. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/accounts' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI5Mjg1NzViYS1iNzg0LTRkNzgtODhiMS1jNjNiMTY5ZDM1YTciLCJzdWIiOiJsb2NhbHxkMWM1MzM2Ni0xMGNiLTQxMjEtYTM3ZC00MmNhMzlkNzNjZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYmE0YjFhZDAtYzEzMC00NjgyLWE5NjQtMzZlNWVhYjExZTM2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjQ2MTMwYzE3LWYwMWQtNDU2YS1hZjBlLWNkMjIyZWNhNzgwOSIsImlhdCI6MTU5NTk5NTcxNiwiZXhwIjoxNTk1OTk2MDE2fQ.pgvpBaDXFlvXwbkFFPc4ENL4buhg8lQrK-njtQbF_TE' -H 'Content-Type: application/json' --data-binary $'{\n "connection": "test_aws-connection"\n}' --compressed
Example Response
{
"account_id": "123456789012",
"regions": [
"eu-north-1",
"ap-south-1",
"eu-west-3",
"eu-west-2",
"eu-west-1",
"ap-northeast-2",
"ap-northeast-1",
"sa-east-1",
"ca-central-1",
"ap-southeast-1",
"ap-southeast-2",
"eu-central-1",
"us-east-1",
"us-east-2",
"us-west-1",
"us-west-2"
]
}
The sample output displays the account (123456789012) and regions managed by the connection (test_aws-connection).
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Listing AWS Account and Regions by AssumeRole
Use the post /v1/cckm/aws/accounts API to list the account and regions associated with a connection added to the CipherTrust Manager.
To view the details of the account associated with the role to be assumed, you need to specify the ARN and external ID (if required) associated with the role.
Note
An AssumeRole provides a set of temporary security credentials that you can use to access AWS resources that you might not normally have access to. Refer to AWS documentation for details on AWS AssumeRole.
Tip
To configure AWS accounts for AssumeRole, refer to IAM tutorial: Delegate access across AWS accounts using IAM roles.
Syntax
curl -k '<IP>/api/v1/cckm/aws/accounts' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "connection": "<connection_identifier>",\n "assume_role_arn": "<arn-of-assume-role>",\n "assume_role_external_id": "<assume_role_external_id>"\n}' --compressed
Request Parameter
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Request Query Parameters
| Parameter | Type | Description |
|---|---|---|
| connection | string | Name or ID of the connection in which the AWS account is managed. |
| assume_role_arn | string | Amazon Resource Name (ARN) of the role to be assumed. |
| assume_role_external_id | string | External ID for the role to be assumed. This parameter can be specified only with assume_role_arn. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/accounts' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI5Mjg1NzViYS1iNzg0LTRkNzgtODhiMS1jNjNiMTY5ZDM1YTciLCJzdWIiOiJsb2NhbHxkMWM1MzM2Ni0xMGNiLTQxMjEtYTM3ZC00MmNhMzlkNzNjZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYmE0YjFhZDAtYzEzMC00NjgyLWE5NjQtMzZlNWVhYjExZTM2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjQ2MTMwYzE3LWYwMWQtNDU2YS1hZjBlLWNkMjIyZWNhNzgwOSIsImlhdCI6MTU5NTk5NTcxNiwiZXhwIjoxNTk1OTk2MDE2fQ.pgvpBaDXFlvXwbkFFPc4ENL4buhg8lQrK-njtQbF_TE' -H 'Content-Type: application/json' --data-binary $'{\n "connection": "test_aws-connection",\n "assume_role_arn": "arn:aws:iam::789012123456:role/test-assume-role-ac",\n "assume_role_external_id": "test-ext-id"\n}' --compressed
Example Response
{
"account_id": "789012123456",
"regions": [
"eu-north-1",
"ap-south-1",
"eu-west-3",
"eu-west-2",
"eu-west-1",
"ap-northeast-2",
"ap-northeast-1",
"sa-east-1",
"ca-central-1",
"ap-southeast-1",
"ap-southeast-2",
"eu-central-1",
"us-east-1",
"us-east-2",
"us-west-1",
"us-west-2"
]
"assume_role_arn": "arn:aws:iam::789012123456:role/test-assume-role-ac",
"assume_role_external_id": "test-ext-id"
}
The sample output displays the details of account (789012123456) and regions of the assumed role over the connection (test_aws-connection).
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Adding AWS KMS Account and Regions to CCKM
Use the post /v1/cckm/aws/kms API to add the AWS KMS account and regions to the CCKM. You can perform cryptographic and key management operations on the AWS KMS.
CCKM allows adding same AWS account in one CipherTrust Manager domain with different names, with each entry having a unique set of regions.
By default, only the KMSs linked with the AWS account that is used for connection with the CipherTrust Manager can be added. However, if you want, you can assume a role within the same or a different account, while adding KMS over the same connection. Refer to Adding AWS KMS Account and Regions by AssumeRole for details.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "account_id": "<account_id>",\n "connection": "<connection_identifier>",\n "name": "<KMS_identifirer>",\n "regions": [region]\n}' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| account_id | string | ID of the AWS account. |
| connection | string | Name or ID of the connection in which the AWS account is managed. |
| name | string | Unique name for the AWS KMS. |
| regions | array of strings | AWS regions to be added to the CCKM. If you select a subset of available regions, then the remaining regions can be added under a different AWS KMS account name but under the same AWS account_id. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI5Mjg1NzViYS1iNzg0LTRkNzgtODhiMS1jNjNiMTY5ZDM1YTciLCJzdWIiOiJsb2NhbHxkMWM1MzM2Ni0xMGNiLTQxMjEtYTM3ZC00MmNhMzlkNzNjZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYmE0YjFhZDAtYzEzMC00NjgyLWE5NjQtMzZlNWVhYjExZTM2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImY1ZWVjMTc5LTlhZjQtNGQ3Yi04Njc5LTU1MWRkYzQ0OGRlNiIsImlhdCI6MTU5NTk5NzkxMSwiZXhwIjoxNTk1OTk4MjExfQ.hKpRsjPANFWyEFU9Q0YfEq32cG5TL-ouOyQtrmgqj-M' -H 'Content-Type: application/json' --data-binary $'{\n "account_id": "123456789012",\n "connection": "test_aws-connection",\n "name": "kms-name",\n "regions": [\n"eu-north-1",\n"ap-south-1",\n"eu-west-3",\n"eu-west-2",\n"eu-west-1",\n"ap-northeast-2",\n"ap-northeast-1",\n"sa-east-1",\n"ca-central-1",\n"ap-southeast-1",\n"ap-southeast-2",\n"eu-central-1",\n"us-east-1",\n"us-east-2",\n"us-west-1",\n"us-west-2"\n]\n}' --compressed
Example Response
{
"id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2020-11-05T05:29:17.200168Z",
"account_id": "123456789012",
"arn": "arn:aws:iam::123456789012:user/user1",
"connection": "aws",
"regions": [
"ap-south-1",
"us-east-1"
],
"cloud_name": "aws"
}
The sample output shows that the AWS account and regions are added to the CCKM, and a unique ID (0b90f8de-8617-498d-ad63-ca18eb717ae7) is returned.
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Adding AWS KMS Account and Regions by AssumeRole
Use the post /v1/cckm/aws/kms API to add the AWS KMS account and regions to the CCKM. You can perform cryptographic and key management operations on the AWS KMS.
CCKM allows adding same AWS account in one CipherTrust Manager domain with different names, with each entry having a unique set of regions.
By default, only the KMSs linked with the AWS account that is used for connection with the CipherTrust Manager can be added. However, if you want, you can assume a role within the same or a different account, while adding KMS over the same connection. To do this, you need to specify the ARN and/or external ID of the role to be assumed.
Note
An AssumeRole provides a set of temporary security credentials that you can use to access AWS resources that you might not normally have access to. Refer to AWS documentation for details on AWS AssumeRole.
Tip
To configure AWS accounts for AssumeRole, refer to IAM tutorial: Delegate access across AWS accounts using IAM roles.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "account_id": "<account_id>",\n "connection": "<connection_identifier>",\n "name": "<KMS_identifirer>",\n "regions": [region],\n "assume_role_arn": "<arn-of-assume-role>",\n "assume_role_external_id": "<assume_role_external_id>"\n}' --compressed
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| account_id | string | ID of the AWS account. |
| connection | string | Name or ID of the connection in which the AWS account is managed. |
| name | string | Unique name for the AWS KMS. |
| regions | array of strings | AWS regions to be added to the CCKM. If you select a subset of available regions, then the remaining regions can be added under a different AWS KMS account name but under the same AWS account_id. |
| assume_role_arn | string | Amazon Resource Name (ARN) of the role to be assumed. |
| assume_role_external_id | string | External ID for the role to be assumed. This parameter can be specified only with assume_role_arn. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI5Mjg1NzViYS1iNzg0LTRkNzgtODhiMS1jNjNiMTY5ZDM1YTciLCJzdWIiOiJsb2NhbHxkMWM1MzM2Ni0xMGNiLTQxMjEtYTM3ZC00MmNhMzlkNzNjZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYmE0YjFhZDAtYzEzMC00NjgyLWE5NjQtMzZlNWVhYjExZTM2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImY1ZWVjMTc5LTlhZjQtNGQ3Yi04Njc5LTU1MWRkYzQ0OGRlNiIsImlhdCI6MTU5NTk5NzkxMSwiZXhwIjoxNTk1OTk4MjExfQ.hKpRsjPANFWyEFU9Q0YfEq32cG5TL-ouOyQtrmgqj-M' -H 'Content-Type: application/json' --data-binary $'{\n "account_id": "789012123456",\n "connection": "test_aws-connection",\n "name": "kms-name",\n "regions": [\n"eu-north-1",\n"ap-south-1",\n"eu-west-3",\n"eu-west-2",\n"eu-west-1",\n"ap-northeast-2",\n"ap-northeast-1",\n"sa-east-1",\n"ca-central-1",\n"ap-southeast-1",\n"ap-southeast-2",\n"eu-central-1",\n"us-east-1",\n"us-east-2",\n"us-west-1",\n"us-west-2"\n],\n "assume_role_arn": "arn:aws:iam::789012123456:role/test-assume-role-ac",\n "assume_role_external_id": "test-ext-id"\n}' --compressed
Example Response
{
"id": "ad63-ca18eb717ae7-0b90f8de-8617-498d",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2022-12-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2022-12-05T05:29:17.200168Z",
"account_id": "789012123456",
"arn": "arn:aws:iam::789012123456:user/user1",
"assume_role_arn": "arn:aws:iam::789012123456:role/test-assume-role-ac",
"assume_role_external_id": "test-ext-id",
"connection": "aws",
"regions": [
"ap-south-1",
"us-east-1"
],
"cloud_name": "aws"
}
The sample output shows that the AWS account and regions linked with the assumed role are added to the CCKM, and a unique ID (ad63-ca18eb717ae7-0b90f8de-8617-498d) is returned.
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Viewing List of AWS KMSs
Use the get /v1/cckm/aws/kms API to view the list of the AWS KMSs. The results can be filtered using the query parameters.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms?skip=0&limit=10' -H 'Authorization: Bearer AUTHTOKEN' --compressed
Request Parameter
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Request Query Parameters
| Parameter | Type | Description |
|---|---|---|
| id | string | ID of the AWS KMS. |
| name | string | Name of the KMS. |
| account_id | string | ID of the AWS account. |
| cloud_name | string | Name of the cloud, aws, aws-us-gov, or aws-cn. |
| skip | integer | Number of records to skip. For example, if "skip":5 is specified, the first five records will not be displayed in the output. |
| limit | integer | Numbers of records to display. For example, if "limit":10 is specified, then the next 10 records (after skipping the number of records specified in the skip parameter) will be displayed in the output. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms?skip=0&limit=10' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiI5Mjg1NzViYS1iNzg0LTRkNzgtODhiMS1jNjNiMTY5ZDM1YTciLCJzdWIiOiJsb2NhbHxkMWM1MzM2Ni0xMGNiLTQxMjEtYTM3ZC00MmNhMzlkNzNjZmMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiYmE0YjFhZDAtYzEzMC00NjgyLWE5NjQtMzZlNWVhYjExZTM2Iiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjJhZjM0NGU3LTAzNjItNDU5My04OTM3LWNmYjRjY2JiOWNkZCIsImlhdCI6MTU5NjAwMDQwOSwiZXhwIjoxNTk2MDAwNzA5fQ.hLVRNt9JbgCraJI9Z71j5IOBEGDWXMr3ue9CNCGWn4I' --compressed
Example Response
{
"skip": 0,
"limit": 10,
"total": 1,
"resources": [
{
"id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2020-11-05T05:29:17.200168Z",
"account_id": "123456789012",
"arn": "arn:aws:iam::123456789012:user/user1",
"connection": "aws",
"regions": [
"ap-south-1",
"us-east-1"
],
"cloud_name": "aws"
}
]
}
The sample output shows the list of the available AWS KMSs on the CCKM.
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Viewing Details of AWS KMSs
Use the get /v1/cckm/aws/kms/{id} API to view the details of an AWS KMS with a specific ID.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms/{id}' -H 'Authorization: Bearer AUTHTOKEN' --compressed
Here, {id} represents the KMS ID.
Request Parameter
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms/0b90f8de-8617-498d-ad63-ca18eb717ae7' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjFjZTgwOTNkLWFlNzgtNDcyMS1iZTUzLTkzZGZiY2NlNjVmOSIsImlhdCI6MTYwNDU1NzgxMCwiZXhwIjoxNjA0NTU4MTEwfQ.IqJZcTF6eOovBYCMy2gOopRSDGRl5IascYAJhFk75dg' --compressed
Example Response
{
"id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2020-11-05T05:29:17.200168Z",
"account_id": "123456789012",
"arn": "arn:aws:iam::123456789012:user/user1",
"connection": "aws",
"regions": [
"ap-south-1",
"us-east-1"
],
"cloud_name": "aws"
}
The sample output shows the details corresponding to the AWS KMS ID (0b90f8de-8617-498d-ad63-ca18eb717ae7).
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Deleting AWS KMS Accounts
Use the delete /v1/cckm/aws/kms/{id} API to delete an AWS KMS account from the CCKM.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms/{id}' -X DELETE -H 'Authorization: Bearer AUTHTOKEN' --compressed
Here, {id} represents the KMS ID.
Request Parameter
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms/0b90f8de-8617-498d-ad63-ca18eb717ae7' -X DELETE -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjFjZTgwOTNkLWFlNzgtNDcyMS1iZTUzLTkzZGZiY2NlNjVmOSIsImlhdCI6MTYwNDU1NzgxMCwiZXhwIjoxNjA0NTU4MTEwfQ.IqJZcTF6eOovBYCMy2gOopRSDGRl5IascYAJhFk75dg' --compressed
Example Response
{
"status": 204
}
The sample output shows that the AWS KMS account (with ID 5e221b78-a24e-4b5f-9af2-a7c46a0cf542) is deleted successfully from the CCKM and "status": 204 is returned in response.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Updating AWS KMS Accounts
Use the patch /v1/cckm/aws/kms/{id} API to modify the AWS KMS parameters such as connection and regions. You can update only one parameter at a time.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms/{id}' -X PATCH -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n \n "regions": ["region"]\n}' --compressed
Here, {id} represents the KMS ID.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| connection | string | Name or ID of the connection in which the AWS account is managed. |
| regions | array of strings | Regions to be updated. |
| assume_role_arn | string | Updates the ARN of the role to be assumed. |
| assume_role_external_id | string | Updates the External ID for the role to be assumed. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms/0b90f8de-8617-498d-ad63-ca18eb717ae7' -X PATCH -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6IjFjZTgwOTNkLWFlNzgtNDcyMS1iZTUzLTkzZGZiY2NlNjVmOSIsImlhdCI6MTYwNDU1NzgxMCwiZXhwIjoxNjA0NTU4MTEwfQ.IqJZcTF6eOovBYCMy2gOopRSDGRl5IascYAJhFk75dg' -H 'Content-Type: application/json' --data-binary $'{\n "regions": ["us-east-1","ap-south-1","us-east-2"]\n}' --compressed
Example Response
{
"id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2020-11-05T06:32:48.93875576Z",
"account_id": "123456789012",
"arn": "arn:aws:iam::123456789012:user/user1",
"connection": "aws",
"regions": [
"us-east-1",
"ap-south-1",
"us-east-2"
],
"cloud_name": "aws"
}
The sample output shows that the updated region (us-east-1, ap-south-1, and us-east-2) for the AWS KMS ID (0b90f8de-8617-498d-ad63-ca18eb717ae7).
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
Managing User Permissions on AWS KMS
Use the post /v1/cckm/aws/kms/{id}/update-acls API to grant permissions to users to perform specific actions on the AWS KMS.
For the first time users, actions are permitted as configured by the CCKM administrator. However, if the permissions of a user need to be modified later, for example, a new action is to be permitted or an existing action is to be revoked, the CCKM administrator needs to set that particular action to true or false.
Syntax
curl -k '<IP>/api/v1/cckm/aws/kms/{id}/update-acls' -H 'Authorization: Bearer AUTHTOKEN' -H 'Content-Type: application/json' --data-binary $'{\n "user_id": "<user id>", \n "permit": <boolean>,\n "actions": [actions]\n}' --compressed
Here, {id} represents the KMS ID.
Request Parameters
| Parameter | Type | Description |
|---|---|---|
| AUTHTOKEN | string | Authorization token. |
| actions | array of strings | Permitted actions on the AWS KMS. For example, a user with the keyupdate permission can perform actions such as update the key policy, enable/disable key, and add/remove alias. Refer to APIs and Action Mapping for the supported actions and details. |
| group | string | Name of the group to be granted permissions. |
| permit | boolean | Flag to permit users to perform specific actions on the AWS KMS. Set to true to permit, false to deny. |
| user_id | string | ID of the user to be granted permissions. |
Note
User ID and group are mutually exclusive – specify either of the two.
APIs and Action Mapping
The following table lists the mapping of APIs and actions required to call these APIs.
| APIs | Actions Required | Description |
|---|---|---|
| Create | keycreate | Permission to create an AWS key. |
| Import | keymaterialimport | Permission to import the key on the AWS KMS. |
| Delete key material | keymaterialdelete | Permission to delete the imported key material from AWS KMS. |
| Rotate | keyrotate | Permission to rotate the key on the AWS KMS. |
| Schedule Deletion | keydelete | Permission for schedule deletion of the key. |
| Cancel delete | keycanceldelete | Permission to cancel deletion of the key. |
| Synchronize | keysynchronize | Permission to synchronize AWS keys. |
| Cancel | keysynchronize | Permission to cancel a synchronization job. |
| Update key policy | keyupdate | Permission to update the AWS key policy. |
| Update key description | keyupdate | Permission to update the AWS key description. |
| Enable key | keyupdate | Permission to enable the AWS key. |
| Disable key | keyupdate | Permission to disable the AWS key. |
| Add tags | keyupdate | Permission to add tags to the AWS key. |
| Remove tags | keyupdate | Permission to rem ove tags from the AWS key. |
| Add alias | keyupdate | Permission to add an alias to the AWS key. |
| Delete alias | keyupdate | Permission to deletes alias from the AWS key. |
| Enable key rotation | keyupdate | Permission to enable automatic key rotation of the AWS key. |
| Disable key rotation | keyupdate | Permission to disable automatic key rotation of the AWS key. |
| Upload | keyupload | Permission to upload the key to the AWS KMS. |
| List | viewnative | Permission to view KMS and its native keys. |
| Get (AWS Keys) | view | |
| List | viewbyok | Permission to view kms and its external keys. |
| Get (AWS Keys) | viewnative/viewbyok | Permission to get the details of an AWS key with the given id. |
| List AWS KMS | viewnative/viewbyok | Permission to view kms and its keys. |
| Get (AWS Kms) | viewnative/viewbyok | Permission to get the details of AWS KMS with the given id. |
| List (CloudHSM Key) | viewcloudhsmkey | Permission to view AWS CloudHSM keys. |
| Create (CloudHSM Key) | cloudhsmkeycreate | Permission to create an AWS CloudHSM key. |
| Delete (CloudHSM Key) | cloudhsmkeydelete | Permission to delete an AWS CloudHSM key. |
| List (Custom Key Store) | viewkeystore | Permission to view Custom key stores. |
| Create (Custom Key Store) | keystoreadd | Permission to add Custom key store. |
| Update (Custom Key Store) | keystoreupdate | Permission to update Custom key store properties. |
| Delete (Custom Key Store) | keystoredelete | Permission to delete Custom key store. |
| Connect (Custom Key Store) | keystoreconnect | Permission to connect Custom key store to AWS. |
| Disconnect (Custom Key Store) | keystoredisconnect | Permission to disconnect Custom key store from AWS. |
| Block (Custom Key Store) | keystoreblock | Permission to block any operations on keys in Custom key store. |
| Unblock (Custom Key Store) | keystoreunblock | Permission to unblock operations on keys in Custom key store. |
| Link (Custom Key Store) | keystorelink | Permission to link Custom key store to AWS. |
| List (HYOK Key) | viewhyokkey | Permission to view AWS HYOK keys. |
| Create (HYOK Key) | hyokkeycreate | Permission to create an AWS HYOK key. |
| Block/Unblock (HYOK Key) | hyokkeyblockunblock | Permission to block/unblock an AWS HYOK key. |
| Delete (HYOK Key) | hyokkeydelete | Permission to delete an AWS HYOK key (applicable only to unlinked key). |
| Link (HYOK Key) | hyokkeylink | Permission to link an HYOK key in CM to HYOK key in AWS. |
| Create Report | reportcreate | Permission to create a report. |
| Delete Report | reportdelete | Permission to delete a report. |
| Download Report | reportdownload | Permission to download a report. |
| View Report | reportview | Permission to view the content of a report. |
| Bulk Operation | keybulkoperation | Permission to perform bulk job operations. |
Example Request
curl -k 'https://127.0.0.1/api/v1/cckm/aws/kms/0b90f8de-8617-498d-ad63-ca18eb717ae7/update-acls' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJjNWMwZGJlNC1lMmJmLTQ3M2MtODY4MC01NWVkMWIzMDEzMmEiLCJzdWIiOiJsb2NhbHxhNjdjMzc0OC05YTRiLTRhZGQtYjNkOS0wNTRiYTIwYmUzYWMiLCJpc3MiOiJreWxvIiwiYWNjIjoia3lsbyIsInByZWZlcnJlZF91c2VybmFtZSI6ImFkbWluIiwiY3VzdCI6eyJkb21haW5faWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJncm91cHMiOlsiYWRtaW4iXSwic2lkIjoiMDhkNDI5ZjktNDgzYi00ODdlLWJjOTQtNGE1Mjc2ZDI2ZjZjIiwiem9uZV9pZCI6IjAwMDAwMDAwLTAwMDAtMDAwMC0wMDAwLTAwMDAwMDAwMDAwMCJ9LCJqd3RpZCI6ImIyZjQxZTFiLTc0MmQtNDA1Mi04NTA5LWRlZDE1NjNjNjRmNCIsImlhdCI6MTYwNDU1OTAyMywiZXhwIjoxNjA0NTU5MzIzfQ.R9TjeIn5d9N7-V_8FGcl-90aRarpQayXfBL2OJ50AKk' -H 'Content-Type: application/json' --data-binary $'{\n "acls": [ {\n "actions": [\n "view","keycreate"\n ],\n "group": "CCKM Users",\n "permit": true\n }]\n}' --compressed
Example Response
{
"id": "0b90f8de-8617-498d-ad63-ca18eb717ae7",
"uri": "kylo:kylo:cckm:kms:kms",
"account": "kylo:kylo:admin:accounts:kylo",
"application": "ncryptify:gemalto:admin:apps:kylo",
"devAccount": "ncryptify:gemalto:admin:accounts:gemalto",
"createdAt": "2020-11-05T05:29:17.200168Z",
"name": "kms",
"updatedAt": "2020-11-05T06:34:10.828983451Z",
"account_id": "123456789012",
"arn": "arn:aws:iam::123456789012:user/user1",
"acls": [
{
"group": "CCKM Users",
"actions": [
"view",
"keycreate"
]
}
],
"connection": "aws",
"regions": [
"us-east-1",
"ap-south-1",
"us-east-2"
],
"cloud_name": "aws"
}
The sample output shows that the group (CCKM Users) is granted permissions to perform the view and keycreate operations on the AWS KMS (with ID 0b90f8de-8617-498d-ad63-ca18eb717ae7).
To know more about response parameters, refer to Response Parameters of AWS KMS APIs.
Response Codes
| Response Code | Description |
|---|---|
| 2xx | Success |
| 4xx | Client errors |
| 5xx | Server errors |
Refer to HTTP status codes for details.
After the permissions are configured on the AWS KMS, run the get /v1/cckm/aws/kms API to view the details of the AWS KMS with the list of actions a user can perform on the AWS KMS.
