import type { MetadataBearer as __MetadataBearer } from "@smithy/types"; import type { CreateKeyRequest, CreateKeyResponse } from "../models/models_0"; /** * @public */ export type { __MetadataBearer }; /** * @public * * The input for {@link CreateKeyCommand}. */ export interface CreateKeyCommandInput extends CreateKeyRequest { } /** * @public * * The output of {@link CreateKeyCommand}. */ export interface CreateKeyCommandOutput extends CreateKeyResponse, __MetadataBearer { } declare const CreateKeyCommand_base: { new (input: CreateKeyCommandInput): import("@smithy/core/client").CommandImpl; new (...[input]: [] | [CreateKeyCommandInput]): import("@smithy/core/client").CommandImpl; getEndpointParameterInstructions(): import("@smithy/types").EndpointParameterInstructions; }; /** *

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.

*

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 Key Management Service 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, ML-DSA * 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. Each KMS key can have only one key usage. KMS keys with RSA key pairs * can be used to encrypt and decrypt data or sign and verify messages (but not both). KMS * keys with NIST-standard ECC key pairs can be used to sign and verify messages or * derive shared secrets (but not both). KMS keys with ECC_SECG_P256K1 can be * used only to sign and verify messages. KMS keys with ML-DSA key pairs can be used to * sign and verify messages. KMS keys with SM2 key pairs (China Regions only) can be used * to either encrypt and decrypt data, sign and verify messages, or derive shared secrets * (you must choose one key usage type). 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
*
*

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.

*

*
*
Imported key material
*
*

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 step * 1. 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: *

* *

* Eventual consistency: The KMS API follows an eventual consistency model. * For more information, see KMS eventual consistency.

* @example * Use a bare-bones client and the command you need to make an API call. * ```javascript * import { KMSClient, CreateKeyCommand } from "@aws-sdk/client-kms"; // ES Modules import * // const { KMSClient, CreateKeyCommand } = require("@aws-sdk/client-kms"); // CommonJS import * // import type { KMSClientConfig } from "@aws-sdk/client-kms"; * const config = {}; // type is KMSClientConfig * const client = new KMSClient(config); * const input = { // CreateKeyRequest * Policy: "STRING_VALUE", * Description: "STRING_VALUE", * KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC" || "KEY_AGREEMENT" || "ENCAPSULATE_DECAPSULATE", * CustomerMasterKeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2", * KeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2" || "ML_DSA_44" || "ML_DSA_65" || "ML_DSA_87" || "ECC_NIST_EDWARDS25519" || "ML_KEM_512" || "ML_KEM_768" || "ML_KEM_1024", * Origin: "AWS_KMS" || "EXTERNAL" || "AWS_CLOUDHSM" || "EXTERNAL_KEY_STORE", * CustomKeyStoreId: "STRING_VALUE", * BypassPolicyLockoutSafetyCheck: true || false, * Tags: [ // TagList * { // Tag * TagKey: "STRING_VALUE", // required * TagValue: "STRING_VALUE", // required * }, * ], * MultiRegion: true || false, * XksKeyId: "STRING_VALUE", * }; * const command = new CreateKeyCommand(input); * const response = await client.send(command); * // { // CreateKeyResponse * // KeyMetadata: { // KeyMetadata * // AWSAccountId: "STRING_VALUE", * // KeyId: "STRING_VALUE", // required * // Arn: "STRING_VALUE", * // CreationDate: new Date("TIMESTAMP"), * // Enabled: true || false, * // Description: "STRING_VALUE", * // KeyUsage: "SIGN_VERIFY" || "ENCRYPT_DECRYPT" || "GENERATE_VERIFY_MAC" || "KEY_AGREEMENT" || "ENCAPSULATE_DECAPSULATE", * // KeyState: "Creating" || "Enabled" || "Disabled" || "PendingDeletion" || "PendingImport" || "PendingReplicaDeletion" || "Unavailable" || "Updating", * // DeletionDate: new Date("TIMESTAMP"), * // ValidTo: new Date("TIMESTAMP"), * // Origin: "AWS_KMS" || "EXTERNAL" || "AWS_CLOUDHSM" || "EXTERNAL_KEY_STORE", * // CustomKeyStoreId: "STRING_VALUE", * // CloudHsmClusterId: "STRING_VALUE", * // ExpirationModel: "KEY_MATERIAL_EXPIRES" || "KEY_MATERIAL_DOES_NOT_EXPIRE", * // KeyManager: "AWS" || "CUSTOMER", * // CustomerMasterKeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2", * // KeySpec: "RSA_2048" || "RSA_3072" || "RSA_4096" || "ECC_NIST_P256" || "ECC_NIST_P384" || "ECC_NIST_P521" || "ECC_SECG_P256K1" || "SYMMETRIC_DEFAULT" || "HMAC_224" || "HMAC_256" || "HMAC_384" || "HMAC_512" || "SM2" || "ML_DSA_44" || "ML_DSA_65" || "ML_DSA_87" || "ECC_NIST_EDWARDS25519" || "ML_KEM_512" || "ML_KEM_768" || "ML_KEM_1024", * // EncryptionAlgorithms: [ // EncryptionAlgorithmSpecList * // "SYMMETRIC_DEFAULT" || "RSAES_OAEP_SHA_1" || "RSAES_OAEP_SHA_256" || "SM2PKE", * // ], * // SigningAlgorithms: [ // SigningAlgorithmSpecList * // "RSASSA_PSS_SHA_256" || "RSASSA_PSS_SHA_384" || "RSASSA_PSS_SHA_512" || "RSASSA_PKCS1_V1_5_SHA_256" || "RSASSA_PKCS1_V1_5_SHA_384" || "RSASSA_PKCS1_V1_5_SHA_512" || "ECDSA_SHA_256" || "ECDSA_SHA_384" || "ECDSA_SHA_512" || "SM2DSA" || "ML_DSA_SHAKE_256" || "ED25519_SHA_512" || "ED25519_PH_SHA_512", * // ], * // KeyAgreementAlgorithms: [ // KeyAgreementAlgorithmSpecList * // "ECDH", * // ], * // EncapsulationAlgorithms: [ // EncapsulationAlgorithmSpecList * // "ML_KEM", * // ], * // MultiRegion: true || false, * // MultiRegionConfiguration: { // MultiRegionConfiguration * // MultiRegionKeyType: "PRIMARY" || "REPLICA", * // PrimaryKey: { // MultiRegionKey * // Arn: "STRING_VALUE", * // Region: "STRING_VALUE", * // }, * // ReplicaKeys: [ // MultiRegionKeyList * // { * // Arn: "STRING_VALUE", * // Region: "STRING_VALUE", * // }, * // ], * // }, * // PendingDeletionWindowInDays: Number("int"), * // MacAlgorithms: [ // MacAlgorithmSpecList * // "HMAC_SHA_224" || "HMAC_SHA_256" || "HMAC_SHA_384" || "HMAC_SHA_512", * // ], * // XksKeyConfiguration: { // XksKeyConfigurationType * // Id: "STRING_VALUE", * // }, * // CurrentKeyMaterialId: "STRING_VALUE", * // }, * // }; * * ``` * * @param CreateKeyCommandInput - {@link CreateKeyCommandInput} * @returns {@link CreateKeyCommandOutput} * @see {@link CreateKeyCommandInput} for command's `input` shape. * @see {@link CreateKeyCommandOutput} for command's `response` shape. * @see {@link KMSClientResolvedConfig | config} for KMSClient's `config` shape. * * @throws {@link CloudHsmClusterInvalidConfigurationException} (client fault) *

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

* *

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

* * @throws {@link CustomKeyStoreInvalidStateException} (client fault) *

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

*

This exception is thrown under the following conditions:

* * * @throws {@link CustomKeyStoreNotFoundException} (client fault) *

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

* * @throws {@link DependencyTimeoutException} (server fault) *

The system timed out while trying to fulfill the request. You can retry the * request.

* * @throws {@link InvalidArnException} (client fault) *

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

* * @throws {@link KMSInternalException} (server fault) *

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

* * @throws {@link LimitExceededException} (client fault) *

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

* * @throws {@link MalformedPolicyDocumentException} (client fault) *

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

* * @throws {@link TagException} (client fault) *

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

* * @throws {@link UnsupportedOperationException} (client fault) *

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

* * @throws {@link XksKeyAlreadyInUseException} (client fault) *

The request was rejected because the (XksKeyId) is already associated with * another KMS key in this external key store. Each KMS key in an external key store must be * associated with a different external key.

* * @throws {@link XksKeyInvalidConfigurationException} (client fault) *

The request was rejected because the external key specified by the XksKeyId * parameter did not meet the configuration requirements for an external key store.

*

The external key must be an AES-256 symmetric key that is enabled and performs encryption * and decryption.

* * @throws {@link XksKeyNotFoundException} (client fault) *

The request was rejected because the external key store proxy could not find the external * key. This exception is thrown when the value of the XksKeyId parameter doesn't * identify a key in the external key manager associated with the external key proxy.

*

Verify that the XksKeyId represents an existing key in the external key * manager. Use the key identifier that the external key store proxy uses to identify the key. * For details, see the documentation provided with your external key store proxy or key * manager.

* * @throws {@link KMSServiceException} *

Base exception class for all service exceptions from KMS service.

* * * @public */ export declare class CreateKeyCommand extends CreateKeyCommand_base { /** @internal type navigation helper, not in runtime. */ protected static __types: { api: { input: CreateKeyRequest; output: CreateKeyResponse; }; sdk: { input: CreateKeyCommandInput; output: CreateKeyCommandOutput; }; }; }