Response Syntax

CloudHsmClusterId (p. 15)

Identiﬁes the AWS CloudHSM cluster for the custom key store. Enter the cluster ID of any active AWS CloudHSM cluster that is not already associated with a custom key store. To ﬁnd the cluster ID, use the DescribeClusters operation.

Type: String

Length Constraints: Minimum length of 19. Maximum length of 24.

Required: Yes

CustomKeyStoreName (p. 15)

Speciﬁes a friendly name for the custom key store. The name must be unique in your AWS account.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Required: Yes

KeyStorePassword (p. 15)

Enter the password of the kmsuser crypto user (CU) account in the speciﬁed AWS CloudHSM cluster.

AWS KMS logs into the cluster as this user to manage key material on your behalf.

The password must be a string of 7 to 32 characters. Its value is case sensitive.

This parameter tells AWS KMS the kmsuser account password; it does not change the password in the AWS CloudHSM cluster.

Type: String

Length Constraints: Minimum length of 7. Maximum length of 32.

Required: Yes

TrustAnchorCertiﬁcate (p. 15)

Enter the content of the trust anchor certiﬁcate for the cluster. This is the content of the customerCA.crt ﬁle that you created when you initialized the cluster.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 5000.

Required: Yes

{

"CustomKeyStoreId": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

Errors

The following data is returned in JSON format by the service.

CustomKeyStoreId (p. 16)

A unique identiﬁer for the new custom key store.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 64.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 241).

CloudHsmClusterInUseException

The request was rejected because the speciﬁed AWS CloudHSM cluster is already associated with a custom key store or it shares a backup history with a cluster that is associated with a custom key store. Each custom key store must be associated with a diﬀerent AWS CloudHSM cluster.

Clusters that share a backup history have the same cluster certiﬁcate. To view the cluster certiﬁcate of a cluster, use the DescribeClusters operation.

HTTP Status Code: 400

CloudHsmClusterInvalidConﬁgurationException

The request was rejected because the associated AWS CloudHSM cluster did not meet the conﬁguration requirements for a custom key store.

• The cluster must be conﬁgured with private subnets in at least two diﬀerent Availability Zones in the Region.

• The security group for the cluster (cloudhsm-cluster-<cluster-id>-sg) must include inbound rules and outbound rules that allow TCP traﬃc on ports 2223-2225. The Source in the inbound rules and the Destination in the outbound rules must match the security group ID. These rules are set by default when you create the cluster. Do not delete or change them. To get information about a particular security group, use the DescribeSecurityGroups operation.

• The cluster must contain at least as many HSMs as the operation requires. To add HSMs, use the AWS CloudHSM CreateHsm operation.

For the CreateCustomKeyStore (p. 15), UpdateCustomKeyStore (p. 205), and

CreateKey (p. 26) operations, the AWS CloudHSM cluster must have at least two active HSMs, each in a diﬀerent Availability Zone. For the ConnectCustomKeyStore (p. 8) operation, the AWS CloudHSM must contain at least one active HSM.

For information about the requirements for an AWS CloudHSM cluster that is associated with a custom key store, see Assemble the Prerequisites in the AWS Key Management Service Developer Guide. For information about creating a private subnet for an AWS CloudHSM cluster, see Create a Private Subnet in the AWS CloudHSM User Guide. For information about cluster security groups, see Conﬁgure a Default Security Group in the AWS CloudHSM User Guide .

HTTP Status Code: 400

CloudHsmClusterNotActiveException

The request was rejected because the AWS CloudHSM cluster that is associated with the custom key store is not active. Initialize and activate the cluster and try the command again. For detailed instructions, see Getting Started in the AWS CloudHSM User Guide.

HTTP Status Code: 400

Request Syntax

