AWS Key Management Service 2014-11-01

CancelKeyDeletion

$result = $client->cancelKeyDeletion([/* ... */]);
$promise = $client->cancelKeyDeletionAsync([/* ... */]);

Parameter Syntax

$result = $client->cancelKeyDeletion([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'KeyId' => '<string>',
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To cancel deletion of a KMS key

The following example cancels deletion of the specified KMS key.

$result = $client->cancelKeyDeletion([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key whose deletion you are canceling. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

Result syntax:

[
    'KeyId' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // The ARN of the KMS key whose deletion you canceled.
]

ConnectCustomKeyStore

$result = $client->connectCustomKeyStore([/* ... */]);
$promise = $client->connectCustomKeyStoreAsync([/* ... */]);

Parameter Syntax

$result = $client->connectCustomKeyStore([
    'CustomKeyStoreId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• CloudHsmClusterNotActiveException:

  The request was rejected because the 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 CloudHSM User Guide.

• CustomKeyStoreInvalidStateException:

  The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores operation.

  This exception is thrown under the following conditions:

  • You requested the CreateKey or GenerateRandom operation in a custom key store that is not connected. These operations are valid only when the custom key store ConnectionState is CONNECTED.

  • You requested the UpdateCustomKeyStore or DeleteCustomKeyStore operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED.

  • You requested the ConnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values.

• CustomKeyStoreNotFoundException:

  The request was rejected because KMS cannot find a custom key store with the specified key store name or ID.

• KMSInternalException:

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

• CloudHsmClusterInvalidConfigurationException:

  The request was rejected because the associated CloudHSM cluster did not meet the configuration requirements for a custom key store.

  • The cluster must be configured with private subnets in at least two different 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 traffic 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 CloudHSM CreateHsm operation.

    For the CreateCustomKeyStore, UpdateCustomKeyStore, and CreateKey operations, the CloudHSM cluster must have at least two active HSMs, each in a different Availability Zone. For the ConnectCustomKeyStore operation, the CloudHSM must contain at least one active HSM.

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

Examples

Example 1: To connect a custom key store to its CloudHSM cluster

This example connects an AWS KMS custom key store to its AWS CloudHSM cluster. This operation does not return any data. To verify that the custom key store is connected, use the DescribeCustomKeyStores operation.

$result = $client->connectCustomKeyStore([
    'CustomKeyStoreId' => 'cks-1234567890abcdef0', // The ID of the AWS KMS custom key store.
]);

Result syntax:

[
]

CreateAlias

$result = $client->createAlias([/* ... */]);
$promise = $client->createAliasAsync([/* ... */]);

Parameter Syntax

$result = $client->createAlias([
    'AliasName' => '<string>', // REQUIRED
    'TargetKeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• AlreadyExistsException:

  The request was rejected because it attempted to create a resource that already exists.

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• InvalidAliasNameException:

  The request was rejected because the specified alias name is not valid.

• KMSInternalException:

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

• LimitExceededException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To create an alias

The following example creates an alias for the specified KMS key.

$result = $client->createAlias([
    'AliasName' => 'alias/ExampleAlias', // The alias to create. Aliases must begin with 'alias/'. Do not use aliases that begin with 'alias/aws' because they are reserved for use by AWS.
    'TargetKeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key whose alias you are creating. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

CreateCustomKeyStore

$result = $client->createCustomKeyStore([/* ... */]);
$promise = $client->createCustomKeyStoreAsync([/* ... */]);

Parameter Syntax

$result = $client->createCustomKeyStore([
    'CloudHsmClusterId' => '<string>', // REQUIRED
    'CustomKeyStoreName' => '<string>', // REQUIRED
    'KeyStorePassword' => '<string>', // REQUIRED
    'TrustAnchorCertificate' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'CustomKeyStoreId' => '<string>',
]

Result Details

Errors

• CloudHsmClusterInUseException:

  The request was rejected because the specified 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 different CloudHSM cluster.

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

• CustomKeyStoreNameInUseException:

  The request was rejected because the specified custom key store name is already assigned to another custom key store in the account. Try again with a custom key store name that is unique in the account.

• CloudHsmClusterNotFoundException:

  The request was rejected because KMS cannot find the CloudHSM cluster with the specified cluster ID. Retry the request with a different cluster ID.

• KMSInternalException:

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

• CloudHsmClusterNotActiveException:

  The request was rejected because the 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 CloudHSM User Guide.

• IncorrectTrustAnchorException:

  The request was rejected because the trust anchor certificate in the request is not the trust anchor certificate for the specified CloudHSM cluster.

  When you initialize the cluster, you create the trust anchor certificate and save it in the customerCA.crt file.

• CloudHsmClusterInvalidConfigurationException:

  The request was rejected because the associated CloudHSM cluster did not meet the configuration requirements for a custom key store.

  • The cluster must be configured with private subnets in at least two different 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 traffic 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 CloudHSM CreateHsm operation.

    For the CreateCustomKeyStore, UpdateCustomKeyStore, and CreateKey operations, the CloudHSM cluster must have at least two active HSMs, each in a different Availability Zone. For the ConnectCustomKeyStore operation, the CloudHSM must contain at least one active HSM.

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

Examples

Example 1: To create an AWS CloudHSM custom key store

This example creates a custom key store that is associated with an AWS CloudHSM cluster.

$result = $client->createCustomKeyStore([
    'CloudHsmClusterId' => 'cluster-1a23b4cdefg', // The ID of the CloudHSM cluster.
    'CustomKeyStoreName' => 'ExampleKeyStore', // A friendly name for the custom key store.
    'KeyStorePassword' => 'kmsPswd', // The password for the kmsuser CU account in the specified cluster.
    'TrustAnchorCertificate' => '', // The content of the customerCA.crt file that you created when you initialized the cluster.
]);

Result syntax:

[
    'CustomKeyStoreId' => 'cks-1234567890abcdef0', // The ID of the new custom key store.
]

CreateGrant

$result = $client->createGrant([/* ... */]);
$promise = $client->createGrantAsync([/* ... */]);

Parameter Syntax

$result = $client->createGrant([
    'Constraints' => [
        'EncryptionContextEquals' => ['<string>', ...],
        'EncryptionContextSubset' => ['<string>', ...],
    ],
    'GrantTokens' => ['<string>', ...],
    'GranteePrincipal' => '<string>', // REQUIRED
    'KeyId' => '<string>', // REQUIRED
    'Name' => '<string>',
    'Operations' => ['<string>', ...], // REQUIRED
    'RetiringPrincipal' => '<string>',
]);

Parameter Details

Result Syntax

[
    'GrantId' => '<string>',
    'GrantToken' => '<string>',
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• InvalidArnException:

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

• KMSInternalException:

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

• InvalidGrantTokenException:

  The request was rejected because the specified grant token is not valid.

• LimitExceededException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To create a grant

The following example creates a grant that allows the specified IAM role to encrypt data with the specified KMS key.

$result = $client->createGrant([
    'GranteePrincipal' => 'arn:aws:iam::111122223333:role/ExampleRole', // The identity that is given permission to perform the operations specified in the grant.
    'KeyId' => 'arn:aws:kms:us-east-2:444455556666:key/1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key to which the grant applies. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
    'Operations' => [
        'Encrypt',
        'Decrypt',
    ], // A list of operations that the grant allows.
]);

Result syntax:

[
    'GrantId' => '0c237476b39f8bc44e45212e08498fbe3151305030726c0590dd8d3e9f3d6a60', // The unique identifier of the grant.
    'GrantToken' => 'AQpAM2RhZTk1MGMyNTk2ZmZmMzEyYWVhOWViN2I1MWM4Mzc0MWFiYjc0ZDE1ODkyNGFlNTIzODZhMzgyZjBlNGY3NiKIAgEBAgB4Pa6VDCWW__MSrqnre1HIN0Grt00ViSSuUjhqOC8OT3YAAADfMIHcBgkqhkiG9w0BBwaggc4wgcsCAQAwgcUGCSqGSIb3DQEHATAeBglghkgBZQMEAS4wEQQMmqLyBTAegIn9XlK5AgEQgIGXZQjkBcl1dykDdqZBUQ6L1OfUivQy7JVYO2-ZJP7m6f1g8GzV47HX5phdtONAP7K_HQIflcgpkoCqd_fUnE114mSmiagWkbQ5sqAVV3ov-VeqgrvMe5ZFEWLMSluvBAqdjHEdMIkHMlhlj4ENZbzBfo9Wxk8b8SnwP4kc4gGivedzFXo-dwN8fxjjq_ZZ9JFOj2ijIbj5FyogDCN0drOfi8RORSEuCEmPvjFRMFAwcmwFkN2NPp89amA', // The grant token.
]

CreateKey

$result = $client->createKey([/* ... */]);
$promise = $client->createKeyAsync([/* ... */]);

Parameter Syntax

$result = $client->createKey([
    'BypassPolicyLockoutSafetyCheck' => true || false,
    'CustomKeyStoreId' => '<string>',
    'CustomerMasterKeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
    'Description' => '<string>',
    'KeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
    'KeyUsage' => 'SIGN_VERIFY|ENCRYPT_DECRYPT|GENERATE_VERIFY_MAC',
    'MultiRegion' => true || false,
    'Origin' => 'AWS_KMS|EXTERNAL|AWS_CLOUDHSM',
    'Policy' => '<string>',
    'Tags' => [
        [
            'TagKey' => '<string>', // REQUIRED
            'TagValue' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'KeyMetadata' => [
        'AWSAccountId' => '<string>',
        'Arn' => '<string>',
        'CloudHsmClusterId' => '<string>',
        'CreationDate' => <DateTime>,
        'CustomKeyStoreId' => '<string>',
        'CustomerMasterKeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
        'DeletionDate' => <DateTime>,
        'Description' => '<string>',
        'Enabled' => true || false,
        'EncryptionAlgorithms' => ['<string>', ...],
        'ExpirationModel' => 'KEY_MATERIAL_EXPIRES|KEY_MATERIAL_DOES_NOT_EXPIRE',
        'KeyId' => '<string>',
        'KeyManager' => 'AWS|CUSTOMER',
        'KeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
        'KeyState' => 'Creating|Enabled|Disabled|PendingDeletion|PendingImport|PendingReplicaDeletion|Unavailable|Updating',
        'KeyUsage' => 'SIGN_VERIFY|ENCRYPT_DECRYPT|GENERATE_VERIFY_MAC',
        'MacAlgorithms' => ['<string>', ...],
        'MultiRegion' => true || false,
        'MultiRegionConfiguration' => [
            'MultiRegionKeyType' => 'PRIMARY|REPLICA',
            'PrimaryKey' => [
                'Arn' => '<string>',
                'Region' => '<string>',
            ],
            'ReplicaKeys' => [
                [
                    'Arn' => '<string>',
                    'Region' => '<string>',
                ],
                // ...
            ],
        ],
        'Origin' => 'AWS_KMS|EXTERNAL|AWS_CLOUDHSM',
        'PendingDeletionWindowInDays' => <integer>,
        'SigningAlgorithms' => ['<string>', ...],
        'ValidTo' => <DateTime>,
    ],
]

Result Details

Errors

• MalformedPolicyDocumentException:

  The request was rejected because the specified policy is not syntactically or semantically correct.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• InvalidArnException:

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

• UnsupportedOperationException:

  The request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation.

• KMSInternalException:

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

• LimitExceededException:

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

• TagException:

  The request was rejected because one or more tags are not valid.

• CustomKeyStoreNotFoundException:

  The request was rejected because KMS cannot find a custom key store with the specified key store name or ID.

• CustomKeyStoreInvalidStateException:

  The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores operation.

  This exception is thrown under the following conditions:

  • You requested the CreateKey or GenerateRandom operation in a custom key store that is not connected. These operations are valid only when the custom key store ConnectionState is CONNECTED.

  • You requested the UpdateCustomKeyStore or DeleteCustomKeyStore operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED.

  • You requested the ConnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values.

• CloudHsmClusterInvalidConfigurationException:

  The request was rejected because the associated CloudHSM cluster did not meet the configuration requirements for a custom key store.

  • The cluster must be configured with private subnets in at least two different 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 traffic 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 CloudHSM CreateHsm operation.

    For the CreateCustomKeyStore, UpdateCustomKeyStore, and CreateKey operations, the CloudHSM cluster must have at least two active HSMs, each in a different Availability Zone. For the ConnectCustomKeyStore operation, the CloudHSM must contain at least one active HSM.

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

Examples

Example 1: To create a KMS key

The following example creates a symmetric KMS key for encryption and decryption. No parameters are required for this operation.

$result = $client->createKey([
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'SYMMETRIC_DEFAULT',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
    ], // Detailed information about the KMS key that this operation creates.
]

Example 2: To create an asymmetric RSA KMS key for encryption and decryption

This example creates a KMS key that contains an asymmetric RSA key pair for encryption and decryption. The key spec and key usage can't be changed after the key is created.

$result = $client->createKey([
    'KeySpec' => 'RSA_4096', // Describes the type of key material in the KMS key.
    'KeyUsage' => 'ENCRYPT_DECRYPT', // The cryptographic operations for which you can use the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'RSA_4096',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'RSAES_OAEP_SHA_1',
            'RSAES_OAEP_SHA_256',
        ],
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'RSA_4096',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
    ], // Detailed information about the KMS key that this operation creates.
]

Example 3: To create an asymmetric elliptic curve KMS key for signing and verification

This example creates a KMS key that contains an asymmetric elliptic curve (ECC) key pair for signing and verification. The key usage is required even though "SIGN_VERIFY" is the only valid value for ECC KMS keys. The key spec and key usage can't be changed after the key is created.

$result = $client->createKey([
    'KeySpec' => 'ECC_NIST_P521', // Describes the type of key material in the KMS key.
    'KeyUsage' => 'SIGN_VERIFY', // The cryptographic operations for which you can use the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'ECC_NIST_P521',
        'Description' => '',
        'Enabled' => 1,
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'ECC_NIST_P521',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'SIGN_VERIFY',
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
        'SigningAlgorithms' => [
            'ECDSA_SHA_512',
        ],
    ], // Detailed information about the KMS key that this operation creates.
]

Example 4: To create a multi-Region primary KMS key

This example creates a multi-Region primary symmetric encryption key. Because the default values for all parameters create a symmetric encryption key, only the MultiRegion parameter is required for this KMS key.

$result = $client->createKey([
    'MultiRegion' => 1, // Indicates whether the KMS key is a multi-Region (True) or regional (False) key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => 'mrk-1234abcd12ab34cd56ef12345678990ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'SYMMETRIC_DEFAULT',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => 1,
        'MultiRegionConfiguration' => [
            'MultiRegionKeyType' => 'PRIMARY',
            'PrimaryKey' => [
                'Arn' => 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef12345678990ab',
                'Region' => 'us-west-2',
            ],
            'ReplicaKeys' => [
            ],
        ],
        'Origin' => 'AWS_KMS',
    ], // Detailed information about the KMS key that this operation creates.
]

Example 5: To create a KMS key for imported key material

This example creates a KMS key with no key material. When the operation is complete, you can import your own key material into the KMS key. To create this KMS key, set the Origin parameter to EXTERNAL.

$result = $client->createKey([
    'Origin' => 'EXTERNAL', // The source of the key material for the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => ,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'SYMMETRIC_DEFAULT',
        'KeyState' => 'PendingImport',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => ,
        'Origin' => 'EXTERNAL',
    ], // Detailed information about the KMS key that this operation creates.
]

Example 6: To create a KMS key in a custom key store

This example creates a KMS key in the specified custom key store. The operation creates the KMS key and its metadata in AWS KMS and the key material in the AWS CloudHSM cluster associated with the custom key store. This example requires the Origin and CustomKeyStoreId parameters.

$result = $client->createKey([
    'CustomKeyStoreId' => 'cks-1234567890abcdef0', // Identifies the custom key store that hosts the KMS key.
    'Origin' => 'AWS_CLOUDHSM', // Indicates the source of the key material for the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CloudHsmClusterId' => 'cluster-1a23b4cdefg',
        'CreationDate' => ,
        'CustomKeyStoreId' => 'cks-1234567890abcdef0',
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'SYMMETRIC_DEFAULT',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => ,
        'Origin' => 'AWS_CLOUDHSM',
    ], // Detailed information about the KMS key that this operation creates.
]

Example 7: To create an HMAC KMS key

This example creates a 384-bit symmetric HMAC KMS key. The GENERATE_VERIFY_MAC key usage value is required even though it's the only valid value for HMAC KMS keys. The key spec and key usage can't be changed after the key is created.

$result = $client->createKey([
    'KeySpec' => 'HMAC_384', // Describes the type of key material in the KMS key.
    'KeyUsage' => 'GENERATE_VERIFY_MAC', // The cryptographic operations for which you can use the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'HMAC_384',
        'Description' => '',
        'Enabled' => 1,
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'HMAC_384',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'GENERATE_VERIFY_MAC',
        'MacAlgorithms' => [
            'HMAC_SHA_384',
        ],
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
    ], // Detailed information about the KMS key that this operation creates.
]

Decrypt

$result = $client->decrypt([/* ... */]);
$promise = $client->decryptAsync([/* ... */]);

Parameter Syntax

$result = $client->decrypt([
    'CiphertextBlob' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED
    'EncryptionAlgorithm' => 'SYMMETRIC_DEFAULT|RSAES_OAEP_SHA_1|RSAES_OAEP_SHA_256',
    'EncryptionContext' => ['<string>', ...],
    'GrantTokens' => ['<string>', ...],
    'KeyId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'EncryptionAlgorithm' => 'SYMMETRIC_DEFAULT|RSAES_OAEP_SHA_1|RSAES_OAEP_SHA_256',
    'KeyId' => '<string>',
    'Plaintext' => <string || resource || Psr\Http\Message\StreamInterface>,
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• InvalidCiphertextException:

  From the Decrypt or ReEncrypt operation, the request was rejected because the specified ciphertext, or additional authenticated data incorporated into the ciphertext, such as the encryption context, is corrupted, missing, or otherwise invalid.

  From the ImportKeyMaterial operation, the request was rejected because KMS could not decrypt the encrypted (wrapped) key material.

• KeyUnavailableException:

  The request was rejected because the specified KMS key was not available. You can retry the request.

• IncorrectKeyException:

  The request was rejected because the specified KMS key cannot decrypt the data. The KeyId in a Decrypt request and the SourceKeyId in a ReEncrypt request must identify the same KMS key that was used to encrypt the ciphertext.

• InvalidKeyUsageException:

  The request was rejected for one of the following reasons:

  • The KeyUsage value of the KMS key is incompatible with the API operation.

  • The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

  For encrypting, decrypting, re-encrypting, and generating data keys, the KeyUsage must be ENCRYPT_DECRYPT. For signing and verifying messages, the KeyUsage must be SIGN_VERIFY. For generating and verifying message authentication codes (MACs), the KeyUsage must be GENERATE_VERIFY_MAC. To find the KeyUsage of a KMS key, use the DescribeKey operation.

  To find the encryption or signing algorithms supported for a particular KMS key, use the DescribeKey operation.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• InvalidGrantTokenException:

  The request was rejected because the specified grant token is not valid.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To decrypt data

The following example decrypts data that was encrypted with a KMS key.

$result = $client->decrypt([
    'CiphertextBlob' => <BLOB>, // The encrypted data (ciphertext).
    'KeyId' => 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // A key identifier for the KMS key to use to decrypt the data.
]);

Result syntax:

[
    'KeyId' => 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // The Amazon Resource Name (ARN) of the KMS key that was used to decrypt the data.
    'Plaintext' => <BLOB>, // The decrypted (plaintext) data.
]

DeleteAlias

$result = $client->deleteAlias([/* ... */]);
$promise = $client->deleteAliasAsync([/* ... */]);

Parameter Syntax

$result = $client->deleteAlias([
    'AliasName' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To delete an alias

The following example deletes the specified alias.

$result = $client->deleteAlias([
    'AliasName' => 'alias/ExampleAlias', // The alias to delete.
]);

DeleteCustomKeyStore

$result = $client->deleteCustomKeyStore([/* ... */]);
$promise = $client->deleteCustomKeyStoreAsync([/* ... */]);

Parameter Syntax

$result = $client->deleteCustomKeyStore([
    'CustomKeyStoreId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• CustomKeyStoreHasCMKsException:

  The request was rejected because the custom key store contains KMS keys. After verifying that you do not need to use the KMS keys, use the ScheduleKeyDeletion operation to delete the KMS keys. After they are deleted, you can delete the custom key store.

• CustomKeyStoreInvalidStateException:

  The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores operation.

  This exception is thrown under the following conditions:

  • You requested the CreateKey or GenerateRandom operation in a custom key store that is not connected. These operations are valid only when the custom key store ConnectionState is CONNECTED.

  • You requested the UpdateCustomKeyStore or DeleteCustomKeyStore operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED.

  • You requested the ConnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values.

• CustomKeyStoreNotFoundException:

  The request was rejected because KMS cannot find a custom key store with the specified key store name or ID.

• KMSInternalException:

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

Examples

Example 1: To delete a custom key store from AWS KMS

This example deletes a custom key store from AWS KMS. This operation does not delete the AWS CloudHSM cluster that was associated with the CloudHSM cluster. This operation doesn't return any data. To verify that the operation was successful, use the DescribeCustomKeyStores operation.

$result = $client->deleteCustomKeyStore([
    'CustomKeyStoreId' => 'cks-1234567890abcdef0', // The ID of the custom key store to be deleted.
]);

Result syntax:

[
]

DeleteImportedKeyMaterial

$result = $client->deleteImportedKeyMaterial([/* ... */]);
$promise = $client->deleteImportedKeyMaterialAsync([/* ... */]);

Parameter Syntax

$result = $client->deleteImportedKeyMaterial([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• InvalidArnException:

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

• UnsupportedOperationException:

  The request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To delete imported key material

The following example deletes the imported key material from the specified KMS key.

$result = $client->deleteImportedKeyMaterial([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key whose imported key material you are deleting. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

DescribeCustomKeyStores

$result = $client->describeCustomKeyStores([/* ... */]);
$promise = $client->describeCustomKeyStoresAsync([/* ... */]);

Parameter Syntax

$result = $client->describeCustomKeyStores([
    'CustomKeyStoreId' => '<string>',
    'CustomKeyStoreName' => '<string>',
    'Limit' => <integer>,
    'Marker' => '<string>',
]);

Parameter Details

Result Syntax

[
    'CustomKeyStores' => [
        [
            'CloudHsmClusterId' => '<string>',
            'ConnectionErrorCode' => 'INVALID_CREDENTIALS|CLUSTER_NOT_FOUND|NETWORK_ERRORS|INTERNAL_ERROR|INSUFFICIENT_CLOUDHSM_HSMS|USER_LOCKED_OUT|USER_NOT_FOUND|USER_LOGGED_IN|SUBNET_NOT_FOUND',
            'ConnectionState' => 'CONNECTED|CONNECTING|FAILED|DISCONNECTED|DISCONNECTING',
            'CreationDate' => <DateTime>,
            'CustomKeyStoreId' => '<string>',
            'CustomKeyStoreName' => '<string>',
            'TrustAnchorCertificate' => '<string>',
        ],
        // ...
    ],
    'NextMarker' => '<string>',
    'Truncated' => true || false,
]

Result Details

Errors

• CustomKeyStoreNotFoundException:

  The request was rejected because KMS cannot find a custom key store with the specified key store name or ID.

• InvalidMarkerException:

  The request was rejected because the marker that specifies where pagination should next begin is not valid.

• KMSInternalException:

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

Examples

Example 1: To get detailed information about custom key stores in the account and Region

This example gets detailed information about all AWS KMS custom key stores in an AWS account and Region. To get all key stores, do not enter a custom key store name or ID.

$result = $client->describeCustomKeyStores([
]);

Result syntax:

[
    'CustomKeyStores' => [
    ], // Details about each custom key store in the account and Region.
]

Example 2: To get detailed information about a custom key store associated with a CloudHSM cluster.

This example gets detailed information about a particular AWS KMS custom key store that is associate with an AWS CloudHSM cluster. To limit the output to a particular custom key store, provide the custom key store name or ID.

$result = $client->describeCustomKeyStores([
    'CustomKeyStoreName' => 'ExampleKeyStore', // The friendly name of the custom key store.
]);

Result syntax:

[
    'CustomKeyStores' => [
        [
            'CloudHsmClusterId' => 'cluster-1a23b4cdefg',
            'ConnectionState' => 'CONNECTED',
            'CreationDate' => ,
            'CustomKeyStoreId' => 'cks-1234567890abcdef0',
            'CustomKeyStoreName' => 'ExampleKeyStore',
            'TrustAnchorCertificate' => '',
        ],
    ], // Detailed information about the specified custom key store.
]

DescribeKey

$result = $client->describeKey([/* ... */]);
$promise = $client->describeKeyAsync([/* ... */]);

Parameter Syntax

$result = $client->describeKey([
    'GrantTokens' => ['<string>', ...],
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'KeyMetadata' => [
        'AWSAccountId' => '<string>',
        'Arn' => '<string>',
        'CloudHsmClusterId' => '<string>',
        'CreationDate' => <DateTime>,
        'CustomKeyStoreId' => '<string>',
        'CustomerMasterKeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
        'DeletionDate' => <DateTime>,
        'Description' => '<string>',
        'Enabled' => true || false,
        'EncryptionAlgorithms' => ['<string>', ...],
        'ExpirationModel' => 'KEY_MATERIAL_EXPIRES|KEY_MATERIAL_DOES_NOT_EXPIRE',
        'KeyId' => '<string>',
        'KeyManager' => 'AWS|CUSTOMER',
        'KeySpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1|SYMMETRIC_DEFAULT|HMAC_224|HMAC_256|HMAC_384|HMAC_512',
        'KeyState' => 'Creating|Enabled|Disabled|PendingDeletion|PendingImport|PendingReplicaDeletion|Unavailable|Updating',
        'KeyUsage' => 'SIGN_VERIFY|ENCRYPT_DECRYPT|GENERATE_VERIFY_MAC',
        'MacAlgorithms' => ['<string>', ...],
        'MultiRegion' => true || false,
        'MultiRegionConfiguration' => [
            'MultiRegionKeyType' => 'PRIMARY|REPLICA',
            'PrimaryKey' => [
                'Arn' => '<string>',
                'Region' => '<string>',
            ],
            'ReplicaKeys' => [
                [
                    'Arn' => '<string>',
                    'Region' => '<string>',
                ],
                // ...
            ],
        ],
        'Origin' => 'AWS_KMS|EXTERNAL|AWS_CLOUDHSM',
        'PendingDeletionWindowInDays' => <integer>,
        'SigningAlgorithms' => ['<string>', ...],
        'ValidTo' => <DateTime>,
    ],
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

Examples

Example 1: To get details about a KMS key

The following example gets metadata for a symmetric encryption KMS key.

$result = $client->describeKey([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // An identifier for the KMS key. You can use the key ID, key ARN, alias name, alias ARN of the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'SYMMETRIC_DEFAULT',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
    ], // An object that contains information about the specified KMS key.
]

Example 2: To get details about an RSA asymmetric KMS key

The following example gets metadata for an asymmetric RSA KMS key used for signing and verification.

$result = $client->describeKey([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // An identifier for the KMS key. You can use the key ID, key ARN, alias name, alias ARN of the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'RSA_2048',
        'Description' => '',
        'Enabled' => ,
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeySpec' => 'RSA_2048',
        'KeyState' => 'Disabled',
        'KeyUsage' => 'SIGN_VERIFY',
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
        'SigningAlgorithms' => [
            'RSASSA_PKCS1_V1_5_SHA_256',
            'RSASSA_PKCS1_V1_5_SHA_384',
            'RSASSA_PKCS1_V1_5_SHA_512',
            'RSASSA_PSS_SHA_256',
            'RSASSA_PSS_SHA_384',
            'RSASSA_PSS_SHA_512',
        ],
    ], // An object that contains information about the specified KMS key.
]

Example 3: To get details about a multi-Region key

The following example gets metadata for a multi-Region replica key. This multi-Region key is a symmetric encryption key. DescribeKey returns information about the primary key and all of its replicas.

$result = $client->describeKey([
    'KeyId' => 'arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab', // An identifier for the KMS key. You can use the key ID, key ARN, alias name, alias ARN of the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '111122223333',
        'Arn' => 'arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'SYMMETRIC_DEFAULT',
        'Description' => '',
        'Enabled' => 1,
        'EncryptionAlgorithms' => [
            'SYMMETRIC_DEFAULT',
        ],
        'KeyId' => 'mrk-1234abcd12ab34cd56ef1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'ENCRYPT_DECRYPT',
        'MultiRegion' => 1,
        'MultiRegionConfiguration' => [
            'MultiRegionKeyType' => 'PRIMARY',
            'PrimaryKey' => [
                'Arn' => 'arn:aws:kms:us-west-2:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab',
                'Region' => 'us-west-2',
            ],
            'ReplicaKeys' => [
                [
                    'Arn' => 'arn:aws:kms:eu-west-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab',
                    'Region' => 'eu-west-1',
                ],
                [
                    'Arn' => 'arn:aws:kms:ap-northeast-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab',
                    'Region' => 'ap-northeast-1',
                ],
                [
                    'Arn' => 'arn:aws:kms:sa-east-1:111122223333:key/mrk-1234abcd12ab34cd56ef1234567890ab',
                    'Region' => 'sa-east-1',
                ],
            ],
        ],
        'Origin' => 'AWS_KMS',
    ], // An object that contains information about the specified KMS key.
]

Example 4: To get details about an HMAC KMS key

The following example gets the metadata of an HMAC KMS key.

$result = $client->describeKey([
    'KeyId' => 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // An identifier for the KMS key. You can use the key ID, key ARN, alias name, alias ARN of the KMS key.
]);

Result syntax:

[
    'KeyMetadata' => [
        'AWSAccountId' => '123456789012',
        'Arn' => 'arn:aws:kms:us-west-2:123456789012:key/1234abcd-12ab-34cd-56ef-1234567890ab',
        'CreationDate' => ,
        'CustomerMasterKeySpec' => 'HMAC_256',
        'Description' => 'Development test key',
        'Enabled' => 1,
        'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab',
        'KeyManager' => 'CUSTOMER',
        'KeyState' => 'Enabled',
        'KeyUsage' => 'GENERATE_VERIFY_MAC',
        'MacAlgorithms' => [
            'HMAC_SHA_256',
        ],
        'MultiRegion' => ,
        'Origin' => 'AWS_KMS',
    ], // An object that contains information about the specified KMS key.
]

DisableKey

$result = $client->disableKey([/* ... */]);
$promise = $client->disableKeyAsync([/* ... */]);

Parameter Syntax

$result = $client->disableKey([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To disable a KMS key

The following example disables the specified KMS key.

$result = $client->disableKey([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key to disable. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

DisableKeyRotation

$result = $client->disableKeyRotation([/* ... */]);
$promise = $client->disableKeyRotationAsync([/* ... */]);

Parameter Syntax

$result = $client->disableKeyRotation([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

• UnsupportedOperationException:

  The request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation.

Examples

Example 1: To disable automatic rotation of key material

The following example disables automatic annual rotation of the key material for the specified KMS key.

$result = $client->disableKeyRotation([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key whose key material will no longer be rotated. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

DisconnectCustomKeyStore

$result = $client->disconnectCustomKeyStore([/* ... */]);
$promise = $client->disconnectCustomKeyStoreAsync([/* ... */]);

Parameter Syntax

$result = $client->disconnectCustomKeyStore([
    'CustomKeyStoreId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• CustomKeyStoreInvalidStateException:

  The request was rejected because of the ConnectionState of the custom key store. To get the ConnectionState of a custom key store, use the DescribeCustomKeyStores operation.

  This exception is thrown under the following conditions:

  • You requested the CreateKey or GenerateRandom operation in a custom key store that is not connected. These operations are valid only when the custom key store ConnectionState is CONNECTED.

  • You requested the UpdateCustomKeyStore or DeleteCustomKeyStore operation on a custom key store that is not disconnected. This operation is valid only when the custom key store ConnectionState is DISCONNECTED.

  • You requested the ConnectCustomKeyStore operation on a custom key store with a ConnectionState of DISCONNECTING or FAILED. This operation is valid for all other ConnectionState values.

• CustomKeyStoreNotFoundException:

  The request was rejected because KMS cannot find a custom key store with the specified key store name or ID.

• KMSInternalException:

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

Examples

Example 1: To disconnect a custom key store from its CloudHSM cluster

This example disconnects an AWS KMS custom key store from its AWS CloudHSM cluster. This operation doesn't return any data. To verify that the custom key store is disconnected, use the DescribeCustomKeyStores operation.

$result = $client->disconnectCustomKeyStore([
    'CustomKeyStoreId' => 'cks-1234567890abcdef0', // The ID of the custom key store.
]);

Result syntax:

[
]

EnableKey

$result = $client->enableKey([/* ... */]);
$promise = $client->enableKeyAsync([/* ... */]);

Parameter Syntax

$result = $client->enableKey([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

• LimitExceededException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To enable a KMS key

The following example enables the specified KMS key.

$result = $client->enableKey([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key to enable. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

EnableKeyRotation

$result = $client->enableKeyRotation([/* ... */]);
$promise = $client->enableKeyRotationAsync([/* ... */]);

Parameter Syntax

$result = $client->enableKeyRotation([
    'KeyId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• InvalidArnException:

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

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

• UnsupportedOperationException:

  The request was rejected because a specified parameter is not supported or a specified resource is not valid for this operation.

Examples

Example 1: To enable automatic rotation of key material

The following example enables automatic annual rotation of the key material for the specified KMS key.

$result = $client->enableKeyRotation([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key whose key material will be rotated annually. You can use the key ID or the Amazon Resource Name (ARN) of the KMS key.
]);

Encrypt

$result = $client->encrypt([/* ... */]);
$promise = $client->encryptAsync([/* ... */]);

Parameter Syntax

$result = $client->encrypt([
    'EncryptionAlgorithm' => 'SYMMETRIC_DEFAULT|RSAES_OAEP_SHA_1|RSAES_OAEP_SHA_256',
    'EncryptionContext' => ['<string>', ...],
    'GrantTokens' => ['<string>', ...],
    'KeyId' => '<string>', // REQUIRED
    'Plaintext' => <string || resource || Psr\Http\Message\StreamInterface>, // REQUIRED
]);

Parameter Details

Result Syntax

[
    'CiphertextBlob' => <string || resource || Psr\Http\Message\StreamInterface>,
    'EncryptionAlgorithm' => 'SYMMETRIC_DEFAULT|RSAES_OAEP_SHA_1|RSAES_OAEP_SHA_256',
    'KeyId' => '<string>',
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• KeyUnavailableException:

  The request was rejected because the specified KMS key was not available. You can retry the request.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• InvalidKeyUsageException:

  The request was rejected for one of the following reasons:

  • The KeyUsage value of the KMS key is incompatible with the API operation.

  • The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

  For encrypting, decrypting, re-encrypting, and generating data keys, the KeyUsage must be ENCRYPT_DECRYPT. For signing and verifying messages, the KeyUsage must be SIGN_VERIFY. For generating and verifying message authentication codes (MACs), the KeyUsage must be GENERATE_VERIFY_MAC. To find the KeyUsage of a KMS key, use the DescribeKey operation.

  To find the encryption or signing algorithms supported for a particular KMS key, use the DescribeKey operation.

• InvalidGrantTokenException:

  The request was rejected because the specified grant token is not valid.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To encrypt data

The following example encrypts data with the specified KMS key.

$result = $client->encrypt([
    'KeyId' => '1234abcd-12ab-34cd-56ef-1234567890ab', // The identifier of the KMS key to use for encryption. You can use the key ID or Amazon Resource Name (ARN) of the KMS key, or the name or ARN of an alias that refers to the KMS key.
    'Plaintext' => <BLOB>, // The data to encrypt.
]);

Result syntax:

[
    'CiphertextBlob' => <BLOB>, // The encrypted data (ciphertext).
    'KeyId' => 'arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // The ARN of the KMS key that was used to encrypt the data.
]

GenerateDataKey

$result = $client->generateDataKey([/* ... */]);
$promise = $client->generateDataKeyAsync([/* ... */]);

Parameter Syntax

$result = $client->generateDataKey([
    'EncryptionContext' => ['<string>', ...],
    'GrantTokens' => ['<string>', ...],
    'KeyId' => '<string>', // REQUIRED
    'KeySpec' => 'AES_256|AES_128',
    'NumberOfBytes' => <integer>,
]);

Parameter Details

Result Syntax

[
    'CiphertextBlob' => <string || resource || Psr\Http\Message\StreamInterface>,
    'KeyId' => '<string>',
    'Plaintext' => <string || resource || Psr\Http\Message\StreamInterface>,
]

Result Details

Errors

• NotFoundException:

  The request was rejected because the specified entity or resource could not be found.

• DisabledException:

  The request was rejected because the specified KMS key is not enabled.

• KeyUnavailableException:

  The request was rejected because the specified KMS key was not available. You can retry the request.

• DependencyTimeoutException:

  The system timed out while trying to fulfill the request. The request can be retried.

• InvalidKeyUsageException:

  The request was rejected for one of the following reasons:

  • The KeyUsage value of the KMS key is incompatible with the API operation.

  • The encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec).

  For encrypting, decrypting, re-encrypting, and generating data keys, the KeyUsage must be ENCRYPT_DECRYPT. For signing and verifying messages, the KeyUsage must be SIGN_VERIFY. For generating and verifying message authentication codes (MACs), the KeyUsage must be GENERATE_VERIFY_MAC. To find the KeyUsage of a KMS key, use the DescribeKey operation.

  To find the encryption or signing algorithms supported for a particular KMS key, use the DescribeKey operation.

• InvalidGrantTokenException:

  The request was rejected because the specified grant token is not valid.

• KMSInternalException:

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

• KMSInvalidStateException:

  The request was rejected because the state of the specified resource is not valid for this request.

  For more information about how key state affects the use of a KMS key, see Key states of KMS keys in the Key Management Service Developer Guide .

Examples

Example 1: To generate a data key

The following example generates a 256-bit symmetric data encryption key (data key) in two formats. One is the unencrypted (plainext) data key, and the other is the data key encrypted with the specified KMS key.

$result = $client->generateDataKey([
    'KeyId' => 'alias/ExampleAlias', // The identifier of the KMS key to use to encrypt the data key. You can use the key ID or Amazon Resource Name (ARN) of the KMS key, or the name or ARN of an alias that refers to the KMS key.
    'KeySpec' => 'AES_256', // Specifies the type of data key to return.
]);

Result syntax:

[
    'CiphertextBlob' => <BLOB>, // The encrypted data key.
    'KeyId' => 'arn:aws:kms:us-east-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab', // The ARN of the KMS key that was used to encrypt the data key.
    'Plaintext' => <BLOB>, // The unencrypted (plaintext) data key.
]

GenerateDataKeyPair

$result = $client->generateDataKeyPair([/* ... */]);
$promise = $client->generateDataKeyPairAsync([/* ... */]);

Parameter Syntax

$result = $client->generateDataKeyPair([
    'EncryptionContext' => ['<string>', ...],
    'GrantTokens' => ['<string>', ...],
    'KeyId' => '<string>', // REQUIRED
    'KeyPairSpec' => 'RSA_2048|RSA_3072|RSA_4096|ECC_NIST_P256|ECC_NIST_P384|ECC_NIST_P521|ECC_SECG_P256K1', // REQUIRED
]);

Parameter Details