/** * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. * SPDX-License-Identifier: Apache-2.0. */ #pragma once #include #include #include #include #include #include namespace Aws { namespace KMS { /** * Key Management Service

Key Management Service (KMS) is * an encryption and key management web service. This guide describes the KMS * operations that you can call programmatically. For general information about * KMS, see the * Key Management Service Developer Guide .

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

Amazon Web Services provides SDKs * that consist of libraries and sample code for various programming languages and * platforms (Java, Ruby, .Net, macOS, Android, etc.). The SDKs provide a * convenient way to create programmatic access to KMS and other Amazon Web * Services services. For example, the SDKs take care of tasks such as signing * requests (see below), managing errors, and retrying requests automatically. For * more information about the Amazon Web Services SDKs, including how to download * and install them, see Tools for Amazon * Web Services.

We recommend that you use the Amazon Web * Services SDKs to make programmatic API calls to KMS.

If you need to use * FIPS 140-2 validated cryptographic modules when communicating with Amazon Web * Services, use the FIPS endpoint in your preferred Amazon Web Services Region. * For more information about the available FIPS endpoints, see Service * endpoints in the Key Management Service topic of the Amazon Web Services * General Reference.

All KMS API calls must be signed and be * transmitted using Transport Layer Security (TLS). KMS recommends you always use * the latest supported TLS version. Clients must also support cipher suites with * Perfect Forward Secrecy (PFS) such as Ephemeral Diffie-Hellman (DHE) or Elliptic * Curve Ephemeral Diffie-Hellman (ECDHE). Most modern systems such as Java 7 and * later support these modes.

Signing Requests

Requests must * be signed using an access key ID and a secret access key. We strongly recommend * that you do not use your Amazon Web Services account root access key ID and * secret access key for everyday work. You can use the access key ID and secret * access key for an IAM user or you can use the Security Token Service (STS) to * generate temporary security credentials and use those to sign requests.

*

All KMS requests must be signed with Signature * Version 4.

Logging API Requests

KMS supports * CloudTrail, a service that logs Amazon Web Services API calls and related events * for your Amazon Web Services account and delivers them to an Amazon S3 bucket * that you specify. By using the information collected by CloudTrail, you can * determine what requests were made to KMS, who made the request, when it was * made, and so on. To learn more about CloudTrail, including how to turn it on and * find your log files, see the CloudTrail * User Guide.

Additional Resources

For more information * about credentials and request signing, see the following:

Commonly Used API Operations

Of the API operations * discussed in this guide, the following will prove the most useful for most * applications. You will likely perform operations other than these, such as * creating keys and assigning policies, by using the console.