{

"Constraints": {

"EncryptionContextEquals": { "string" : "string"

"EncryptionContextSubset": { "string" : "string"

} },

"GranteePrincipal": "string", "GrantTokens": [ "string" ], "KeyId": "string",

Request Parameters

"Name": "string",

"Operations": [ "string" ], "RetiringPrincipal": "string"

}

Request Parameters

For information about the parameters that are common to all actions, see Common Parameters (p. 239).

The request accepts the following data in JSON format.

NoteIn the following list, the required parameters are described ﬁrst.

GranteePrincipal (p. 19)

The identity that gets the permissions speciﬁed in the grant.

To specify the principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid AWS principals include AWS accounts (root), IAM users, IAM roles, federated users, and assumed role users. For examples of the ARN syntax to use for specifying a principal, see AWS Identity and Access Management (IAM) in the Example ARNs section of the AWS General Reference.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^[\w+=,.@:/-]+$

Required: Yes KeyId (p. 19)

Identiﬁes the KMS key for the grant. The grant gives principals permission to use this KMS key.

Specify the key ID or key ARN of the KMS key. To specify a KMS key in a diﬀerent AWS account, you must use the key ARN.

For example:

• Key ID: 1234abcd-12ab-34cd-56ef-1234567890ab

• Key ARN:

arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab To get the key ID and key ARN for a KMS key, use ListKeys (p. 144) or DescribeKey (p. 55).

Type: String

Length Constraints: Minimum length of 1. Maximum length of 2048.

Required: Yes Operations (p. 19)

A list of operations that the grant permits.

The operation must be supported on the KMS key. For example, you cannot create a grant for a symmetric KMS key that allows the Sign (p. 189) operation, or a grant for an asymmetric KMS key that allows the GenerateDataKey (p. 81) operation. If you try, AWS KMS returns a

ValidationError exception. For details, see Grant operations in the AWS Key Management Service Developer Guide.

Request Parameters

Type: Array of strings

Valid Values: Decrypt | Encrypt | GenerateDataKey |

GenerateDataKeyWithoutPlaintext | ReEncryptFrom | ReEncryptTo | Sign

Required: Yes Constraints (p. 19)

Speciﬁes a grant constraint.

AWS KMS supports the EncryptionContextEquals and EncryptionContextSubset grant constraints. Each constraint value can include up to 8 encryption context pairs. The encryption context value in each constraint cannot exceed 384 characters.

These grant constraints allow the permissions in the grant only when the encryption context in the request matches (EncryptionContextEquals) or includes (EncryptionContextSubset) the encryption context speciﬁed in this structure. For information about grant constraints, see Using grant constraints in the AWS Key Management Service Developer Guide. For more information about encryption context, see Encryption Context in the AWS Key Management Service Developer Guide . The encryption context grant constraints are supported only on operations that include an

encryption context. You cannot use an encryption context grant constraint for cryptographic operations with asymmetric KMS keys or for management operations, such as DescribeKey (p. 55) or RetireGrant (p. 177).

Type: GrantConstraints (p. 227) object Required: No

GrantTokens (p. 19) A list of grant tokens.

Use a grant token when your permission to call this operation comes from a new grant that has not yet achieved eventual consistency. For more information, see Grant token and Using a grant token in the AWS Key Management Service Developer Guide.

Type: Array of strings

Array Members: Minimum number of 0 items. Maximum number of 10 items.

Length Constraints: Minimum length of 1. Maximum length of 8192.

Required: No Name (p. 19)

A friendly name for the grant. Use this value to prevent the unintended creation of duplicate grants when retrying this request.

When this value is absent, all CreateGrant requests result in a new grant with a unique GrantId even if all the supplied parameters are identical. This can result in unintended duplicates when you retry the CreateGrant request.

When this value is present, you can retry a CreateGrant request with identical parameters; if the grant already exists, the original GrantId is returned without creating a new grant. Note that the returned grant token is unique with every CreateGrant request, even when a duplicate GrantId is returned. All grant tokens for the same grant ID can be used interchangeably.

Type: String

Response Syntax

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^[a-zA-Z0-9:/_-]+$

Required: No RetiringPrincipal (p. 19)

The principal that has permission to use the RetireGrant (p. 177) operation to retire the grant.

To specify the principal, use the Amazon Resource Name (ARN) of an AWS principal. Valid AWS principals include AWS accounts (root), IAM users, federated users, and assumed role users.

For examples of the ARN syntax to use for specifying a principal, see AWS Identity and Access Management (IAM) in the Example ARNs section of the AWS General Reference.

The grant determines the retiring principal. Other principals might have permission to retire the grant or revoke the grant. For details, see RevokeGrant (p. 181) and Retiring and revoking grants in the AWS Key Management Service Developer Guide.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 256.

Pattern: ^[\w+=,.@:/-]+$

Required: No

Response Syntax

{ "GrantId": "string", "GrantToken": "string"

}

Response Elements

If the action is successful, the service sends back an HTTP 200 response.

The following data is returned in JSON format by the service.

GrantId (p. 22)

The unique identiﬁer for the grant.

You can use the GrantId in a ListGrants (p. 134), RetireGrant (p. 177), or RevokeGrant (p. 181) operation.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 128.

GrantToken (p. 22) The grant token.

Errors

Type: String

Length Constraints: Minimum length of 1. Maximum length of 8192.

Errors

For information about the errors that are common to all actions, see Common Errors (p. 241).

DependencyTimeoutException

The system timed out while trying to fulﬁll the request. The request can be retried.

HTTP Status Code: 500 DisabledException

The request was rejected because the speciﬁed KMS key is not enabled.

HTTP Status Code: 400 InvalidArnException

The request was rejected because a speciﬁed ARN, or an ARN in a key policy, is not valid.

HTTP Status Code: 400 InvalidGrantTokenException

The request was rejected because the speciﬁed grant token is not valid.

HTTP Status Code: 400 KMSInternalException

The request was rejected because an internal exception occurred. The request can be retried.

HTTP Status Code: 500 KMSInvalidStateException

The request was rejected because the state of the speciﬁed resource is not valid for this request.

For more information about how key state aﬀects the use of a KMS key, see Key state: Eﬀect on your KMS key in the AWS Key Management Service Developer Guide .

HTTP Status Code: 400 LimitExceededException

The request was rejected because a quota was exceeded. For more information, see Quotas in the AWS Key Management Service Developer Guide.

HTTP Status Code: 400 NotFoundException

The request was rejected because the speciﬁed entity or resource could not be found.

HTTP Status Code: 400

Examples

The following examples are formatted for legibility.

Example Request

This example illustrates one usage of CreateGrant.

POST / HTTP/1.1

], "GranteePrincipal": "arn:aws:iam::111122223333:role/ExampleRole",

