Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo
back

AWS APIs

AWS KMS Management APIs

search

Please Note:

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.

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.

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.

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.

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.

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.

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.