*/ class AWS_KMS_API KMSClient : public Aws::Client::AWSJsonClient, public Aws::Client::ClientWithAsyncTemplateMethods { public: typedef Aws::Client::AWSJsonClient BASECLASS; static const char* SERVICE_NAME; static const char* ALLOCATION_TAG; typedef KMSClientConfiguration ClientConfigurationType; typedef KMSEndpointProvider EndpointProviderType; /** * Initializes client to use DefaultCredentialProviderChain, with default http client factory, and optional client config. If client config * is not specified, it will be initialized to default values. */ KMSClient(const Aws::KMS::KMSClientConfiguration& clientConfiguration = Aws::KMS::KMSClientConfiguration(), std::shared_ptr endpointProvider = Aws::MakeShared(ALLOCATION_TAG)); /** * Initializes client to use SimpleAWSCredentialsProvider, with default http client factory, and optional client config. If client config * is not specified, it will be initialized to default values. */ KMSClient(const Aws::Auth::AWSCredentials& credentials, std::shared_ptr endpointProvider = Aws::MakeShared(ALLOCATION_TAG), const Aws::KMS::KMSClientConfiguration& clientConfiguration = Aws::KMS::KMSClientConfiguration()); /** * Initializes client to use specified credentials provider with specified client config. If http client factory is not supplied, * the default http client factory will be used */ KMSClient(const std::shared_ptr& credentialsProvider, std::shared_ptr endpointProvider = Aws::MakeShared(ALLOCATION_TAG), const Aws::KMS::KMSClientConfiguration& clientConfiguration = Aws::KMS::KMSClientConfiguration()); /* Legacy constructors due deprecation */ /** * Initializes client to use DefaultCredentialProviderChain, with default http client factory, and optional client config. If client config * is not specified, it will be initialized to default values. */ KMSClient(const Aws::Client::ClientConfiguration& clientConfiguration); /** * Initializes client to use SimpleAWSCredentialsProvider, with default http client factory, and optional client config. If client config * is not specified, it will be initialized to default values. */ KMSClient(const Aws::Auth::AWSCredentials& credentials, const Aws::Client::ClientConfiguration& clientConfiguration); /** * Initializes client to use specified credentials provider with specified client config. If http client factory is not supplied, * the default http client factory will be used */ KMSClient(const std::shared_ptr& credentialsProvider, const Aws::Client::ClientConfiguration& clientConfiguration); /* End of legacy constructors due deprecation */ virtual ~KMSClient(); /** *

Cancels the deletion of a KMS key. When this operation succeeds, the key * state of the KMS key is Disabled. To enable the KMS key, use * EnableKey.

For more information about scheduling and canceling * deletion of a KMS key, see Deleting * KMS keys in the Key Management Service Developer Guide.

The * KMS key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:CancelKeyDeletion * (key policy)

Related operations: ScheduleKeyDeletion *

See Also:

AWS * API Reference

*/ virtual Model::CancelKeyDeletionOutcome CancelKeyDeletion(const Model::CancelKeyDeletionRequest& request) const; /** * A Callable wrapper for CancelKeyDeletion that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::CancelKeyDeletionOutcomeCallable CancelKeyDeletionCallable(const CancelKeyDeletionRequestT& request) const { return SubmitCallable(&KMSClient::CancelKeyDeletion, request); } /** * An Async wrapper for CancelKeyDeletion that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void CancelKeyDeletionAsync(const CancelKeyDeletionRequestT& request, const CancelKeyDeletionResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::CancelKeyDeletion, request, handler, context); } /** *

Connects or reconnects a custom * key store to its backing key store. For an CloudHSM key store, * ConnectCustomKeyStore connects the key store to its associated * CloudHSM cluster. For an external key store, ConnectCustomKeyStore * connects the key store to the external key store proxy that communicates with * your external key manager.

The custom key store must be connected before * you can create KMS keys in the key store or use the KMS keys it contains. You * can disconnect and reconnect a custom key store at any time.

The * connection process for a custom key store can take an extended amount of time to * complete. This operation starts the connection process, but it does not wait for * it to complete. When it succeeds, this operation quickly returns an HTTP 200 * response and a JSON object with no properties. However, this response does not * indicate that the custom key store is connected. To get the connection state of * the custom key store, use the DescribeCustomKeyStores operation.

* This operation is part of the custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

The ConnectCustomKeyStore operation might fail * for various reasons. To find the reason, use the DescribeCustomKeyStores * operation and see the ConnectionErrorCode in the response. For help * interpreting the ConnectionErrorCode, see * CustomKeyStoresListEntry.

To fix the failure, use the * DisconnectCustomKeyStore operation to disconnect the custom key store, * correct the error, use the UpdateCustomKeyStore operation if necessary, * and then use ConnectCustomKeyStore again.

CloudHSM key * store

During the connection process for an CloudHSM key store, KMS * finds the CloudHSM cluster that is associated with the custom key store, creates * the connection infrastructure, connects to the cluster, logs into the CloudHSM * client as the kmsuser CU, and rotates its password.

To * connect an CloudHSM key store, its associated CloudHSM cluster must have at * least one active HSM. To get the number of active HSMs in a cluster, use the DescribeClusters * operation. To add HSMs to the cluster, use the CreateHsm * operation. Also, the * kmsuser crypto user (CU) must not be logged into the cluster. * This prevents KMS from using this account to log in.

If you are having * trouble connecting or disconnecting a CloudHSM key store, see Troubleshooting * an CloudHSM key store in the Key Management Service Developer * Guide.

External key store

When you connect an * external key store that uses public endpoint connectivity, KMS tests its ability * to communicate with your external key manager by sending a request via the * external key store proxy.

When you connect to an external key store that * uses VPC endpoint service connectivity, KMS establishes the networking elements * that it needs to communicate with your external key manager via the external key * store proxy. This includes creating an interface endpoint to the VPC endpoint * service and a private hosted zone for traffic between KMS and the VPC endpoint * service.

To connect an external key store, KMS must be able to connect to * the external key store proxy, the external key store proxy must be able to * communicate with your external key manager, and the external key manager must be * available for cryptographic operations.

If you are having trouble * connecting or disconnecting an external key store, see Troubleshooting * an external key store in the Key Management Service Developer * Guide.

Cross-account use: No. You cannot perform this * operation on a custom key store in a different Amazon Web Services account.

*

Required permissions: kms:ConnectCustomKeyStore * (IAM policy)

Related operations

See Also:

AWS * API Reference

*/ virtual Model::ConnectCustomKeyStoreOutcome ConnectCustomKeyStore(const Model::ConnectCustomKeyStoreRequest& request) const; /** * A Callable wrapper for ConnectCustomKeyStore that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ConnectCustomKeyStoreOutcomeCallable ConnectCustomKeyStoreCallable(const ConnectCustomKeyStoreRequestT& request) const { return SubmitCallable(&KMSClient::ConnectCustomKeyStore, request); } /** * An Async wrapper for ConnectCustomKeyStore that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ConnectCustomKeyStoreAsync(const ConnectCustomKeyStoreRequestT& request, const ConnectCustomKeyStoreResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ConnectCustomKeyStore, request, handler, context); } /** *

Creates a friendly name for a KMS key.

Adding, deleting, or * updating an alias can allow or deny permission to the KMS key. For details, see * ABAC * for KMS in the Key Management Service Developer Guide.

*

You can use an alias to identify a KMS key in the KMS console, in the * DescribeKey operation and in cryptographic * operations, such as Encrypt and GenerateDataKey. You can also * change the KMS key that's associated with the alias (UpdateAlias) or * delete the alias (DeleteAlias) at any time. These operations don't affect * the underlying KMS key.

You can associate the alias with any customer * managed key in the same Amazon Web Services Region. Each alias is associated * with only one KMS key at a time, but a KMS key can have multiple aliases. A * valid KMS key is required. You can't create an alias without a KMS key.

*

The alias must be unique in the account and Region, but you can have aliases * with the same name in different Regions. For detailed information about aliases, * see Using * aliases in the Key Management Service Developer Guide.

This * operation does not return a response. To get the alias that you created, use the * ListAliases operation.

The KMS key that you use for this operation * must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on an alias * in a different Amazon Web Services account.

Required permissions *

For details, see Controlling * access to aliases in the Key Management Service Developer Guide.

*

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::CreateAliasOutcome CreateAlias(const Model::CreateAliasRequest& request) const; /** * A Callable wrapper for CreateAlias that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::CreateAliasOutcomeCallable CreateAliasCallable(const CreateAliasRequestT& request) const { return SubmitCallable(&KMSClient::CreateAlias, request); } /** * An Async wrapper for CreateAlias that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void CreateAliasAsync(const CreateAliasRequestT& request, const CreateAliasResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::CreateAlias, request, handler, context); } /** *

Creates a custom * key store backed by a key store that you own and manage. When you use a KMS * key in a custom key store for a cryptographic operation, the cryptographic * operation is actually performed in your key store using your keys. KMS supports * CloudHSM * key stores backed by an CloudHSM * cluster and external * key stores backed by an external key store proxy and external key manager * outside of Amazon Web Services.

This operation is part of the custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

Before you create the custom key store, the required elements * must be in place and operational. We recommend that you use the test tools that * KMS provides to verify the configuration your external key store proxy. For * details about the required elements and verification tests, see Assemble * the prerequisites (for CloudHSM key stores) or Assemble * the prerequisites (for external key stores) in the Key Management Service * Developer Guide.

To create a custom key store, use the following * parameters.

  • To create an CloudHSM key store, specify the * CustomKeyStoreName, CloudHsmClusterId, * KeyStorePassword, and TrustAnchorCertificate. The * CustomKeyStoreType parameter is optional for CloudHSM key stores. * If you include it, set it to the default value, AWS_CLOUDHSM. For * help with failures, see Troubleshooting * an CloudHSM key store in the Key Management Service Developer * Guide.

  • To create an external key store, specify the * CustomKeyStoreName and a CustomKeyStoreType of * EXTERNAL_KEY_STORE. Also, specify values for * XksProxyConnectivity, * XksProxyAuthenticationCredential, XksProxyUriEndpoint, * and XksProxyUriPath. If your XksProxyConnectivity * value is VPC_ENDPOINT_SERVICE, specify the * XksProxyVpcEndpointServiceName parameter. For help with failures, * see Troubleshooting * an external key store in the Key Management Service Developer * Guide.

For external key stores:

Some * external key managers provide a simpler method for creating an external key * store. For details, see your external key manager documentation.

When * creating an external key store in the KMS console, you can upload a JSON-based * proxy configuration file with the desired values. You cannot use a proxy * configuration with the CreateCustomKeyStore operation. However, you * can use the values in the file to help you determine the correct values for the * CreateCustomKeyStore parameters.

When the operation * completes successfully, it returns the ID of the new custom key store. Before * you can use your new custom key store, you need to use the * ConnectCustomKeyStore operation to connect a new CloudHSM key store to * its CloudHSM cluster, or to connect a new external key store to the external key * store proxy for your external key manager. Even if you are not going to use your * custom key store immediately, you might want to connect it to verify that all * settings are correct and then disconnect it until you are ready to use it.

*

For help with failures, see Troubleshooting * a custom key store in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a custom * key store in a different Amazon Web Services account.

Required * permissions: kms:CreateCustomKeyStore * (IAM policy).

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::CreateCustomKeyStoreOutcome CreateCustomKeyStore(const Model::CreateCustomKeyStoreRequest& request) const; /** * A Callable wrapper for CreateCustomKeyStore that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::CreateCustomKeyStoreOutcomeCallable CreateCustomKeyStoreCallable(const CreateCustomKeyStoreRequestT& request) const { return SubmitCallable(&KMSClient::CreateCustomKeyStore, request); } /** * An Async wrapper for CreateCustomKeyStore that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void CreateCustomKeyStoreAsync(const CreateCustomKeyStoreRequestT& request, const CreateCustomKeyStoreResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::CreateCustomKeyStore, request, handler, context); } /** *

Adds a grant to a KMS key.

A grant is a policy instrument that * allows Amazon Web Services principals to use KMS keys in cryptographic * operations. It also can allow them to view a KMS key (DescribeKey) and * create and manage grants. When authorizing access to a KMS key, grants are * considered along with key policies and IAM policies. Grants are often used for * temporary permissions because you can create one, use its permissions, and * delete it without changing your key policies or IAM policies.

For * detailed information about grants, including grant terminology, see Grants * in KMS in the Key Management Service Developer Guide . For * examples of working with grants in several programming languages, see Programming * grants.

The CreateGrant operation returns a * GrantToken and a GrantId.

  • When you * create, retire, or revoke a grant, there might be a brief delay, usually less * than five minutes, until the grant is available throughout KMS. This state is * known as eventual consistency. Once the grant has achieved eventual * consistency, the grantee principal can use the permissions in the grant without * identifying the grant.

    However, to use the permissions in the grant * immediately, use the GrantToken that CreateGrant * returns. For details, see Using * a grant token in the Key Management Service Developer Guide * .

  • The CreateGrant operation also returns a * GrantId. You can use the GrantId and a key identifier * to identify the grant in the RetireGrant and RevokeGrant * operations. To find the grant ID, use the ListGrants or * ListRetirableGrants operations.

The KMS key that you * use for this operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation on a KMS key in a * different Amazon Web Services account, specify the key ARN in the value of the * KeyId parameter.

Required permissions: kms:CreateGrant * (key policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::CreateGrantOutcome CreateGrant(const Model::CreateGrantRequest& request) const; /** * A Callable wrapper for CreateGrant that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::CreateGrantOutcomeCallable CreateGrantCallable(const CreateGrantRequestT& request) const { return SubmitCallable(&KMSClient::CreateGrant, request); } /** * An Async wrapper for CreateGrant that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void CreateGrantAsync(const CreateGrantRequestT& request, const CreateGrantResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::CreateGrant, request, handler, context); } /** *

Creates a unique customer managed KMS * key in your Amazon Web Services account and Region. You can use a KMS key in * cryptographic operations, such as encryption and signing. Some Amazon Web * Services services let you use KMS keys that you create and manage to protect * your service resources.

A KMS key is a logical representation of a * cryptographic key. In addition to the key material used in cryptographic * operations, a KMS key includes metadata, such as the key ID, key policy, * creation date, description, and key state. For details, see Managing * keys in the Key Management Service Developer Guide

Use the * parameters of CreateKey to specify the type of KMS key, the source * of its key material, its key policy, description, tags, and other * properties.

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

*

To create different types of KMS keys, use the following * guidance:

Symmetric encryption KMS key

By default, * CreateKey creates a symmetric encryption KMS key with key material * that KMS generates. This is the basic and most widely used type of KMS key, and * provides the best performance.

To create a symmetric encryption KMS key, * you don't need to specify any parameters. The default value for * KeySpec, SYMMETRIC_DEFAULT, the default value for * KeyUsage, ENCRYPT_DECRYPT, and the default value for * Origin, AWS_KMS, create a symmetric encryption KMS key * with KMS key material.

If you need a key for basic encryption and * decryption or you are creating a KMS key to protect your resources in an Amazon * Web Services service, create a symmetric encryption KMS key. The key material in * a symmetric encryption key never leaves KMS unencrypted. You can use a symmetric * encryption KMS key to encrypt and decrypt data up to 4,096 bytes, but they are * typically used to generate data keys and data keys pairs. For details, see * GenerateDataKey and GenerateDataKeyPair.

*
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.

Asymmetric KMS keys * contain an RSA key pair, Elliptic Curve (ECC) key pair, or an SM2 key pair * (China Regions only). The private key in an asymmetric KMS key never leaves KMS * unencrypted. However, you can use the GetPublicKey operation to download * the public key so it can be used outside of KMS. KMS keys with RSA or SM2 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 asymmetric KMS keys, see Asymmetric * KMS keys in the Key Management Service Developer Guide.

*
HMAC KMS key

To create an HMAC KMS key, set the * KeySpec parameter to a key spec value for HMAC KMS keys. Then set * the KeyUsage parameter to GENERATE_VERIFY_MAC. You * must set the key usage even though GENERATE_VERIFY_MAC is the only * valid key usage value for HMAC KMS keys. You can't change these properties after * the KMS key is created.

HMAC KMS keys are symmetric keys that never leave * KMS unencrypted. You can use HMAC keys to generate (GenerateMac) and * verify (VerifyMac) HMAC codes for messages up to 4096 bytes.

*
Multi-Region primary keys
Imported key material
*

To create a multi-Region primary key in the local Amazon Web Services * 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 different * Amazon Web Services Region, use the ReplicateKey operation. To change a * replica key to a primary key, and its primary key to a replica key, use the * UpdatePrimaryRegion operation.

You can create multi-Region KMS * keys for all supported KMS key types: symmetric encryption KMS keys, HMAC KMS * keys, asymmetric encryption KMS keys, and asymmetric signing KMS keys. You can * also create multi-Region keys with imported key material. However, you can't * create multi-Region keys in a custom key store.

This operation supports * multi-Region keys, an KMS feature that lets you create multiple * interoperable KMS keys in different Amazon Web Services 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 Amazon Web Services Region and * decrypt it in a different Amazon Web Services Region without re-encrypting the * data or making a cross-Region call. For more information about multi-Region * keys, see Multi-Region * keys in KMS in the Key Management Service Developer Guide.

*

To import your own key material into a KMS key, begin by * creating a KMS key with no key material. To do this, use the Origin * parameter of CreateKey with a value of EXTERNAL. Next, * use GetParametersForImport operation to get a public key and import * token. Use the wrapping public key to encrypt your key material. Then, use * ImportKeyMaterial with your import token to import the key material. For * step-by-step instructions, see Importing * Key Material in the Key Management Service Developer Guide * .

You can import key material into KMS keys of all supported KMS key * types: symmetric encryption KMS keys, HMAC KMS keys, asymmetric encryption KMS * keys, and asymmetric signing KMS keys. You can also create multi-Region keys * with imported key material. However, you can't import key material into a KMS * key in a custom key store.

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 operation. * For instructions, see Importing key material into multi-Region keys. For more information about * multi-Region keys, see Multi-Region * keys in KMS in the Key Management Service Developer Guide.

*

Custom key store

A custom * key store lets you protect your Amazon Web Services resources using keys in * a backing key store that you own and manage. When you request a cryptographic * operation with a KMS key in a custom key store, the operation is performed in * the backing key store using its cryptographic keys.

KMS supports CloudHSM * key stores backed by an CloudHSM cluster and external * key stores backed by an external key manager outside of Amazon Web Services. * When you create a KMS key in an CloudHSM key store, KMS generates an encryption * key in the CloudHSM cluster and associates it with the KMS key. When you create * a KMS key in an external key store, you specify an existing encryption key in * the external key manager.

Some external key managers provide a * simpler method for creating a KMS key in an external key store. For details, see * your external key manager documentation.

Before you create a KMS * key in a custom key store, the ConnectionState of the key store * must be CONNECTED. To connect the custom key store, use the * ConnectCustomKeyStore operation. To find the * ConnectionState, use the DescribeCustomKeyStores * operation.

To create a KMS key in a custom key store, use the * CustomKeyStoreId. Use the default KeySpec value, * SYMMETRIC_DEFAULT, and the default KeyUsage value, * ENCRYPT_DECRYPT to create a symmetric encryption key. No other key * type is supported in a custom key store.

To create a KMS key in an CloudHSM * key store, use the Origin parameter with a value of * AWS_CLOUDHSM. The CloudHSM cluster that is associated with the * custom key store must have at least two active HSMs in different Availability * Zones in the Amazon Web Services Region.

To create a KMS key in an external * key store, use the Origin parameter with a value of * EXTERNAL_KEY_STORE and an XksKeyId parameter that * identifies an existing external key.

Some external key managers * provide a simpler method for creating a KMS key in an external key store. For * details, see your external key manager documentation.

*

Cross-account use: No. You cannot use this operation to create a KMS * key in a different Amazon Web Services account.

Required * permissions: kms:CreateKey * (IAM policy). To use the Tags parameter, kms:TagResource * (IAM policy). For examples and information about related permissions, see Allow * a user to create KMS keys in the Key Management Service Developer * Guide.

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::CreateKeyOutcome CreateKey(const Model::CreateKeyRequest& request) const; /** * A Callable wrapper for CreateKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::CreateKeyOutcomeCallable CreateKeyCallable(const CreateKeyRequestT& request) const { return SubmitCallable(&KMSClient::CreateKey, request); } /** * An Async wrapper for CreateKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void CreateKeyAsync(const CreateKeyRequestT& request, const CreateKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::CreateKey, request, handler, context); } /** *

Decrypts ciphertext that was encrypted by a KMS key using any of the * following operations:

You can use this * operation to decrypt ciphertext that was encrypted under a symmetric encryption * KMS key or an asymmetric encryption KMS key. When the KMS key is asymmetric, you * must specify the KMS key and the encryption algorithm that was used to encrypt * the ciphertext. For information about asymmetric KMS keys, see Asymmetric * KMS keys in the Key Management Service Developer Guide.

The * Decrypt operation also decrypts ciphertext that was encrypted * outside of KMS by the public key in an KMS asymmetric KMS key. However, it * cannot decrypt symmetric ciphertext produced by other libraries, such as the Amazon * Web Services Encryption SDK or Amazon * S3 client-side encryption. These libraries return a ciphertext format that * is incompatible with KMS.

If the ciphertext was encrypted under a * symmetric encryption KMS key, the KeyId parameter is optional. KMS * can get this information from metadata that it adds to the symmetric ciphertext * blob. This feature adds durability to your implementation by ensuring that * authorized users can decrypt ciphertext decades after it was encrypted, even if * they've lost track of the key ID. However, specifying the KMS key is always * recommended as a best practice. When you use the KeyId parameter to * specify a KMS key, KMS only uses the KMS key you specify. If the ciphertext was * encrypted under a different KMS key, the Decrypt operation fails. * This practice ensures that you use the KMS key that you intend.

Whenever * possible, use key policies to give users permission to call the * Decrypt operation on a particular KMS key, instead of using * &IAM; policies. Otherwise, you might create an &IAM; policy that gives * the user Decrypt permission on all KMS keys. This user could * decrypt ciphertext that was encrypted by KMS keys in other accounts if the key * policy for the cross-account KMS key permits it. If you must use an IAM policy * for Decrypt permissions, limit the user to particular KMS keys or * particular trusted accounts. For details, see Best * practices for IAM policies in the Key Management Service Developer * Guide.

Decrypt also supports Amazon * Web Services Nitro Enclaves, which provide an isolated compute environment * in Amazon EC2. To call Decrypt for a Nitro enclave, use the Amazon * Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the * Recipient parameter to provide the attestation document for the * enclave. Instead of the plaintext data, the response includes the plaintext data * encrypted with the public key from the attestation document * (CiphertextForRecipient).For information about the interaction * between KMS and Amazon Web Services Nitro Enclaves, see How * Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service * Developer Guide..

The KMS key that you use for this operation must be * in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. If you use the KeyId parameter * to identify a KMS key in a different Amazon Web Services account, specify the * key ARN or the alias ARN of the KMS key.

Required permissions: kms:Decrypt * (key policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::DecryptOutcome Decrypt(const Model::DecryptRequest& request) const; /** * A Callable wrapper for Decrypt that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DecryptOutcomeCallable DecryptCallable(const DecryptRequestT& request) const { return SubmitCallable(&KMSClient::Decrypt, request); } /** * An Async wrapper for Decrypt that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DecryptAsync(const DecryptRequestT& request, const DecryptResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::Decrypt, request, handler, context); } /** *

Deletes the specified alias.

Adding, deleting, or updating an * alias can allow or deny permission to the KMS key. For details, see ABAC for * KMS in the Key Management Service Developer Guide.

*

Because an alias is not a property of a KMS key, you can delete and change * the aliases of a KMS key without affecting the KMS key. Also, aliases do not * appear in the response from the DescribeKey operation. To get the aliases * of all KMS keys, use the ListAliases operation.

Each KMS key can * have multiple aliases. To change the alias of a KMS key, use DeleteAlias * to delete the current alias and CreateAlias to create a new alias. To * associate an existing alias with a different KMS key, call * UpdateAlias.

Cross-account use: No. You cannot perform * this operation on an alias in a different Amazon Web Services account.

* Required permissions

For details, see Controlling * access to aliases in the Key Management Service Developer Guide.

*

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::DeleteAliasOutcome DeleteAlias(const Model::DeleteAliasRequest& request) const; /** * A Callable wrapper for DeleteAlias that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DeleteAliasOutcomeCallable DeleteAliasCallable(const DeleteAliasRequestT& request) const { return SubmitCallable(&KMSClient::DeleteAlias, request); } /** * An Async wrapper for DeleteAlias that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DeleteAliasAsync(const DeleteAliasRequestT& request, const DeleteAliasResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DeleteAlias, request, handler, context); } /** *

Deletes a custom * key store. This operation does not affect any backing elements of the custom * key store. It does not delete the CloudHSM cluster that is associated with an * CloudHSM key store, or affect any users or keys in the cluster. For an external * key store, it does not affect the external key store proxy, external key * manager, or any external keys.

This operation is part of the custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

The custom key store that you delete cannot contain any KMS * keys. Before deleting the key store, verify that you will never need to use * any of the KMS keys in the key store for any cryptographic * operations. Then, use ScheduleKeyDeletion to delete the KMS keys from * the key store. After the required waiting period expires and all KMS keys are * deleted from the custom key store, use DisconnectCustomKeyStore to * disconnect the key store from KMS. Then, you can delete the custom key * store.

For keys in an CloudHSM key store, the * ScheduleKeyDeletion operation makes a best effort to delete the key * material from the associated cluster. However, you might need to manually delete * the orphaned key material from the cluster and its backups. KMS never * creates, manages, or deletes cryptographic keys in the external key manager * associated with an external key store. You must manage them using your external * key manager tools.

Instead of deleting the custom key store, consider * using the DisconnectCustomKeyStore operation to disconnect the custom key * store from its backing key store. While the key store is disconnected, you * cannot create or use the KMS keys in the key store. But, you do not need to * delete KMS keys and you can reconnect a disconnected custom key store at any * time.

If the operation succeeds, it returns a JSON object with no * properties.

Cross-account use: No. You cannot perform this * operation on a custom key store in a different Amazon Web Services account.

*

Required permissions: kms:DeleteCustomKeyStore * (IAM policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::DeleteCustomKeyStoreOutcome DeleteCustomKeyStore(const Model::DeleteCustomKeyStoreRequest& request) const; /** * A Callable wrapper for DeleteCustomKeyStore that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DeleteCustomKeyStoreOutcomeCallable DeleteCustomKeyStoreCallable(const DeleteCustomKeyStoreRequestT& request) const { return SubmitCallable(&KMSClient::DeleteCustomKeyStore, request); } /** * An Async wrapper for DeleteCustomKeyStore that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DeleteCustomKeyStoreAsync(const DeleteCustomKeyStoreRequestT& request, const DeleteCustomKeyStoreResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DeleteCustomKeyStore, request, handler, context); } /** *

Deletes key material that was previously imported. This operation makes the * specified KMS key temporarily unusable. To restore the usability of the KMS key, * reimport the same key material. For more information about importing key * material into KMS, see Importing * Key Material in the Key Management Service Developer Guide.

*

When the specified KMS key is in the PendingDeletion state, this * operation does not change the KMS key's state. Otherwise, it changes the KMS * key's state to PendingImport.

The KMS key that you use for * this operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:DeleteImportedKeyMaterial * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::DeleteImportedKeyMaterialOutcome DeleteImportedKeyMaterial(const Model::DeleteImportedKeyMaterialRequest& request) const; /** * A Callable wrapper for DeleteImportedKeyMaterial that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DeleteImportedKeyMaterialOutcomeCallable DeleteImportedKeyMaterialCallable(const DeleteImportedKeyMaterialRequestT& request) const { return SubmitCallable(&KMSClient::DeleteImportedKeyMaterial, request); } /** * An Async wrapper for DeleteImportedKeyMaterial that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DeleteImportedKeyMaterialAsync(const DeleteImportedKeyMaterialRequestT& request, const DeleteImportedKeyMaterialResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DeleteImportedKeyMaterial, request, handler, context); } /** *

Gets information about custom * key stores in the account and Region.

This operation is part of the * custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

By default, this operation returns information about all * custom key stores in the account and Region. To get only information about a * particular custom key store, use either the CustomKeyStoreName or * CustomKeyStoreId parameter (but not both).

To determine * whether the custom key store is connected to its CloudHSM cluster or external * key store proxy, use the ConnectionState element in the response. * If an attempt to connect the custom key store failed, the * ConnectionState value is FAILED and the * ConnectionErrorCode element in the response indicates the cause of * the failure. For help interpreting the ConnectionErrorCode, see * CustomKeyStoresListEntry.

Custom key stores have a * DISCONNECTED connection state if the key store has never been * connected or you used the DisconnectCustomKeyStore operation to * disconnect it. Otherwise, the connection state is CONNECTED. If your custom key * store connection state is CONNECTED but you are having trouble * using it, verify that the backing store is active and available. For an CloudHSM * key store, verify that the associated CloudHSM cluster is active and contains * the minimum number of HSMs required for the operation, if any. For an external * key store, verify that the external key store proxy and its associated external * key manager are reachable and enabled.

For help repairing your CloudHSM * key store, see the Troubleshooting * CloudHSM key stores. For help repairing your external key store, see the Troubleshooting * external key stores. Both topics are in the Key Management Service * Developer Guide.

Cross-account use: No. You cannot perform * this operation on a custom key store in a different Amazon Web Services * account.

Required permissions: kms:DescribeCustomKeyStores * (IAM policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::DescribeCustomKeyStoresOutcome DescribeCustomKeyStores(const Model::DescribeCustomKeyStoresRequest& request) const; /** * A Callable wrapper for DescribeCustomKeyStores that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DescribeCustomKeyStoresOutcomeCallable DescribeCustomKeyStoresCallable(const DescribeCustomKeyStoresRequestT& request) const { return SubmitCallable(&KMSClient::DescribeCustomKeyStores, request); } /** * An Async wrapper for DescribeCustomKeyStores that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DescribeCustomKeyStoresAsync(const DescribeCustomKeyStoresRequestT& request, const DescribeCustomKeyStoresResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DescribeCustomKeyStores, request, handler, context); } /** *

Provides detailed information about a KMS key. You can run * DescribeKey on a customer * managed key or an Amazon * Web Services managed key.

This detailed information includes the key * ARN, creation date (and deletion date, if applicable), the key state, and the * origin and expiration date (if any) of the key material. It includes fields, * like KeySpec, that help you distinguish different types of KMS * keys. It also displays the key usage (encryption, signing, or generating and * verifying MACs) and the algorithms that the KMS key supports.

For multi-Region * keys, DescribeKey displays the primary key and all related * replica keys. For KMS keys in CloudHSM key stores, * it includes information about the key store, such as the key store ID and the * CloudHSM cluster ID. For KMS keys in external key stores, * it includes the custom key store ID and the ID of the external key.

* DescribeKey does not return the following information:

    *

  • Aliases associated with the KMS key. To get this information, use * ListAliases.

  • Whether automatic key rotation is enabled * on the KMS key. To get this information, use GetKeyRotationStatus. Also, * some key states prevent a KMS key from being automatically rotated. For details, * see How * Automatic Key Rotation Works in the Key Management Service Developer * Guide.

  • Tags on the KMS key. To get this information, use * ListResourceTags.

  • Key policies and grants on the KMS * key. To get this information, use GetKeyPolicy and ListGrants.

    *

In general, DescribeKey is a non-mutating operation. * It returns data about KMS keys, but doesn't change them. However, Amazon Web * Services services use DescribeKey to create Amazon * Web Services managed keys from a predefined Amazon Web Services alias * with no key ID.

Cross-account use: Yes. To perform this operation * with a KMS key in a different Amazon Web Services account, specify the key ARN * or alias ARN in the value of the KeyId parameter.

* Required permissions: kms:DescribeKey * (key policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::DescribeKeyOutcome DescribeKey(const Model::DescribeKeyRequest& request) const; /** * A Callable wrapper for DescribeKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DescribeKeyOutcomeCallable DescribeKeyCallable(const DescribeKeyRequestT& request) const { return SubmitCallable(&KMSClient::DescribeKey, request); } /** * An Async wrapper for DescribeKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DescribeKeyAsync(const DescribeKeyRequestT& request, const DescribeKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DescribeKey, request, handler, context); } /** *

Sets the state of a KMS key to disabled. This change temporarily prevents use * of the KMS key for cryptographic * operations.

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 * .

The KMS key that you use for this operation must be in a compatible * key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:DisableKey * (key policy)

Related operations: EnableKey

See * Also:

AWS API * Reference

*/ virtual Model::DisableKeyOutcome DisableKey(const Model::DisableKeyRequest& request) const; /** * A Callable wrapper for DisableKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DisableKeyOutcomeCallable DisableKeyCallable(const DisableKeyRequestT& request) const { return SubmitCallable(&KMSClient::DisableKey, request); } /** * An Async wrapper for DisableKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DisableKeyAsync(const DisableKeyRequestT& request, const DisableKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DisableKey, request, handler, context); } /** *

Disables automatic * rotation of the key material of the specified symmetric encryption KMS * key.

Automatic key rotation is supported only on symmetric encryption KMS * keys. You cannot enable automatic rotation of asymmetric * KMS keys, HMAC KMS * keys, KMS keys with imported * key material, or KMS keys in a custom * key store. To enable or disable automatic rotation of a set of related multi-Region * keys, set the property on the primary key.

You can enable * (EnableKeyRotation) and disable automatic rotation of the key material in * customer * managed KMS keys. Key material rotation of Amazon * Web Services managed KMS keys is not configurable. KMS always rotates the * key material for every year. Rotation of Amazon * Web Services owned KMS keys varies.

In May 2022, KMS changed * the rotation schedule for Amazon Web Services managed keys from every three * years to every year. For details, see EnableKeyRotation.

*

The KMS key that you use for this operation must be in a compatible key * state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:DisableKeyRotation * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::DisableKeyRotationOutcome DisableKeyRotation(const Model::DisableKeyRotationRequest& request) const; /** * A Callable wrapper for DisableKeyRotation that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DisableKeyRotationOutcomeCallable DisableKeyRotationCallable(const DisableKeyRotationRequestT& request) const { return SubmitCallable(&KMSClient::DisableKeyRotation, request); } /** * An Async wrapper for DisableKeyRotation that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DisableKeyRotationAsync(const DisableKeyRotationRequestT& request, const DisableKeyRotationResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DisableKeyRotation, request, handler, context); } /** *

Disconnects the custom * key store from its backing key store. This operation disconnects an CloudHSM * key store from its associated CloudHSM cluster or disconnects an external key * store from the external key store proxy that communicates with your external key * manager.

This operation is part of the custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

While a custom key store is disconnected, you can manage the * custom key store and its KMS keys, but you cannot create or use its KMS keys. * You can reconnect the custom key store at any time.

While a custom * key store is disconnected, all attempts to create KMS keys in the custom key * store or to use existing KMS keys in cryptographic * operations will fail. This action can prevent users from storing and * accessing sensitive data.

When you disconnect a custom key store, * its ConnectionState changes to Disconnected. To find * the connection state of a custom key store, use the * DescribeCustomKeyStores operation. To reconnect a custom key store, use * the ConnectCustomKeyStore operation.

If the operation succeeds, it * returns a JSON object with no properties.

Cross-account use: No. * You cannot perform this operation on a custom key store in a different Amazon * Web Services account.

Required permissions: kms:DisconnectCustomKeyStore * (IAM policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::DisconnectCustomKeyStoreOutcome DisconnectCustomKeyStore(const Model::DisconnectCustomKeyStoreRequest& request) const; /** * A Callable wrapper for DisconnectCustomKeyStore that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::DisconnectCustomKeyStoreOutcomeCallable DisconnectCustomKeyStoreCallable(const DisconnectCustomKeyStoreRequestT& request) const { return SubmitCallable(&KMSClient::DisconnectCustomKeyStore, request); } /** * An Async wrapper for DisconnectCustomKeyStore that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void DisconnectCustomKeyStoreAsync(const DisconnectCustomKeyStoreRequestT& request, const DisconnectCustomKeyStoreResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::DisconnectCustomKeyStore, request, handler, context); } /** *

Sets the key state of a KMS key to enabled. This allows you to use the KMS * key for cryptographic * operations.

The KMS key that you use for this operation must be in a * compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:EnableKey * (key policy)

Related operations: DisableKey

See * Also:

AWS API * Reference

*/ virtual Model::EnableKeyOutcome EnableKey(const Model::EnableKeyRequest& request) const; /** * A Callable wrapper for EnableKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::EnableKeyOutcomeCallable EnableKeyCallable(const EnableKeyRequestT& request) const { return SubmitCallable(&KMSClient::EnableKey, request); } /** * An Async wrapper for EnableKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void EnableKeyAsync(const EnableKeyRequestT& request, const EnableKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::EnableKey, request, handler, context); } /** *

Enables automatic * rotation of the key material of the specified symmetric encryption KMS key. *

When you enable automatic rotation of acustomer * managed KMS key, KMS rotates the key material of the KMS key one year * (approximately 365 days) from the enable date and every year thereafter. You can * monitor rotation of the key material for your KMS keys in CloudTrail and Amazon * CloudWatch. To disable rotation of the key material in a customer managed KMS * key, use the DisableKeyRotation operation.

Automatic key rotation * is supported only on symmetric * encryption KMS keys. You cannot enable automatic rotation of asymmetric * KMS keys, HMAC KMS * keys, KMS keys with imported * key material, or KMS keys in a custom * key store. To enable or disable automatic rotation of a set of related multi-Region * keys, set the property on the primary key.

You cannot enable or * disable automatic rotation Amazon * Web Services managed KMS keys. KMS always rotates the key material of Amazon * Web Services managed keys every year. Rotation of Amazon * Web Services owned KMS keys varies.

In May 2022, KMS changed * the rotation schedule for Amazon Web Services managed keys from every three * years (approximately 1,095 days) to every year (approximately 365 days).

*

New Amazon Web Services managed keys are automatically rotated one year after * they are created, and approximately every year thereafter.

Existing * Amazon Web Services managed keys are automatically rotated one year after their * most recent rotation, and every year thereafter.

The KMS key that * you use for this operation must be in a compatible key state. For details, see * Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:EnableKeyRotation * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::EnableKeyRotationOutcome EnableKeyRotation(const Model::EnableKeyRotationRequest& request) const; /** * A Callable wrapper for EnableKeyRotation that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::EnableKeyRotationOutcomeCallable EnableKeyRotationCallable(const EnableKeyRotationRequestT& request) const { return SubmitCallable(&KMSClient::EnableKeyRotation, request); } /** * An Async wrapper for EnableKeyRotation that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void EnableKeyRotationAsync(const EnableKeyRotationRequestT& request, const EnableKeyRotationResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::EnableKeyRotation, request, handler, context); } /** *

Encrypts plaintext of up to 4,096 bytes using a KMS key. You can use a * symmetric or asymmetric KMS key with a KeyUsage of * ENCRYPT_DECRYPT.

You can use this operation to encrypt small * amounts of arbitrary data, such as a personal identifier or database password, * or other sensitive information. You don't need to use the Encrypt * operation to encrypt a data key. The GenerateDataKey and * GenerateDataKeyPair operations return a plaintext data key and an * encrypted copy of that data key.

If you use a symmetric encryption KMS * key, you can use an encryption context to add additional security to your * encryption operation. If you specify an EncryptionContext when * encrypting data, you must specify the same encryption context (a case-sensitive * exact match) when decrypting the data. Otherwise, the request to decrypt fails * with an InvalidCiphertextException. For more information, see Encryption * Context in the Key Management Service Developer Guide.

If you * specify an asymmetric KMS key, you must also specify the encryption algorithm. * The algorithm must be compatible with the KMS key spec.

When * you use an asymmetric KMS key to encrypt or reencrypt data, be sure to record * the KMS key and encryption algorithm that you choose. You will be required to * provide the same KMS key and encryption algorithm when you decrypt the data. If * the KMS key and algorithm do not match the values used to encrypt the data, the * decrypt operation fails.

You are not required to supply the key ID and * encryption algorithm when you decrypt with symmetric encryption KMS keys because * KMS stores this information in the ciphertext blob. KMS cannot store metadata in * ciphertext generated with asymmetric keys. The standard format for asymmetric * key ciphertext does not include configurable fields.

The * maximum size of the data that you can encrypt varies with the type of KMS key * and the encryption algorithm that you choose.

  • Symmetric * encryption KMS keys

    • SYMMETRIC_DEFAULT: 4096 * bytes

  • RSA_2048

    • * RSAES_OAEP_SHA_1: 214 bytes

    • * RSAES_OAEP_SHA_256: 190 bytes

  • * RSA_3072

    • RSAES_OAEP_SHA_1: 342 * bytes

    • RSAES_OAEP_SHA_256: 318 bytes

      • *

  • RSA_4096

    • * RSAES_OAEP_SHA_1: 470 bytes

    • * RSAES_OAEP_SHA_256: 446 bytes

  • * SM2PKE: 1024 bytes (China Regions only)

The KMS * key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:Encrypt * (key policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::EncryptOutcome Encrypt(const Model::EncryptRequest& request) const; /** * A Callable wrapper for Encrypt that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::EncryptOutcomeCallable EncryptCallable(const EncryptRequestT& request) const { return SubmitCallable(&KMSClient::Encrypt, request); } /** * An Async wrapper for Encrypt that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void EncryptAsync(const EncryptRequestT& request, const EncryptResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::Encrypt, request, handler, context); } /** *

Returns a unique symmetric data key for use outside of KMS. This operation * returns a plaintext copy of the data key and a copy that is encrypted under a * symmetric encryption KMS key that you specify. The bytes in the plaintext key * are random; they are not related to the caller or the KMS key. You can use the * plaintext key to encrypt your data outside of KMS and store the encrypted data * key with the encrypted data.

To generate a data key, specify the * symmetric encryption KMS key that will be used to encrypt the data key. You * cannot use an asymmetric KMS key to encrypt data keys. To get the type of your * KMS key, use the DescribeKey operation.

You must also specify the * length of the data key. Use either the KeySpec or * NumberOfBytes parameters (but not both). For 128-bit and 256-bit * data keys, use the KeySpec parameter.

To generate a 128-bit * SM4 data key (China Regions only), specify a KeySpec value of * AES_128 or a NumberOfBytes value of 16. * The symmetric encryption key used in China Regions to encrypt your data key is * an SM4 encryption key.

To get only an encrypted copy of the data key, use * GenerateDataKeyWithoutPlaintext. To generate an asymmetric data key pair, * use the GenerateDataKeyPair or GenerateDataKeyPairWithoutPlaintext * operation. To get a cryptographically secure random byte string, use * GenerateRandom.

You can use an optional encryption context to add * additional security to the encryption operation. If you specify an * EncryptionContext, you must specify the same encryption context (a * case-sensitive exact match) when decrypting the encrypted data key. Otherwise, * the request to decrypt fails with an InvalidCiphertextException. * For more information, see Encryption * Context in the Key Management Service Developer Guide.

* GenerateDataKey also supports Amazon * Web Services Nitro Enclaves, which provide an isolated compute environment * in Amazon EC2. To call GenerateDataKey for an Amazon Web Services * Nitro enclave, use the Amazon * Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the * Recipient parameter to provide the attestation document for the * enclave. GenerateDataKey returns a copy of the data key encrypted * under the specified KMS key, as usual. But instead of a plaintext copy of the * data key, the response includes a copy of the data key encrypted under the * public key from the attestation document (CiphertextForRecipient). * For information about the interaction between KMS and Amazon Web Services Nitro * Enclaves, see How * Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service * Developer Guide..

The KMS key that you use for this operation must be * in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

How to use your data key

We recommend that you use the * following pattern to encrypt data locally in your application. You can write * your own code or use a client-side encryption library, such as the Amazon * Web Services Encryption SDK, the Amazon * DynamoDB Encryption Client, or Amazon * S3 client-side encryption to do these tasks for you.

To encrypt data * outside of KMS:

  1. Use the GenerateDataKey operation * to get a data key.

  2. Use the plaintext data key (in the * Plaintext field of the response) to encrypt your data outside of * KMS. Then erase the plaintext data key from memory.

  3. Store the * encrypted data key (in the CiphertextBlob field of the response) * with the encrypted data.

To decrypt data outside of KMS:

*

  1. Use the Decrypt operation to decrypt the encrypted data key. * The operation returns a plaintext copy of the data key.

  2. Use * the plaintext data key to decrypt data outside of KMS, then erase the plaintext * data key from memory.

Cross-account use: Yes. To * perform this operation with a KMS key in a different Amazon Web Services * account, specify the key ARN or alias ARN in the value of the KeyId * parameter.

Required permissions: kms:GenerateDataKey * (key policy)

Related operations:

See Also:

* AWS * API Reference

*/ virtual Model::GenerateDataKeyOutcome GenerateDataKey(const Model::GenerateDataKeyRequest& request) const; /** * A Callable wrapper for GenerateDataKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateDataKeyOutcomeCallable GenerateDataKeyCallable(const GenerateDataKeyRequestT& request) const { return SubmitCallable(&KMSClient::GenerateDataKey, request); } /** * An Async wrapper for GenerateDataKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateDataKeyAsync(const GenerateDataKeyRequestT& request, const GenerateDataKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateDataKey, request, handler, context); } /** *

Returns a unique asymmetric data key pair for use outside of KMS. This * operation returns a plaintext public key, a plaintext private key, and a copy of * the private key that is encrypted under the symmetric encryption KMS key you * specify. You can use the data key pair to perform asymmetric cryptography and * implement digital signatures outside of KMS. The bytes in the keys are random; * they not related to the caller or to the KMS key that is used to encrypt the * private key.

You can use the public key that * GenerateDataKeyPair returns to encrypt data or verify a signature * outside of KMS. Then, store the encrypted private key with the data. When you * are ready to decrypt data or sign a message, you can use the Decrypt * operation to decrypt the encrypted private key.

To generate a data key * pair, you must specify a symmetric encryption KMS key to encrypt the private key * in a data key pair. You cannot use an asymmetric KMS key or a KMS key in a * custom key store. To get the type and origin of your KMS key, use the * DescribeKey operation.

Use the KeyPairSpec parameter * to choose an RSA or Elliptic Curve (ECC) data key pair. In China Regions, you * can also choose an SM2 data key pair. KMS recommends that you use ECC key pairs * for signing, and use RSA and SM2 key pairs for either encryption or signing, but * not both. However, KMS cannot enforce any restrictions on the use of data key * pairs outside of KMS.

If you are using the data key pair to encrypt data, * or for any operation where you don't immediately need a private key, consider * using the GenerateDataKeyPairWithoutPlaintext operation. * GenerateDataKeyPairWithoutPlaintext returns a plaintext public key * and an encrypted private key, but omits the plaintext private key that you need * only to decrypt ciphertext or sign a message. Later, when you need to decrypt * the data or sign a message, use the Decrypt operation to decrypt the * encrypted private key in the data key pair.

* GenerateDataKeyPair returns a unique data key pair for each * request. The bytes in the keys are random; they are not related to the caller or * the KMS key that is used to encrypt the private key. The public key is a * DER-encoded X.509 SubjectPublicKeyInfo, as specified in RFC 5280. The private key is a * DER-encoded PKCS8 PrivateKeyInfo, as specified in RFC 5958.

* GenerateDataKeyPair also supports Amazon * Web Services Nitro Enclaves, which provide an isolated compute environment * in Amazon EC2. To call GenerateDataKeyPair for an Amazon Web * Services Nitro enclave, use the Amazon * Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the * Recipient parameter to provide the attestation document for the * enclave. GenerateDataKeyPair returns the public data key and a copy * of the private data key encrypted under the specified KMS key, as usual. But * instead of a plaintext copy of the private data key * (PrivateKeyPlaintext), the response includes a copy of the private * data key encrypted under the public key from the attestation document * (CiphertextForRecipient). For information about the interaction * between KMS and Amazon Web Services Nitro Enclaves, see How * Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service * Developer Guide..

You can use an optional encryption context to add * additional security to the encryption operation. If you specify an * EncryptionContext, you must specify the same encryption context (a * case-sensitive exact match) when decrypting the encrypted data key. Otherwise, * the request to decrypt fails with an InvalidCiphertextException. * For more information, see Encryption * Context in the Key Management Service Developer Guide.

The KMS * key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:GenerateDataKeyPair * (key policy)

Related operations:

See Also:

* AWS * API Reference

*/ virtual Model::GenerateDataKeyPairOutcome GenerateDataKeyPair(const Model::GenerateDataKeyPairRequest& request) const; /** * A Callable wrapper for GenerateDataKeyPair that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateDataKeyPairOutcomeCallable GenerateDataKeyPairCallable(const GenerateDataKeyPairRequestT& request) const { return SubmitCallable(&KMSClient::GenerateDataKeyPair, request); } /** * An Async wrapper for GenerateDataKeyPair that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateDataKeyPairAsync(const GenerateDataKeyPairRequestT& request, const GenerateDataKeyPairResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateDataKeyPair, request, handler, context); } /** *

Returns a unique asymmetric data key pair for use outside of KMS. This * operation returns a plaintext public key and a copy of the private key that is * encrypted under the symmetric encryption KMS key you specify. Unlike * GenerateDataKeyPair, this operation does not return a plaintext private * key. The bytes in the keys are random; they are not related to the caller or to * the KMS key that is used to encrypt the private key.

You can use the * public key that GenerateDataKeyPairWithoutPlaintext returns to * encrypt data or verify a signature outside of KMS. Then, store the encrypted * private key with the data. When you are ready to decrypt data or sign a message, * you can use the Decrypt operation to decrypt the encrypted private * key.

To generate a data key pair, you must specify a symmetric encryption * KMS key to encrypt the private key in a data key pair. You cannot use an * asymmetric KMS key or a KMS key in a custom key store. To get the type and * origin of your KMS key, use the DescribeKey operation.

Use the * KeyPairSpec parameter to choose an RSA or Elliptic Curve (ECC) data * key pair. In China Regions, you can also choose an SM2 data key pair. KMS * recommends that you use ECC key pairs for signing, and use RSA and SM2 key pairs * for either encryption or signing, but not both. However, KMS cannot enforce any * restrictions on the use of data key pairs outside of KMS.

* GenerateDataKeyPairWithoutPlaintext returns a unique data key pair * for each request. The bytes in the key are not related to the caller or KMS key * that is used to encrypt the private key. The public key is a DER-encoded X.509 * SubjectPublicKeyInfo, as specified in RFC 5280.

You can use an * optional encryption context to add additional security to the encryption * operation. If you specify an EncryptionContext, you must specify * the same encryption context (a case-sensitive exact match) when decrypting the * encrypted data key. Otherwise, the request to decrypt fails with an * InvalidCiphertextException. For more information, see Encryption * Context in the Key Management Service Developer Guide.

The KMS * key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:GenerateDataKeyPairWithoutPlaintext * (key policy)

Related operations:

See * Also:

AWS * API Reference

*/ virtual Model::GenerateDataKeyPairWithoutPlaintextOutcome GenerateDataKeyPairWithoutPlaintext(const Model::GenerateDataKeyPairWithoutPlaintextRequest& request) const; /** * A Callable wrapper for GenerateDataKeyPairWithoutPlaintext that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateDataKeyPairWithoutPlaintextOutcomeCallable GenerateDataKeyPairWithoutPlaintextCallable(const GenerateDataKeyPairWithoutPlaintextRequestT& request) const { return SubmitCallable(&KMSClient::GenerateDataKeyPairWithoutPlaintext, request); } /** * An Async wrapper for GenerateDataKeyPairWithoutPlaintext that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateDataKeyPairWithoutPlaintextAsync(const GenerateDataKeyPairWithoutPlaintextRequestT& request, const GenerateDataKeyPairWithoutPlaintextResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateDataKeyPairWithoutPlaintext, request, handler, context); } /** *

Returns a unique symmetric data key for use outside of KMS. This operation * returns a data key that is encrypted under a symmetric encryption KMS key that * you specify. The bytes in the key are random; they are not related to the caller * or to the KMS key.

GenerateDataKeyWithoutPlaintext is * identical to the GenerateDataKey operation except that it does not return * a plaintext copy of the data key.

This operation is useful for systems * that need to encrypt data at some point, but not immediately. When you need to * encrypt the data, you call the Decrypt operation on the encrypted copy of * the key.

It's also useful in distributed systems with different levels of * trust. For example, you might store encrypted data in containers. One component * of your system creates new containers and stores an encrypted data key with each * container. Then, a different component puts the data into the containers. That * component first decrypts the data key, uses the plaintext data key to encrypt * data, puts the encrypted data into the container, and then destroys the * plaintext data key. In this system, the component that creates the containers * never sees the plaintext data key.

To request an asymmetric data key * pair, use the GenerateDataKeyPair or * GenerateDataKeyPairWithoutPlaintext operations.

To generate a data * key, you must specify the symmetric encryption KMS key that is used to encrypt * the data key. You cannot use an asymmetric KMS key or a key in a custom key * store to generate a data key. To get the type of your KMS key, use the * DescribeKey operation.

You must also specify the length of the * data key. Use either the KeySpec or NumberOfBytes * parameters (but not both). For 128-bit and 256-bit data keys, use the * KeySpec parameter.

To generate an SM4 data key (China * Regions only), specify a KeySpec value of AES_128 or * NumberOfBytes value of 16. The symmetric encryption * key used in China Regions to encrypt your data key is an SM4 encryption key.

*

If the operation succeeds, you will find the encrypted copy of the data key * in the CiphertextBlob field.

You can use an optional * encryption context to add additional security to the encryption operation. If * you specify an EncryptionContext, you must specify the same * encryption context (a case-sensitive exact match) when decrypting the encrypted * data key. Otherwise, the request to decrypt fails with an * InvalidCiphertextException. For more information, see Encryption * Context in the Key Management Service Developer Guide.

The KMS * key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:GenerateDataKeyWithoutPlaintext * (key policy)

Related operations:

See * Also:

AWS * API Reference

*/ virtual Model::GenerateDataKeyWithoutPlaintextOutcome GenerateDataKeyWithoutPlaintext(const Model::GenerateDataKeyWithoutPlaintextRequest& request) const; /** * A Callable wrapper for GenerateDataKeyWithoutPlaintext that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateDataKeyWithoutPlaintextOutcomeCallable GenerateDataKeyWithoutPlaintextCallable(const GenerateDataKeyWithoutPlaintextRequestT& request) const { return SubmitCallable(&KMSClient::GenerateDataKeyWithoutPlaintext, request); } /** * An Async wrapper for GenerateDataKeyWithoutPlaintext that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateDataKeyWithoutPlaintextAsync(const GenerateDataKeyWithoutPlaintextRequestT& request, const GenerateDataKeyWithoutPlaintextResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateDataKeyWithoutPlaintext, request, handler, context); } /** *

Generates a hash-based message authentication code (HMAC) for a message using * an HMAC KMS key and a MAC algorithm that the key supports. HMAC KMS keys and the * HMAC algorithms that KMS uses conform to industry standards defined in RFC 2104.

You * can use value that GenerateMac returns in the VerifyMac operation to * demonstrate that the original message has not changed. Also, because a secret * key is used to create the hash, you can verify that the party that generated the * hash has the required secret key. You can also use the raw result to implement * HMAC-based algorithms such as key derivation functions. This operation is part * of KMS support for HMAC KMS keys. For details, see HMAC keys * in KMS in the Key Management Service Developer Guide .

*

Best practices recommend that you limit the time during which any * signing mechanism, including an HMAC, is effective. This deters an attack where * the actor uses a signed message to establish validity repeatedly or long after * the message is superseded. HMAC tags do not include a timestamp, but you can * include a timestamp in the token or message to help you detect when its time to * refresh the HMAC.

The KMS key that you use for this operation * must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:GenerateMac * (key policy)

Related operations: VerifyMac

See * Also:

AWS API * Reference

*/ virtual Model::GenerateMacOutcome GenerateMac(const Model::GenerateMacRequest& request) const; /** * A Callable wrapper for GenerateMac that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateMacOutcomeCallable GenerateMacCallable(const GenerateMacRequestT& request) const { return SubmitCallable(&KMSClient::GenerateMac, request); } /** * An Async wrapper for GenerateMac that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateMacAsync(const GenerateMacRequestT& request, const GenerateMacResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateMac, request, handler, context); } /** *

Returns a random byte string that is cryptographically secure.

You * must use the NumberOfBytes parameter to specify the length of the * random byte string. There is no default value for string length.

By * default, the random byte string is generated in KMS. To generate the byte string * in the CloudHSM cluster associated with an CloudHSM key store, use the * CustomKeyStoreId parameter.

GenerateRandom * also supports Amazon * Web Services Nitro Enclaves, which provide an isolated compute environment * in Amazon EC2. To call GenerateRandom for a Nitro enclave, use the * Amazon * Web Services Nitro Enclaves SDK or any Amazon Web Services SDK. Use the * Recipient parameter to provide the attestation document for the * enclave. Instead of plaintext bytes, the response includes the plaintext bytes * encrypted under the public key from the attestation document * (CiphertextForRecipient).For information about the interaction * between KMS and Amazon Web Services Nitro Enclaves, see How * Amazon Web Services Nitro Enclaves uses KMS in the Key Management Service * Developer Guide.

For more information about entropy and random number * generation, see Key * Management Service Cryptographic Details.

Cross-account use: * Not applicable. GenerateRandom does not use any account-specific * resources, such as KMS keys.

Required permissions: kms:GenerateRandom * (IAM policy)

See Also:

AWS * API Reference

*/ virtual Model::GenerateRandomOutcome GenerateRandom(const Model::GenerateRandomRequest& request) const; /** * A Callable wrapper for GenerateRandom that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GenerateRandomOutcomeCallable GenerateRandomCallable(const GenerateRandomRequestT& request) const { return SubmitCallable(&KMSClient::GenerateRandom, request); } /** * An Async wrapper for GenerateRandom that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GenerateRandomAsync(const GenerateRandomRequestT& request, const GenerateRandomResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GenerateRandom, request, handler, context); } /** *

Gets a key policy attached to the specified KMS key.

Cross-account * use: No. You cannot perform this operation on a KMS key in a different * Amazon Web Services account.

Required permissions: kms:GetKeyPolicy * (key policy)

Related operations: PutKeyPolicy *

See Also:

AWS * API Reference

*/ virtual Model::GetKeyPolicyOutcome GetKeyPolicy(const Model::GetKeyPolicyRequest& request) const; /** * A Callable wrapper for GetKeyPolicy that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GetKeyPolicyOutcomeCallable GetKeyPolicyCallable(const GetKeyPolicyRequestT& request) const { return SubmitCallable(&KMSClient::GetKeyPolicy, request); } /** * An Async wrapper for GetKeyPolicy that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GetKeyPolicyAsync(const GetKeyPolicyRequestT& request, const GetKeyPolicyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GetKeyPolicy, request, handler, context); } /** *

Gets a Boolean value that indicates whether automatic * rotation of the key material is enabled for the specified KMS key.

*

When you enable automatic rotation for customer * managed KMS keys, KMS rotates the key material of the KMS key one year * (approximately 365 days) from the enable date and every year thereafter. You can * monitor rotation of the key material for your KMS keys in CloudTrail and Amazon * CloudWatch.

Automatic key rotation is supported only on symmetric * encryption KMS keys. You cannot enable automatic rotation of asymmetric * KMS keys, HMAC KMS * keys, KMS keys with imported * key material, or KMS keys in a custom * key store. To enable or disable automatic rotation of a set of related multi-Region * keys, set the property on the primary key..

You can enable * (EnableKeyRotation) and disable automatic rotation * (DisableKeyRotation) of the key material in customer managed KMS keys. * Key material rotation of Amazon * Web Services managed KMS keys is not configurable. KMS always rotates the * key material in Amazon Web Services managed KMS keys every year. The key * rotation status for Amazon Web Services managed KMS keys is always * true.

In May 2022, KMS changed the rotation schedule * for Amazon Web Services managed keys from every three years to every year. For * details, see EnableKeyRotation.

The KMS key that you use * for this operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

  • Disabled: The key rotation status does not change when you disable * a KMS key. However, while the KMS key is disabled, KMS does not rotate the key * material. When you re-enable the KMS key, rotation resumes. If the key material * in the re-enabled KMS key hasn't been rotated in one year, KMS rotates it * immediately, and every year thereafter. If it's been less than a year since the * key material in the re-enabled KMS key was rotated, the KMS key resumes its * prior rotation schedule.

  • Pending deletion: While a KMS key is * pending deletion, its key rotation status is false and KMS does not * rotate the key material. If you cancel the deletion, the original key rotation * status returns to true.

Cross-account * use: Yes. To perform this operation on a KMS key in a different Amazon Web * Services account, specify the key ARN in the value of the KeyId * parameter.

Required permissions: kms:GetKeyRotationStatus * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::GetKeyRotationStatusOutcome GetKeyRotationStatus(const Model::GetKeyRotationStatusRequest& request) const; /** * A Callable wrapper for GetKeyRotationStatus that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GetKeyRotationStatusOutcomeCallable GetKeyRotationStatusCallable(const GetKeyRotationStatusRequestT& request) const { return SubmitCallable(&KMSClient::GetKeyRotationStatus, request); } /** * An Async wrapper for GetKeyRotationStatus that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GetKeyRotationStatusAsync(const GetKeyRotationStatusRequestT& request, const GetKeyRotationStatusResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GetKeyRotationStatus, request, handler, context); } /** *

Returns the public key and an import token you need to import or reimport key * material for a KMS key.

By default, KMS keys are created with key * material that KMS generates. This operation supports Importing * key material, an advanced feature that lets you generate and import the * cryptographic key material for a KMS key. For more information about importing * key material into KMS, see Importing * key material in the Key Management Service Developer Guide.

*

Before calling GetParametersForImport, use the CreateKey * operation with an Origin value of EXTERNAL to create a * KMS key with no key material. You can import key material for a symmetric * encryption KMS key, HMAC KMS key, asymmetric encryption KMS key, or asymmetric * signing KMS key. You can also import key material into a multi-Region * key of any supported type. However, you can't import key material into a KMS * key in a custom key * store. You can also use GetParametersForImport to get a public * key and import token to reimport * the original key material into a KMS key whose key material expired or was * deleted.

GetParametersForImport returns the items that you * need to import your key material.

  • The public key (or "wrapping * key") of an RSA key pair that KMS generates.

    You will use this public key * to encrypt ("wrap") your key material while it's in transit to KMS.

    • *

  • A import token that ensures that KMS can decrypt your key material and * associate it with the correct KMS key.

The public key and its * import token are permanently linked and must be used together. Each public key * and import token set is valid for 24 hours. The expiration date and time appear * in the ParametersValidTo field in the * GetParametersForImport response. You cannot use an expired public * key or import token in an ImportKeyMaterial request. If your key and * token expire, send another GetParametersForImport request.

* GetParametersForImport requires the following information:

    *

  • The key ID of the KMS key for which you are importing the key * material.

  • The key spec of the public key ("wrapping key") that * you will use to encrypt your key material during import.

  • The * wrapping algorithm that you will use with the public key to encrypt your key * material.

You can use the same or a different public key spec * and wrapping algorithm each time you import or reimport the same key material. *

The KMS key that you use for this operation must be in a compatible key * state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:GetParametersForImport * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::GetParametersForImportOutcome GetParametersForImport(const Model::GetParametersForImportRequest& request) const; /** * A Callable wrapper for GetParametersForImport that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GetParametersForImportOutcomeCallable GetParametersForImportCallable(const GetParametersForImportRequestT& request) const { return SubmitCallable(&KMSClient::GetParametersForImport, request); } /** * An Async wrapper for GetParametersForImport that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GetParametersForImportAsync(const GetParametersForImportRequestT& request, const GetParametersForImportResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GetParametersForImport, request, handler, context); } /** *

Returns the public key of an asymmetric KMS key. Unlike the private key of a * asymmetric KMS key, which never leaves KMS unencrypted, callers with * kms:GetPublicKey permission can download the public key of an * asymmetric KMS key. You can share the public key to allow others to encrypt * messages and verify signatures outside of KMS. For information about asymmetric * KMS keys, see Asymmetric * KMS keys in the Key Management Service Developer Guide.

You do * not need to download the public key. Instead, you can use the public key within * KMS by calling the Encrypt, ReEncrypt, or Verify operations * with the identifier of an asymmetric KMS key. When you use the public key within * KMS, you benefit from the authentication, authorization, and logging that are * part of every KMS operation. You also reduce of risk of encrypting data that * cannot be decrypted. These features are not effective outside of KMS.

To * help you use the public key safely outside of KMS, GetPublicKey * returns important information about the public key in the response, * including:

  • KeySpec: * The type of key material in the public key, such as RSA_4096 or * ECC_NIST_P521.

  • KeyUsage: * Whether the key is used for encryption or signing.

  • EncryptionAlgorithms * or SigningAlgorithms: * A list of the encryption algorithms or the signing algorithms for the key.

    *

Although KMS cannot enforce these restrictions on external * operations, it is crucial that you use this information to prevent the public * key from being used improperly. For example, you can prevent a public signing * key from being used encrypt data, or prevent a public key from being used with * an encryption algorithm that is not supported by KMS. You can also avoid errors, * such as using the wrong signing algorithm in a verification operation.

To * verify a signature outside of KMS with an SM2 public key (China Regions only), * you must specify the distinguishing ID. By default, KMS uses * 1234567812345678 as the distinguishing ID. For more information, * see Offline * verification with SM2 key pairs.

The KMS key that you use for this * operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:GetPublicKey * (key policy)

Related operations: CreateKey

See * Also:

AWS * API Reference

*/ virtual Model::GetPublicKeyOutcome GetPublicKey(const Model::GetPublicKeyRequest& request) const; /** * A Callable wrapper for GetPublicKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::GetPublicKeyOutcomeCallable GetPublicKeyCallable(const GetPublicKeyRequestT& request) const { return SubmitCallable(&KMSClient::GetPublicKey, request); } /** * An Async wrapper for GetPublicKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void GetPublicKeyAsync(const GetPublicKeyRequestT& request, const GetPublicKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::GetPublicKey, request, handler, context); } /** *

Imports or reimports key material into an existing KMS key that was created * without key material. ImportKeyMaterial also sets the expiration * model and expiration date of the imported key material.

By default, KMS * keys are created with key material that KMS generates. This operation supports * Importing * key material, an advanced feature that lets you generate and import the * cryptographic key material for a KMS key. For more information about importing * key material into KMS, see Importing * key material in the Key Management Service Developer Guide.

*

After you successfully import key material into a KMS key, you can reimport * the same key material into that KMS key, but you cannot import different key * material. You might reimport key material to replace key material that expired * or key material that you deleted. You might also reimport key material to change * the expiration model or expiration date of the key material. Before reimporting * key material, if necessary, call DeleteImportedKeyMaterial to delete the * current imported key material.

Each time you import key material into * KMS, you can determine whether (ExpirationModel) and when * (ValidTo) the key material expires. To change the expiration of * your key material, you must import it again, either by calling * ImportKeyMaterial or using the import * features of the KMS console.

Before calling * ImportKeyMaterial:

  • Create or identify a KMS key * with no key material. The KMS key must have an Origin value of * EXTERNAL, which indicates that the KMS key is designed for imported * key material.

    To create an new KMS key for imported key material, call * the CreateKey operation with an Origin value of * EXTERNAL. You can create a symmetric encryption KMS key, HMAC KMS * key, asymmetric encryption KMS key, or asymmetric signing KMS key. You can also * import key material into a multi-Region * key of any supported type. However, you can't import key material into a KMS * key in a custom key * store.

  • Use the DescribeKey operation to verify that * the KeyState of the KMS key is PendingImport, which * indicates that the KMS key has no key material.

    If you are reimporting * the same key material into an existing KMS key, you might need to call the * DeleteImportedKeyMaterial to delete its existing key material.

    • *

  • Call the GetParametersForImport operation to get a public key and * import token set for importing key material.

  • Use the public * key in the GetParametersForImport response to encrypt your key * material.

Then, in an ImportKeyMaterial * request, you submit your encrypted key material and import token. When calling * this operation, you must specify the following values:

  • The key * ID or key ARN of the KMS key to associate with the imported key material. Its * Origin must be EXTERNAL and its KeyState * must be PendingImport. You cannot perform this operation on a KMS * key in a custom key * store, or on a KMS key in a different Amazon Web Services account. To get * the Origin and KeyState of a KMS key, call * DescribeKey.

  • The encrypted key material.

    • *

  • The import token that GetParametersForImport returned. You must * use a public key and token from the same GetParametersForImport * response.

  • Whether the key material expires * (ExpirationModel) and, if so, when (ValidTo). For help * with this choice, see Setting * an expiration time in the Key Management Service Developer Guide.

    *

    If you set an expiration date, KMS deletes the key material from the KMS key * on the specified date, making the KMS key unusable. To use the KMS key in * cryptographic operations again, you must reimport the same key material. * However, you can delete and reimport the key material at any time, including * before the key material expires. Each time you reimport, you can eliminate or * reset the expiration time.

When this operation is successful, * the key state of the KMS key changes from PendingImport to * Enabled, and you can use the KMS key in cryptographic * operations.

If this operation fails, use the exception to help determine * the problem. If the error is related to the key material, the import token, or * wrapping key, use GetParametersForImport to get a new public key and * import token for the KMS key and repeat the import procedure. For help, see How * To Import Key Material in the Key Management Service Developer * Guide.

The KMS key that you use for this operation must be in a * compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:ImportKeyMaterial * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::ImportKeyMaterialOutcome ImportKeyMaterial(const Model::ImportKeyMaterialRequest& request) const; /** * A Callable wrapper for ImportKeyMaterial that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ImportKeyMaterialOutcomeCallable ImportKeyMaterialCallable(const ImportKeyMaterialRequestT& request) const { return SubmitCallable(&KMSClient::ImportKeyMaterial, request); } /** * An Async wrapper for ImportKeyMaterial that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ImportKeyMaterialAsync(const ImportKeyMaterialRequestT& request, const ImportKeyMaterialResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ImportKeyMaterial, request, handler, context); } /** *

Gets a list of aliases in the caller's Amazon Web Services account and * region. For more information about aliases, see CreateAlias.

By * default, the ListAliases operation returns all aliases in the * account and region. To get only the aliases associated with a particular KMS * key, use the KeyId parameter.

The ListAliases * response can include aliases that you created and associated with your customer * managed keys, and aliases that Amazon Web Services created and associated with * Amazon Web Services managed keys in your account. You can recognize Amazon Web * Services aliases because their names have the format * aws/<service-name>, such as aws/dynamodb.

*

The response might also include aliases that have no TargetKeyId * field. These are predefined aliases that Amazon Web Services has created but has * not yet associated with a KMS key. Aliases that Amazon Web Services creates in * your account, including predefined aliases, do not count against your KMS * aliases quota.

Cross-account use: No. * ListAliases does not return aliases in other Amazon Web Services * accounts.

Required permissions: kms:ListAliases * (IAM policy)

For details, see Controlling * access to aliases in the Key Management Service Developer Guide.

*

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::ListAliasesOutcome ListAliases(const Model::ListAliasesRequest& request) const; /** * A Callable wrapper for ListAliases that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListAliasesOutcomeCallable ListAliasesCallable(const ListAliasesRequestT& request) const { return SubmitCallable(&KMSClient::ListAliases, request); } /** * An Async wrapper for ListAliases that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListAliasesAsync(const ListAliasesRequestT& request, const ListAliasesResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListAliases, request, handler, context); } /** *

Gets a list of all grants for the specified KMS key.

You must specify * the KMS key in all requests. You can filter the grant list by grant ID or * grantee principal.

For detailed information about grants, including grant * terminology, see Grants * in KMS in the Key Management Service Developer Guide . For * examples of working with grants in several programming languages, see Programming * grants.

The GranteePrincipal field in the * ListGrants response usually contains the user or role designated as * the grantee principal in the grant. However, when the grantee principal in the * grant is an Amazon Web Services service, the GranteePrincipal field * contains the service * principal, which might represent several different grantee principals.

*

Cross-account use: Yes. To perform this operation on a KMS * key in a different Amazon Web Services account, specify the key ARN in the value * of the KeyId parameter.

Required permissions: kms:ListGrants * (key policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::ListGrantsOutcome ListGrants(const Model::ListGrantsRequest& request) const; /** * A Callable wrapper for ListGrants that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListGrantsOutcomeCallable ListGrantsCallable(const ListGrantsRequestT& request) const { return SubmitCallable(&KMSClient::ListGrants, request); } /** * An Async wrapper for ListGrants that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListGrantsAsync(const ListGrantsRequestT& request, const ListGrantsResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListGrants, request, handler, context); } /** *

Gets the names of the key policies that are attached to a KMS key. This * operation is designed to get policy names that you can use in a * GetKeyPolicy operation. However, the only valid policy name is * default.

Cross-account use: No. You cannot perform * this operation on a KMS key in a different Amazon Web Services account.

* Required permissions: kms:ListKeyPolicies * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::ListKeyPoliciesOutcome ListKeyPolicies(const Model::ListKeyPoliciesRequest& request) const; /** * A Callable wrapper for ListKeyPolicies that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListKeyPoliciesOutcomeCallable ListKeyPoliciesCallable(const ListKeyPoliciesRequestT& request) const { return SubmitCallable(&KMSClient::ListKeyPolicies, request); } /** * An Async wrapper for ListKeyPolicies that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListKeyPoliciesAsync(const ListKeyPoliciesRequestT& request, const ListKeyPoliciesResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListKeyPolicies, request, handler, context); } /** *

Gets a list of all KMS keys in the caller's Amazon Web Services account and * Region.

Cross-account use: No. You cannot perform this operation * on a KMS key in a different Amazon Web Services account.

Required * permissions: kms:ListKeys * (IAM policy)

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::ListKeysOutcome ListKeys(const Model::ListKeysRequest& request) const; /** * A Callable wrapper for ListKeys that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListKeysOutcomeCallable ListKeysCallable(const ListKeysRequestT& request) const { return SubmitCallable(&KMSClient::ListKeys, request); } /** * An Async wrapper for ListKeys that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListKeysAsync(const ListKeysRequestT& request, const ListKeysResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListKeys, request, handler, context); } /** *

Returns all tags on the specified KMS key.

For general information * about tags, including the format and syntax, see Tagging * Amazon Web Services resources in the Amazon Web Services General * Reference. For information about using tags in KMS, see Tagging * keys.

Cross-account use: No. You cannot perform this * operation on a KMS key in a different Amazon Web Services account.

* Required permissions: kms:ListResourceTags * (key policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::ListResourceTagsOutcome ListResourceTags(const Model::ListResourceTagsRequest& request) const; /** * A Callable wrapper for ListResourceTags that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListResourceTagsOutcomeCallable ListResourceTagsCallable(const ListResourceTagsRequestT& request) const { return SubmitCallable(&KMSClient::ListResourceTags, request); } /** * An Async wrapper for ListResourceTags that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListResourceTagsAsync(const ListResourceTagsRequestT& request, const ListResourceTagsResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListResourceTags, request, handler, context); } /** *

Returns information about all grants in the Amazon Web Services account and * Region that have the specified retiring principal.

You can specify any * principal in your Amazon Web Services account. The grants that are returned * include grants for KMS keys in your Amazon Web Services account and other Amazon * Web Services accounts. You might use this operation to determine which grants * you may retire. To retire a grant, use the RetireGrant operation.

*

For detailed information about grants, including grant terminology, see Grants * in KMS in the Key Management Service Developer Guide . For * examples of working with grants in several programming languages, see Programming * grants.

Cross-account use: You must specify a principal in * your Amazon Web Services account. However, this operation can return grants in * any Amazon Web Services account. You do not need * kms:ListRetirableGrants permission (or any other additional * permission) in any Amazon Web Services account other than your own.

* Required permissions: kms:ListRetirableGrants * (IAM policy) in your Amazon Web Services account.

Related * operations:

See Also:

AWS * API Reference

*/ virtual Model::ListRetirableGrantsOutcome ListRetirableGrants(const Model::ListRetirableGrantsRequest& request) const; /** * A Callable wrapper for ListRetirableGrants that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ListRetirableGrantsOutcomeCallable ListRetirableGrantsCallable(const ListRetirableGrantsRequestT& request) const { return SubmitCallable(&KMSClient::ListRetirableGrants, request); } /** * An Async wrapper for ListRetirableGrants that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ListRetirableGrantsAsync(const ListRetirableGrantsRequestT& request, const ListRetirableGrantsResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ListRetirableGrants, request, handler, context); } /** *

Attaches a key policy to the specified KMS key.

For more information * about key policies, see Key * Policies in the Key Management Service Developer Guide. For help * writing and formatting a JSON policy document, see the IAM * JSON Policy Reference in the Identity and Access Management User * Guide . For examples of adding a key policy in multiple programming * languages, see Setting * a key policy in the Key Management Service Developer Guide.

* Cross-account use: No. You cannot perform this operation on a KMS key in * a different Amazon Web Services account.

Required permissions: kms:PutKeyPolicy * (key policy)

Related operations: GetKeyPolicy *

See Also:

AWS * API Reference

*/ virtual Model::PutKeyPolicyOutcome PutKeyPolicy(const Model::PutKeyPolicyRequest& request) const; /** * A Callable wrapper for PutKeyPolicy that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::PutKeyPolicyOutcomeCallable PutKeyPolicyCallable(const PutKeyPolicyRequestT& request) const { return SubmitCallable(&KMSClient::PutKeyPolicy, request); } /** * An Async wrapper for PutKeyPolicy that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void PutKeyPolicyAsync(const PutKeyPolicyRequestT& request, const PutKeyPolicyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::PutKeyPolicy, request, handler, context); } /** *

Decrypts ciphertext and then reencrypts it entirely within KMS. You can use * this operation to change the KMS key under which data is encrypted, such as when * you manually * rotate a KMS key or change the KMS key that protects a ciphertext. You can * also use it to reencrypt ciphertext under the same KMS key, such as to change * the encryption * context of a ciphertext.

The ReEncrypt operation can * decrypt ciphertext that was encrypted by using a KMS key in an KMS operation, * such as Encrypt or GenerateDataKey. It can also decrypt ciphertext * that was encrypted by using the public key of an asymmetric * KMS key outside of KMS. However, it cannot decrypt ciphertext produced by * other libraries, such as the Amazon * Web Services Encryption SDK or Amazon * S3 client-side encryption. These libraries return a ciphertext format that * is incompatible with KMS.

When you use the ReEncrypt * operation, you need to provide information for the decrypt operation and the * subsequent encrypt operation.

  • If your ciphertext was encrypted * under an asymmetric KMS key, you must use the SourceKeyId parameter * to identify the KMS key that encrypted the ciphertext. You must also supply the * encryption algorithm that was used. This information is required to decrypt the * data.

  • If your ciphertext was encrypted under a symmetric * encryption KMS key, the SourceKeyId parameter is optional. KMS can * get this information from metadata that it adds to the symmetric ciphertext * blob. This feature adds durability to your implementation by ensuring that * authorized users can decrypt ciphertext decades after it was encrypted, even if * they've lost track of the key ID. However, specifying the source KMS key is * always recommended as a best practice. When you use the SourceKeyId * parameter to specify a KMS key, KMS uses only the KMS key you specify. If the * ciphertext was encrypted under a different KMS key, the ReEncrypt * operation fails. This practice ensures that you use the KMS key that you * intend.

  • To reencrypt the data, you must use the * DestinationKeyId parameter to specify the KMS key that re-encrypts * the data after it is decrypted. If the destination KMS key is an asymmetric KMS * key, you must also provide the encryption algorithm. The algorithm that you * choose must be compatible with the KMS key.

    When you use an * asymmetric KMS key to encrypt or reencrypt data, be sure to record the KMS key * and encryption algorithm that you choose. You will be required to provide the * same KMS key and encryption algorithm when you decrypt the data. If the KMS key * and algorithm do not match the values used to encrypt the data, the decrypt * operation fails.

    You are not required to supply the key ID and encryption * algorithm when you decrypt with symmetric encryption KMS keys because KMS stores * this information in the ciphertext blob. KMS cannot store metadata in ciphertext * generated with asymmetric keys. The standard format for asymmetric key * ciphertext does not include configurable fields.

*

The KMS key that you use for this operation must be in a compatible key * state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. The source KMS key and destination KMS key * can be in different Amazon Web Services accounts. Either or both KMS keys can be * in a different account than the caller. To specify a KMS key in a different * account, you must use its key ARN or alias ARN.

Required * permissions:

To permit * reencryption from or to a KMS key, include the "kms:ReEncrypt*" * permission in your key * policy. This permission is automatically included in the key policy when you * use the console to create a KMS key. But you must include it manually when you * create a KMS key programmatically or when you use the PutKeyPolicy * operation to set a key policy.

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::ReEncryptOutcome ReEncrypt(const Model::ReEncryptRequest& request) const; /** * A Callable wrapper for ReEncrypt that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ReEncryptOutcomeCallable ReEncryptCallable(const ReEncryptRequestT& request) const { return SubmitCallable(&KMSClient::ReEncrypt, request); } /** * An Async wrapper for ReEncrypt that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ReEncryptAsync(const ReEncryptRequestT& request, const ReEncryptResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ReEncrypt, request, handler, context); } /** *

Replicates a multi-Region key into the specified Region. This operation * creates a multi-Region replica key based on a multi-Region primary key in a * different Region of the same Amazon Web Services partition. You can create * multiple replicas of a primary key, but each must be in a different Region. To * create a multi-Region primary key, use the CreateKey operation.

*

This operation supports multi-Region keys, an KMS feature that lets * you create multiple interoperable KMS keys in different Amazon Web Services * 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 Amazon Web * Services Region and decrypt it in a different Amazon Web Services Region without * re-encrypting the data or making a cross-Region call. For more information about * multi-Region keys, see Multi-Region * keys in KMS in the Key Management Service Developer Guide.

A * replica key is a fully-functional KMS key that can be used independently * of its primary and peer replica keys. A primary key and its replica keys share * properties that make them interoperable. They have the same key * ID and key material. They also have the same key * spec, key * usage, key * material origin, and automatic * key rotation status. KMS automatically synchronizes these shared properties * among related multi-Region keys. All other properties of a replica key can * differ, including its key * policy, tags, * aliases, * and Key * states of KMS keys. KMS pricing and quotas for KMS keys apply to each * primary key and replica key.

When this operation completes, the new * replica key has a transient key state of Creating. This key state * changes to Enabled (or PendingImport) after a few * seconds when the process of creating the new replica key is complete. While the * key state is Creating, you can manage key, but you cannot yet use * it in cryptographic operations. If you are creating and using the replica key * programmatically, retry on KMSInvalidStateException or call * DescribeKey to check its KeyState value before using * it. For details about the Creating key state, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

You cannot create more than one replica of a primary key in any Region. If * the Region already includes a replica of the key you're trying to replicate, * ReplicateKey returns an AlreadyExistsException error. * If the key state of the existing replica is PendingDeletion, you * can cancel the scheduled key deletion (CancelKeyDeletion) or wait for the * key to be deleted. The new replica key you create will have the same shared * properties as the original replica key.

The CloudTrail log of a * ReplicateKey operation records a ReplicateKey * operation in the primary key's Region and a CreateKey operation in the * replica key's Region.

If you replicate a multi-Region primary key with * imported key material, the replica key is created with no key material. You must * import the same key material that you imported into the primary key. For * details, see Importing key * material into multi-Region keys in the Key Management Service Developer * Guide.

To convert a replica key to a primary key, use the * UpdatePrimaryRegion operation.

ReplicateKey * uses different default values for the KeyPolicy and * Tags parameters than those used in the KMS console. For details, * see the parameter descriptions.

Cross-account use: No. * You cannot use this operation to create a replica key in a different Amazon Web * Services account.

Required permissions:

  • * kms:ReplicateKey on the primary key (in the primary key's Region). * Include this permission in the primary key's key policy.

  • * kms:CreateKey in an IAM policy in the replica Region.

    • *

  • To use the Tags parameter, kms:TagResource in * an IAM policy in the replica Region.

Related * operations

See Also:

AWS * API Reference

*/ virtual Model::ReplicateKeyOutcome ReplicateKey(const Model::ReplicateKeyRequest& request) const; /** * A Callable wrapper for ReplicateKey that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ReplicateKeyOutcomeCallable ReplicateKeyCallable(const ReplicateKeyRequestT& request) const { return SubmitCallable(&KMSClient::ReplicateKey, request); } /** * An Async wrapper for ReplicateKey that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ReplicateKeyAsync(const ReplicateKeyRequestT& request, const ReplicateKeyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ReplicateKey, request, handler, context); } /** *

Deletes a grant. Typically, you retire a grant when you no longer need its * permissions. To identify the grant to retire, use a grant * token, or both the grant ID and a key identifier (key ID or key ARN) of the * KMS key. The CreateGrant operation returns both values.

This * operation can be called by the retiring principal for a grant, by the * grantee principal if the grant allows the RetireGrant * operation, and by the Amazon Web Services account in which the grant is created. * It can also be called by principals to whom permission for retiring a grant is * delegated. For details, see Retiring * and revoking grants in the Key Management Service Developer * Guide.

For detailed information about grants, including grant * terminology, see Grants * in KMS in the Key Management Service Developer Guide . For * examples of working with grants in several programming languages, see Programming * grants.

Cross-account use: Yes. You can retire a grant on a * KMS key in a different Amazon Web Services account.

Required * permissions::Permission to retire a grant is determined primarily by the * grant. For details, see Retiring * and revoking grants in the Key Management Service Developer * Guide.

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::RetireGrantOutcome RetireGrant(const Model::RetireGrantRequest& request) const; /** * A Callable wrapper for RetireGrant that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::RetireGrantOutcomeCallable RetireGrantCallable(const RetireGrantRequestT& request) const { return SubmitCallable(&KMSClient::RetireGrant, request); } /** * An Async wrapper for RetireGrant that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void RetireGrantAsync(const RetireGrantRequestT& request, const RetireGrantResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::RetireGrant, request, handler, context); } /** *

Deletes the specified grant. You revoke a grant to terminate the permissions * that the grant allows. For more information, see Retiring * and revoking grants in the Key Management Service Developer Guide * .

When you create, retire, or revoke a grant, there might be a brief * delay, usually less than five minutes, until the grant is available throughout * KMS. This state is known as eventual consistency. For details, see Eventual * consistency in the Key Management Service Developer Guide . *

For detailed information about grants, including grant terminology, see * Grants * in KMS in the Key Management Service Developer Guide . For * examples of working with grants in several programming languages, see Programming * grants.

Cross-account use: Yes. To perform this operation on * a KMS key in a different Amazon Web Services account, specify the key ARN in the * value of the KeyId parameter.

Required permissions: * kms:RevokeGrant * (key policy).

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::RevokeGrantOutcome RevokeGrant(const Model::RevokeGrantRequest& request) const; /** * A Callable wrapper for RevokeGrant that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::RevokeGrantOutcomeCallable RevokeGrantCallable(const RevokeGrantRequestT& request) const { return SubmitCallable(&KMSClient::RevokeGrant, request); } /** * An Async wrapper for RevokeGrant that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void RevokeGrantAsync(const RevokeGrantRequestT& request, const RevokeGrantResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::RevokeGrant, request, handler, context); } /** *

Schedules the deletion of a KMS key. By default, KMS applies a waiting period * of 30 days, but you can specify a waiting period of 7-30 days. When this * operation is successful, the key state of the KMS key changes to * PendingDeletion and the key can't be used in any cryptographic * operations. It remains in this state for the duration of the waiting period. * Before the waiting period ends, you can use CancelKeyDeletion to cancel * the deletion of the KMS key. After the waiting period ends, KMS deletes the KMS * key, its key material, and all KMS data associated with it, including all * aliases that refer to it.

Deleting a KMS key is a destructive * and potentially dangerous operation. When a KMS key is deleted, all data that * was encrypted under the KMS key is unrecoverable. (The only exception is a multi-Region * replica key, or an asymmetric * or HMAC KMS key with imported key material.) To prevent the use of a KMS key * without deleting it, use DisableKey.

You can * schedule the deletion of a multi-Region primary key and its replica keys at any * time. However, KMS will not delete a multi-Region primary key with existing * replica keys. If you schedule the deletion of a primary key with replicas, its * key state changes to PendingReplicaDeletion and it cannot be * replicated or used in cryptographic operations. This status can continue * indefinitely. When the last of its replicas keys is deleted (not just * scheduled), the key state of the primary key changes to * PendingDeletion and its waiting period * (PendingWindowInDays) begins. For details, see Deleting * multi-Region keys in the Key Management Service Developer Guide.

*

When KMS deletes * a KMS key from an CloudHSM key store, it makes a best effort to delete the * associated key material from the associated CloudHSM cluster. However, you might * need to manually delete * the orphaned key material from the cluster and its backups. Deleting * a KMS key from an external key store has no effect on the associated * external key. However, for both types of custom key stores, deleting a KMS key * is destructive and irreversible. You cannot decrypt ciphertext encrypted under * the KMS key by using only its associated external key or CloudHSM key. Also, you * cannot recreate a KMS key in an external key store by creating a new KMS key * with the same key material.

For more information about scheduling a KMS * key for deletion, see Deleting * KMS keys in the Key Management Service Developer Guide.

The * KMS key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:ScheduleKeyDeletion (key policy)

Related operations

See Also:

AWS * API Reference

*/ virtual Model::ScheduleKeyDeletionOutcome ScheduleKeyDeletion(const Model::ScheduleKeyDeletionRequest& request) const; /** * A Callable wrapper for ScheduleKeyDeletion that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::ScheduleKeyDeletionOutcomeCallable ScheduleKeyDeletionCallable(const ScheduleKeyDeletionRequestT& request) const { return SubmitCallable(&KMSClient::ScheduleKeyDeletion, request); } /** * An Async wrapper for ScheduleKeyDeletion that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void ScheduleKeyDeletionAsync(const ScheduleKeyDeletionRequestT& request, const ScheduleKeyDeletionResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::ScheduleKeyDeletion, request, handler, context); } /** *

Creates a digital * signature for a message or message digest by using the private key in an * asymmetric signing KMS key. To verify the signature, use the Verify * operation, or use the public key in the same asymmetric KMS key outside of KMS. * For information about asymmetric KMS keys, see Asymmetric * KMS keys in the Key Management Service Developer Guide.

*

Digital signatures are generated and verified by using asymmetric key pair, * such as an RSA or ECC pair that is represented by an asymmetric KMS key. The key * owner (or an authorized user) uses their private key to sign a message. Anyone * with the public key can verify that the message was signed with that particular * private key and that the message hasn't changed since it was signed.

To * use the Sign operation, provide the following information:

    *

  • Use the KeyId parameter to identify an asymmetric KMS key * with a KeyUsage value of SIGN_VERIFY. To get the * KeyUsage value of a KMS key, use the DescribeKey operation. * The caller must have kms:Sign permission on the KMS key.

    • *

  • Use the Message parameter to specify the message or message * digest to sign. You can submit messages of up to 4096 bytes. To sign a larger * message, generate a hash digest of the message, and then provide the hash digest * in the Message parameter. To indicate whether the message is a full * message or a digest, use the MessageType parameter.

  • *

    Choose a signing algorithm that is compatible with the KMS key.

    • *

When signing a message, be sure to record the KMS key and * the signing algorithm. This information is required to verify the signature.

*

Best practices recommend that you limit the time during * which any signature is effective. This deters an attack where the actor uses a * signed message to establish validity repeatedly or long after the message is * superseded. Signatures do not include a timestamp, but you can include a * timestamp in the signed message to help you detect when its time to refresh the * signature.

To verify the signature that this operation * generates, use the Verify operation. Or use the GetPublicKey * operation to download the public key and then use the public key to verify the * signature outside of KMS.

The KMS key that you use for this operation * must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:Sign * (key policy)

Related operations: Verify

See * Also:

AWS API * Reference

*/ virtual Model::SignOutcome Sign(const Model::SignRequest& request) const; /** * A Callable wrapper for Sign that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::SignOutcomeCallable SignCallable(const SignRequestT& request) const { return SubmitCallable(&KMSClient::Sign, request); } /** * An Async wrapper for Sign that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void SignAsync(const SignRequestT& request, const SignResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::Sign, request, handler, context); } /** *

Adds or edits tags on a customer * managed key.

Tagging or untagging a KMS key can allow or deny * permission to the KMS key. For details, see ABAC for * KMS in the Key Management Service Developer Guide.

*

Each tag consists of a tag key and a tag value, both of which are * case-sensitive strings. The tag value can be an empty (null) string. To add a * tag, specify a new tag key and a tag value. To edit a tag, specify an existing * tag key and a new tag value.

You can use this operation to tag a customer * managed key, but you cannot tag an Amazon * Web Services managed key, an Amazon * Web Services owned key, a custom * key store, or an alias.

*

You can also add tags to a KMS key while creating it (CreateKey) or * replicating it (ReplicateKey).

For information about using tags in * KMS, see Tagging * keys. For general information about tags, including the format and syntax, * see Tagging * Amazon Web Services resources in the Amazon Web Services General * Reference.

The KMS key that you use for this operation must be in a * compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required * permissions: kms:TagResource * (key policy)

Related operations

See Also:

AWS API * Reference

*/ virtual Model::TagResourceOutcome TagResource(const Model::TagResourceRequest& request) const; /** * A Callable wrapper for TagResource that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::TagResourceOutcomeCallable TagResourceCallable(const TagResourceRequestT& request) const { return SubmitCallable(&KMSClient::TagResource, request); } /** * An Async wrapper for TagResource that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void TagResourceAsync(const TagResourceRequestT& request, const TagResourceResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::TagResource, request, handler, context); } /** *

Deletes tags from a customer * managed key. To delete a tag, specify the tag key and the KMS key.

*

Tagging or untagging a KMS key can allow or deny permission to the KMS * key. For details, see ABAC for * KMS in the Key Management Service Developer Guide.

*

When it succeeds, the UntagResource operation doesn't return any * output. Also, if the specified tag key isn't found on the KMS key, it doesn't * throw an exception or return a response. To confirm that the operation worked, * use the ListResourceTags operation.

For information about using * tags in KMS, see Tagging * keys. For general information about tags, including the format and syntax, * see Tagging * Amazon Web Services resources in the Amazon Web Services General * Reference.

The KMS key that you use for this operation must be in a * compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions: * kms:UntagResource * (key policy)

Related operations

See Also:

AWS * API Reference

*/ virtual Model::UntagResourceOutcome UntagResource(const Model::UntagResourceRequest& request) const; /** * A Callable wrapper for UntagResource that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::UntagResourceOutcomeCallable UntagResourceCallable(const UntagResourceRequestT& request) const { return SubmitCallable(&KMSClient::UntagResource, request); } /** * An Async wrapper for UntagResource that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void UntagResourceAsync(const UntagResourceRequestT& request, const UntagResourceResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::UntagResource, request, handler, context); } /** *

Associates an existing KMS alias with a different KMS key. Each alias is * associated with only one KMS key at a time, although a KMS key can have multiple * aliases. The alias and the KMS key must be in the same Amazon Web Services * account and Region.

Adding, deleting, or updating an alias can * allow or deny permission to the KMS key. For details, see ABAC for * KMS in the Key Management Service Developer Guide.

The * current and new KMS key must be the same type (both symmetric or both asymmetric * or both HMAC), and they must have the same key usage. This restriction prevents * errors in code that uses aliases. If you must assign an alias to a different * type of KMS key, use DeleteAlias to delete the old alias and * CreateAlias to create a new alias.

You cannot use * UpdateAlias to change an alias name. To change an alias name, use * DeleteAlias to delete the old alias and CreateAlias to create a * new alias.

Because an alias is not a property of a KMS key, you can * create, update, and delete the aliases of a KMS key without affecting the KMS * key. Also, aliases do not appear in the response from the DescribeKey * operation. To get the aliases of all KMS keys in the account, use the * ListAliases operation.

The KMS key that you use for this * operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required permissions *

For details, see Controlling * access to aliases in the Key Management Service Developer Guide.

*

Related operations:

See Also:

AWS API * Reference

*/ virtual Model::UpdateAliasOutcome UpdateAlias(const Model::UpdateAliasRequest& request) const; /** * A Callable wrapper for UpdateAlias that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::UpdateAliasOutcomeCallable UpdateAliasCallable(const UpdateAliasRequestT& request) const { return SubmitCallable(&KMSClient::UpdateAlias, request); } /** * An Async wrapper for UpdateAlias that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void UpdateAliasAsync(const UpdateAliasRequestT& request, const UpdateAliasResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::UpdateAlias, request, handler, context); } /** *

Changes the properties of a custom key store. You can use this operation to * change the properties of an CloudHSM key store or an external key store.

*

Use the required CustomKeyStoreId parameter to identify the * custom key store. Use the remaining optional parameters to change its * properties. This operation does not return any property values. To verify the * updated property values, use the DescribeCustomKeyStores operation.

*

This operation is part of the custom * key stores feature in KMS, which combines the convenience and extensive * integration of KMS with the isolation and control of a key store that you own * and manage.

When updating the properties of an external key * store, verify that the updated settings connect your key store, via the external * key store proxy, to the same external key manager as the previous settings, or * to a backup or snapshot of the external key manager with the same cryptographic * keys. If the updated connection settings fail, you can fix them and retry, * although an extended delay might disrupt Amazon Web Services services. However, * if KMS permanently loses its access to cryptographic keys, ciphertext encrypted * under those keys is unrecoverable.

For external key * stores:

Some external key managers provide a simpler method for updating * an external key store. For details, see your external key manager * documentation.

When updating an external key store in the KMS console, * you can upload a JSON-based proxy configuration file with the desired values. * You cannot upload the proxy configuration file to the * UpdateCustomKeyStore operation. However, you can use the file to * help you determine the correct values for the UpdateCustomKeyStore * parameters.

For an CloudHSM key store, you can use this operation * to change the custom key store friendly name * (NewCustomKeyStoreName), to tell KMS about a change to the * kmsuser crypto user password (KeyStorePassword), or to * associate the custom key store with a different, but related, CloudHSM cluster * (CloudHsmClusterId). To update any property of an CloudHSM key * store, the ConnectionState of the CloudHSM key store must be * DISCONNECTED.

For an external key store, you can use this * operation to change the custom key store friendly name * (NewCustomKeyStoreName), or to tell KMS about a change to the * external key store proxy authentication credentials * (XksProxyAuthenticationCredential), connection method * (XksProxyConnectivity), external proxy endpoint * (XksProxyUriEndpoint) and path (XksProxyUriPath). For * external key stores with an XksProxyConnectivity of * VPC_ENDPOINT_SERVICE, you can also update the Amazon VPC endpoint * service name (XksProxyVpcEndpointServiceName). To update most * properties of an external key store, the ConnectionState of the * external key store must be DISCONNECTED. However, you can update * the CustomKeyStoreName, * XksProxyAuthenticationCredential, and XksProxyUriPath * of an external key store when it is in the CONNECTED or DISCONNECTED state.

*

If your update requires a DISCONNECTED state, before using * UpdateCustomKeyStore, use the DisconnectCustomKeyStore * operation to disconnect the custom key store. After the * UpdateCustomKeyStore operation completes, use the * ConnectCustomKeyStore to reconnect the custom key store. To find the * ConnectionState of the custom key store, use the * DescribeCustomKeyStores operation.

Before updating the * custom key store, verify that the new values allow KMS to connect the custom key * store to its backing key store. For example, before you change the * XksProxyUriPath value, verify that the external key store proxy is * reachable at the new path.

If the operation succeeds, it returns a JSON * object with no properties.

Cross-account use: No. You cannot * perform this operation on a custom key store in a different Amazon Web Services * account.

Required permissions: kms:UpdateCustomKeyStore * (IAM policy)

Related operations:

See Also:

AWS * API Reference

*/ virtual Model::UpdateCustomKeyStoreOutcome UpdateCustomKeyStore(const Model::UpdateCustomKeyStoreRequest& request) const; /** * A Callable wrapper for UpdateCustomKeyStore that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::UpdateCustomKeyStoreOutcomeCallable UpdateCustomKeyStoreCallable(const UpdateCustomKeyStoreRequestT& request) const { return SubmitCallable(&KMSClient::UpdateCustomKeyStore, request); } /** * An Async wrapper for UpdateCustomKeyStore that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void UpdateCustomKeyStoreAsync(const UpdateCustomKeyStoreRequestT& request, const UpdateCustomKeyStoreResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::UpdateCustomKeyStore, request, handler, context); } /** *

Updates the description of a KMS key. To see the description of a KMS key, * use DescribeKey.

The KMS key that you use for this operation must * be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: No. You cannot perform this operation on a KMS key * in a different Amazon Web Services account.

Required * permissions: kms:UpdateKeyDescription * (key policy)

Related operations

See Also:

AWS * API Reference

*/ virtual Model::UpdateKeyDescriptionOutcome UpdateKeyDescription(const Model::UpdateKeyDescriptionRequest& request) const; /** * A Callable wrapper for UpdateKeyDescription that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::UpdateKeyDescriptionOutcomeCallable UpdateKeyDescriptionCallable(const UpdateKeyDescriptionRequestT& request) const { return SubmitCallable(&KMSClient::UpdateKeyDescription, request); } /** * An Async wrapper for UpdateKeyDescription that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void UpdateKeyDescriptionAsync(const UpdateKeyDescriptionRequestT& request, const UpdateKeyDescriptionResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::UpdateKeyDescription, request, handler, context); } /** *

Changes the primary key of a multi-Region key.

This operation changes * the replica key in the specified Region to a primary key and changes the former * primary key to a replica key. For example, suppose you have a primary key in * us-east-1 and a replica key in eu-west-2. If you run * UpdatePrimaryRegion with a PrimaryRegion value of * eu-west-2, the primary key is now the key in * eu-west-2, and the key in us-east-1 becomes a replica * key. For details, see Updating * the primary Region in the Key Management Service Developer Guide.

*

This operation supports multi-Region keys, an KMS feature that lets * you create multiple interoperable KMS keys in different Amazon Web Services * 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 Amazon Web * Services Region and decrypt it in a different Amazon Web Services Region without * re-encrypting the data or making a cross-Region call. For more information about * multi-Region keys, see Multi-Region * keys in KMS in the Key Management Service Developer Guide.

The * primary key of a multi-Region key is the source for properties that are * always shared by primary and replica keys, including the key material, key * ID, key * spec, key * usage, key * material origin, and automatic * key rotation. It's the only key that can be replicated. You cannot delete * the primary key until all replica keys are deleted.

The key ID and * primary Region that you specify uniquely identify the replica key that will * become the primary key. The primary Region must already have a replica key. This * operation does not create a KMS key in the specified Region. To find the replica * keys, use the DescribeKey operation on the primary key or any replica * key. To create a replica key, use the ReplicateKey operation.

You * can run this operation while using the affected multi-Region keys in * cryptographic operations. This operation should not delay, interrupt, or cause * failures in cryptographic operations.

Even after this operation * completes, the process of updating the primary Region might still be in progress * for a few more seconds. Operations such as DescribeKey might * display both the old and new primary keys as replicas. The old and new primary * keys have a transient key state of Updating. The original key state * is restored when the update is complete. While the key state is * Updating, you can use the keys in cryptographic operations, but you * cannot replicate the new primary key or perform certain management operations, * such as enabling or disabling these keys. For details about the * Updating key state, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

This operation does not return any output. To verify that primary key is * changed, use the DescribeKey operation.

Cross-account use: * No. You cannot use this operation in a different Amazon Web Services account. *

Required permissions:

  • * kms:UpdatePrimaryRegion on the current primary key (in the primary * key's Region). Include this permission primary key's key policy.

  • *

    kms:UpdatePrimaryRegion on the current replica key (in the * replica key's Region). Include this permission in the replica key's key * policy.

Related operations

See Also:

AWS * API Reference

*/ virtual Model::UpdatePrimaryRegionOutcome UpdatePrimaryRegion(const Model::UpdatePrimaryRegionRequest& request) const; /** * A Callable wrapper for UpdatePrimaryRegion that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::UpdatePrimaryRegionOutcomeCallable UpdatePrimaryRegionCallable(const UpdatePrimaryRegionRequestT& request) const { return SubmitCallable(&KMSClient::UpdatePrimaryRegion, request); } /** * An Async wrapper for UpdatePrimaryRegion that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void UpdatePrimaryRegionAsync(const UpdatePrimaryRegionRequestT& request, const UpdatePrimaryRegionResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::UpdatePrimaryRegion, request, handler, context); } /** *

Verifies a digital signature that was generated by the Sign operation. *

Verification confirms that an authorized user signed the message * with the specified KMS key and signing algorithm, and the message hasn't changed * since it was signed. If the signature is verified, the value of the * SignatureValid field in the response is True. If the * signature verification fails, the Verify operation fails with an * KMSInvalidSignatureException exception.

A digital signature * is generated by using the private key in an asymmetric KMS key. The signature is * verified by using the public key in the same asymmetric KMS key. For information * about asymmetric KMS keys, see Asymmetric * KMS keys in the Key Management Service Developer Guide.

To use * the Verify operation, specify the same asymmetric KMS key, message, * and signing algorithm that were used to produce the signature. The message type * does not need to be the same as the one used for signing, but it must indicate * whether the value of the Message parameter should be hashed as part * of the verification process.

You can also verify the digital signature by * using the public key of the KMS key outside of KMS. Use the GetPublicKey * operation to download the public key in the asymmetric KMS key and then use the * public key to verify the signature outside of KMS. The advantage of using the * Verify operation is that it is performed within KMS. As a result, * it's easy to call, the operation is performed within the FIPS boundary, it is * logged in CloudTrail, and you can use key policy and IAM policy to determine who * is authorized to use the KMS key to verify signatures.

To verify a * signature outside of KMS with an SM2 public key (China Regions only), you must * specify the distinguishing ID. By default, KMS uses * 1234567812345678 as the distinguishing ID. For more information, * see Offline * verification with SM2 key pairs.

The KMS key that you use for this * operation must be in a compatible key state. For details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:Verify * (key policy)

Related operations: Sign

See * Also:

AWS API * Reference

*/ virtual Model::VerifyOutcome Verify(const Model::VerifyRequest& request) const; /** * A Callable wrapper for Verify that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::VerifyOutcomeCallable VerifyCallable(const VerifyRequestT& request) const { return SubmitCallable(&KMSClient::Verify, request); } /** * An Async wrapper for Verify that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void VerifyAsync(const VerifyRequestT& request, const VerifyResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::Verify, request, handler, context); } /** *

Verifies the hash-based message authentication code (HMAC) for a specified * message, HMAC KMS key, and MAC algorithm. To verify the HMAC, * VerifyMac computes an HMAC using the message, HMAC KMS key, and MAC * algorithm that you specify, and compares the computed HMAC to the HMAC that you * specify. If the HMACs are identical, the verification succeeds; otherwise, it * fails. Verification indicates that the message hasn't changed since the HMAC was * calculated, and the specified key was used to generate and verify the HMAC.

*

HMAC KMS keys and the HMAC algorithms that KMS uses conform to industry * standards defined in RFC * 2104.

This operation is part of KMS support for HMAC KMS keys. For * details, see HMAC keys * in KMS in the Key Management Service Developer Guide.

The KMS * key that you use for this operation must be in a compatible key state. For * details, see Key * states of KMS keys in the Key Management Service Developer Guide.

*

Cross-account use: Yes. To perform this operation with a KMS key in a * different Amazon Web Services account, specify the key ARN or alias ARN in the * value of the KeyId parameter.

Required permissions: * kms:VerifyMac * (key policy)

Related operations: GenerateMac *

See Also:

AWS API * Reference

*/ virtual Model::VerifyMacOutcome VerifyMac(const Model::VerifyMacRequest& request) const; /** * A Callable wrapper for VerifyMac that returns a future to the operation so that it can be executed in parallel to other requests. */ template Model::VerifyMacOutcomeCallable VerifyMacCallable(const VerifyMacRequestT& request) const { return SubmitCallable(&KMSClient::VerifyMac, request); } /** * An Async wrapper for VerifyMac that queues the request into a thread executor and triggers associated callback when operation has finished. */ template void VerifyMacAsync(const VerifyMacRequestT& request, const VerifyMacResponseReceivedHandler& handler, const std::shared_ptr& context = nullptr) const { return SubmitAsync(&KMSClient::VerifyMac, request, handler, context); } void OverrideEndpoint(const Aws::String& endpoint); std::shared_ptr& accessEndpointProvider(); private: friend class Aws::Client::ClientWithAsyncTemplateMethods; void init(const KMSClientConfiguration& clientConfiguration); KMSClientConfiguration m_clientConfiguration; std::shared_ptr m_executor; std::shared_ptr m_endpointProvider; }; } // namespace KMS } // namespace Aws