"KeyId": "arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab"

}

Example Response

This example illustrates one usage of CreateGrant.

HTTP/1.1 200 OK Server: Server

Date: Mon, 31 Oct 2016 20:28:51 GMT Content-Type: application/x-amz-json-1.1 Content-Length: 585

Connection: keep-alive

x-amzn-RequestId: a2d8d452-9fa8-11e6-b30c-dbb8ea4d97c5

{ "GrantId": "0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60", "GrantToken":

For more information about using this API in one of the language-speciﬁc AWS SDKs, see the following:

• AWS Command Line Interface

• AWS SDK for .NET

• AWS SDK for C++

• AWS SDK for Go

• AWS SDK for Java V2

• AWS SDK for JavaScript

• AWS SDK for PHP V3

• AWS SDK for Python

See Also

• AWS SDK for Ruby V3

CreateKey

Creates a unique customer managed KMS key in your AWS account and Region.

NoteAWS KMS is replacing the term customer master key (CMK) with AWS KMS key and KMS key. The concept has not changed. To prevent breaking changes, AWS KMS is keeping some variations of this term.

You can use the CreateKey operation to create symmetric or asymmetric KMS keys.

• Symmetric KMS keys contain a 256-bit symmetric key that never leaves AWS KMS unencrypted. To use the KMS key, you must call AWS KMS. You can use a symmetric KMS key to encrypt and decrypt small amounts of data, but they are typically used to generate data keys and data keys pairs. For details, see GenerateDataKey (p. 81) and GenerateDataKeyPair (p. 87).

• Asymmetric KMS keys can contain an RSA key pair or an Elliptic Curve (ECC) key pair. The private key in an asymmetric KMS key never leaves AWS KMS unencrypted. However, you can use the GetPublicKey (p. 119) operation to download the public key so it can be used outside of AWS KMS.

KMS keys with RSA key pairs can be used to encrypt or decrypt data or sign and verify messages (but not both). KMS keys with ECC key pairs can be used only to sign and verify messages.

For information about symmetric and asymmetric KMS keys, see Asymmetric KMS keys in the AWS Key Management Service Developer Guide.

To create diﬀerent types of KMS keys, use the following guidance:

Asymmetric KMS keys

To create an asymmetric KMS key, use the KeySpec parameter to specify the type of key material in the KMS key. Then, use the KeyUsage parameter to determine whether the KMS key will be used to encrypt and decrypt or sign and verify. You can't change these properties after the KMS key is created.

Symmetric KMS keys

When creating a symmetric KMS key, you don't need to specify the KeySpec or KeyUsage parameters. The default value for KeySpec, SYMMETRIC_DEFAULT, and the default value for KeyUsage, ENCRYPT_DECRYPT, are the only valid values for symmetric KMS keys.

Multi-Region primary keys, Imported key material

To create a multi-Region primary key in the local AWS Region, use the MultiRegion parameter with a value of True. To create a multi-Region replica key, that is, a KMS key with the same key ID and key material as a primary key, but in a diﬀerent AWS Region, use the ReplicateKey (p. 170) operation. To change a replica key to a primary key, and its primary key to a replica key, use the UpdatePrimaryRegion (p. 213) operation.

This operation supports multi-Region keys, an AWS KMS feature that lets you create multiple interoperable KMS keys in diﬀerent AWS Regions. Because these KMS keys have the same key ID, key material, and other metadata, you can use them interchangeably to encrypt data in one AWS Region and decrypt it in a diﬀerent AWS Region without re-encrypting the data or making a cross-Region call. For more information about multi-Region keys, see Multi-Region keys in AWS KMS in the AWS Key Management Service Developer Guide.

You can create symmetric and asymmetric multi-Region keys and multi-Region keys with imported key material. You cannot create multi-Region keys in a custom key store.

Request Syntax

To import your own key material, begin by creating a symmetric KMS key with no key material.

To do this, use the Origin parameter of CreateKey with a value of EXTERNAL. Next, use GetParametersForImport (p. 114) operation to get a public key and import token, and use the public key to encrypt your key material. Then, use ImportKeyMaterial (p. 124) with your import token to import the key material. For step-by-step instructions, see Importing Key Material in the AWS Key Management Service Developer Guide . You cannot import the key material into an asymmetric KMS key.

To create a multi-Region primary key with imported key material, use the Origin parameter of CreateKey with a value of EXTERNAL and the MultiRegion parameter with a value of True.

To create replicas of the multi-Region primary key, use the ReplicateKey (p. 170) operation. For more information about multi-Region keys, see Multi-Region keys in AWS KMS in the AWS Key Management Service Developer Guide.

Custom key store

在文檔中 AWS Key Management Service (頁 25-200)