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
Listing AWS Account and Regions by AssumeRole
Adding AWS KMS Account and Regions to CCKM
Adding AWS KMS Account and Regions by AssumeRole
Viewing List of AWS KMSs
Viewing Details of AWS KMSs
Deleting AWS KMS Accounts
Updating AWS KMS Accounts
Managing User Permissions on AWS KMS

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.

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 Data Security Platform Service 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 Data Security Platform Service 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

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.

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.

Suggest A Change

AWS KMS Management APIs

Prerequisites

Listing AWS Account and Regions

Syntax

Request Parameter

Request Query Parameters

Example Request

Example Response

Response Codes

Listing AWS Account and Regions by AssumeRole

Syntax

Request Parameter

Request Query Parameters

Example Request

Example Response

Response Codes

Adding AWS KMS Account and Regions to CCKM

Syntax

Request Parameters

Example Request

Example Response

Response Codes

Adding AWS KMS Account and Regions by AssumeRole

Syntax

Request Parameters

Example Request

Example Response

Response Codes

Viewing List of AWS KMSs

Syntax

Request Parameter

Request Query Parameters

Example Request

Example Response

Response Codes

Viewing Details of AWS KMSs

Syntax

Request Parameter

Example Request

Example Response

Response Codes

Deleting AWS KMS Accounts

Syntax

Request Parameter

Example Request

Example Response

Response Codes

Updating AWS KMS Accounts

Syntax

Request Parameters

Example Request

Example Response

Response Codes

Managing User Permissions on AWS KMS

Syntax

Request Parameters

APIs and Action Mapping

Example Request

Example Response

Response Codes

On this page