Creating keys
You can create Amazon KMS keys in the Amazon Web Services Management Console, or by using the CreateKey operation or an Amazon CloudFormation template. During this process, you pick the type of the KMS key, its regionality (single-Region or multi-Region), and the origin of the key material (by default, Amazon KMS creates the key material). You cannot change these properties after the KMS key is created. You also set the key policy for the KMS key, which you can change at any time.
This topic explains how to create the basic KMS key, a symmetric encryption KMS key for a single Region with key material from Amazon KMS. You can use this KMS key to protect your resources in an Amazon Web Service. For detailed information about symmetric encryption KMS keys, see SYMMETRIC_DEFAULT key spec. For help creating other types of keys, see Special-purpose keys.
If you are creating a KMS key to encrypt data you store or manage in an Amazon service,
create a symmetric encryption KMS key. Amazon services that
are integrated with Amazon KMS
Note
Symmetric KMS keys are now called symmetric encryption KMS keys. Amazon KMS supports two kinds of symmetric KMS keys, symmetric encryption KMS keys (the default type) and HMAC KMS keys, which are also symmetric keys.
When you create a KMS key in the Amazon KMS console, you are required to give it an alias
(friendly name). The CreateKey
operation does not create an alias for the new
KMS key. To create an alias for a new or existing KMS key, use the CreateAlias operation. For detailed
information about aliases in Amazon KMS, see Using aliases.
This topic explains how to create a symmetric encryption KMS key. Use the following table to find instructions for creating KMS keys of different types.
Instructions for creating a KMS key | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
KMS key type | Instructions | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Symmetric encryption key (SYMMETRIC_DEFAULT) | Creating symmetric encryption KMS keys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Asymmetric key | Creating asymmetric KMS keys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
HMAC key | Creating HMAC KMS keys | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Multi-Region key (of any type) | Creating a primary key with imported key material | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Imported key material ("Bring your own key — BYOK") | Importing key material step 1: Create an Amazon KMS key without key material | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Amazon CloudHSM key store | Creating KMS keys in an Amazon CloudHSM key store | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
External key store ("Hold your own key — HYOK") | Creating KMS keys in an external key store |
Learn more:
-
To create data keys for client-side encryption, use the GenerateDataKey operation.
-
To create an asymmetric KMS key for encryption or signing, see Creating asymmetric KMS keys.
-
To create an HMAC KMS key, see Creating HMAC KMS keys.
-
To create a KMS key with imported key material ("bring your own key"), see Importing key material step 1: Create an Amazon KMS key without key material.
-
To create a multi-Region primary key or replica key, see Creating multi-Region keys.
-
To create a KMS key in a custom key store (key material origin is Custom Key Store (CloudHSM)), see Creating KMS keys in an Amazon CloudHSM key store.
-
To use an Amazon CloudFormation template to create a KMS key, see AWS::KMS::Key in the Amazon CloudFormation User Guide.
-
To determine whether an existing KMS key is symmetric or asymmetric, see Identifying asymmetric KMS keys.
-
To use your KMS key programmatically and in command line interface operations, you need a key ID or key ARN. For detailed instructions, see Finding the key ID and key ARN.
-
For information about quotas that apply to KMS keys, see Quotas.
Permissions for creating KMS keys
To create a KMS key in the console or by using the APIs, you must have the following permission in an IAM policy. Whenever possible, use condition keys to limit the permissions. For example, you can use the kms:KeySpec condition key in an IAM policy to allow principals to create only symmetric encryption keys.
For an example of an IAM policy for principals who create keys, see Allow a user to create KMS keys.
Note
Be cautious when giving principals permission to manage tags and aliases. Changing a tag or alias can allow or deny permission to the customer managed key. For details, see ABAC for Amazon KMS.
-
kms:CreateKey is required.
-
kms:CreateAlias is required to create a KMS key in the console where an alias is required for every new KMS key.
-
kms:TagResource is required to add tags while creating the KMS key.
-
iam:CreateServiceLinkedRole is required to create multi-Region primary keys. For details, see Controlling access to multi-Region keys.
The kms:PutKeyPolicy permission is
not required to create the KMS key. The kms:CreateKey
permission includes
permission to set the initial key policy. But you must add this permission to the key policy
while creating the KMS key to ensure that you can control access to the KMS key. The
alternative is using the BypassLockoutSafetyCheck
KMS keys belong to the Amazon account in which they were created. The IAM user who
creates a KMS key is not considered to be the key owner and they don't automatically have
permission to use or manage the KMS key that they created. Like any other principal, the key
creator needs to get permission through a key policy, IAM policy, or grant. However,
principals who have the kms:CreateKey
permission can set the initial key policy
and give themselves permission to use or manage the key.
Creating symmetric encryption KMS keys
You can create KMS keys in the Amazon Web Services Management Console or by using the Amazon KMS API.
This topic explains how to create the basic KMS key, a symmetric encryption KMS key for a single Region with key material from Amazon KMS. You can use this KMS key to protect your resources in an Amazon Web Service. For help creating other types of keys, see Special-purpose keys.
Creating symmetric encryption KMS keys (console)
You can use the Amazon Web Services Management Console to create Amazon KMS keys (KMS keys).
Important
Do not include confidential or sensitive information in the alias, description, or tags. These fields may appear in plain text in CloudTrail logs and other output.
-
Sign in to the Amazon Web Services Management Console and open the Amazon Key Management Service (Amazon KMS) console at https://console.amazonaws.cn/kms
. -
To change the Amazon Web Services Region, use the Region selector in the upper-right corner of the page.
-
In the navigation pane, choose Customer managed keys.
-
Choose Create key.
-
To create a symmetric encryption KMS key, for Key type choose Symmetric.
For information about how to create an asymmetric KMS key in the Amazon KMS console, see Creating asymmetric KMS keys (console).
-
In Key usage, the Encrypt and decrypt option is selected for you.
For information about how to create KMS keys that generate and verify MAC codes, see Creating HMAC KMS keys.
-
Choose Next.
For information about the Advanced options, see Special-purpose keys.
-
Type an alias for the KMS key. The alias name cannot begin with
aws/
. Theaws/
prefix is reserved by Amazon Web Services to represent Amazon managed keys in your account.Note
Adding, deleting, or updating an alias can allow or deny permission to the KMS key. For details, see ABAC for Amazon KMS and Using aliases to control access to KMS keys.
An alias is a display name that you can use to identify the KMS key. We recommend that you choose an alias that indicates the type of data you plan to protect or the application you plan to use with the KMS key.
Aliases are required when you create a KMS key in the Amazon Web Services Management Console. They are optional when you use the CreateKey operation.
-
(Optional) Type a description for the KMS key.
You can add a description now or update it any time unless the key state is
Pending Deletion
orPending Replica Deletion
. To add, change, or delete the description of an existing customer managed key, edit the description in the Amazon Web Services Management Console or use the UpdateKeyDescription operation. -
(Optional) Type a tag key and an optional tag value. To add more than one tag to the KMS key, choose Add tag.
Note
Tagging or untagging a KMS key can allow or deny permission to the KMS key. For details, see ABAC for Amazon KMS and Using tags to control access to KMS keys.
When you add tags to your Amazon resources, Amazon generates a cost allocation report with usage and costs aggregated by tags. Tags can also be used to control access to a KMS key. For information about tagging KMS keys, see Tagging keys and ABAC for Amazon KMS.
-
Choose Next.
-
Select the IAM users and roles that can administer the KMS key.
Note
This key policy gives the Amazon Web Services account full control of this KMS key. It allows account administrators to use IAM policies to give other principals permission to manage the KMS key. For details, see Default key policy.
IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM
in the IAM User Guide. -
(Optional) To prevent the selected IAM users and roles from deleting this KMS key, in the Key deletion section at the bottom of the page, clear the Allow key administrators to delete this key check box.
-
Choose Next.
-
Select the IAM users and roles that can use the key in cryptographic operations
Note
This key policy gives the Amazon Web Services account full control of this KMS key. It allows account administrators to use IAM policies to give other principals permission to use the KMS key in cryptographic operations. For details, see Default key policy.
IAM best practices discourage the use of IAM users with long-term credentials. Whenever possible, use IAM roles, which provide temporary credentials. For details, see Security best practices in IAM
in the IAM User Guide. -
(Optional) You can allow other Amazon Web Services accounts to use this KMS key for cryptographic operations. To do so, in the Other Amazon Web Services accounts section at the bottom of the page, choose Add another Amazon Web Services account and enter the Amazon Web Services account identification number of an external account. To add multiple external accounts, repeat this step.
Note
To allow principals in the external accounts to use the KMS key, Administrators of the external account must create IAM policies that provide these permissions. For more information, see Allowing users in other accounts to use a KMS key.
-
Choose Next.
-
Review the key settings that you chose. You can still go back and change all settings.
-
Choose Finish to create the KMS key.
Creating symmetric encryption KMS keys (Amazon KMS API)
You can use the CreateKey operation
to create Amazon KMS keys of all types. These examples use the Amazon Command Line Interface (Amazon CLI)
Important
Do not include confidential or sensitive information in the Description
or Tags
fields. These fields may appear in plain text in CloudTrail logs and other output.
The following operation creates the most commonly used KMS key, a symmetric encryption
key in a single Region backed by key material generated by Amazon KMS. This operation has no
required parameters. However, you might also want to use the Policy
parameter
to specify a key policy. You can change the key policy (PutKeyPolicy) and add optional elements,
such as a description and tags at any time. You can also create
asymmetric keys, multi-Region keys, keys with imported key material, and keys in custom key stores.
The CreateKey
operation doesn't let you specify an alias, but you can use
the CreateAlias operation to create
an alias for your new KMS key.
The following is an example of a call to the CreateKey
operation with no
parameters. This command uses all of the default values. It creates a symmetric encryption
KMS key with key material generated by Amazon KMS.
$
aws kms create-key
{ "KeyMetadata": { "Origin": "AWS_KMS", "KeyId": "1234abcd-12ab-34cd-56ef-1234567890ab", "Description": "", "KeyManager": "CUSTOMER", "Enabled": true, "KeySpec": "SYMMETRIC_DEFAULT", "CustomerMasterKeySpec": "SYMMETRIC_DEFAULT", "KeyUsage": "ENCRYPT_DECRYPT", "KeyState": "Enabled", "CreationDate": 1502910355.475, "Arn": "arn:aws:kms:us-west-2:111122223333:key/1234abcd-12ab-34cd-56ef-1234567890ab", "AWSAccountId": "111122223333", "MultiRegion": false "EncryptionAlgorithms": [ "SYMMETRIC_DEFAULT" ], } }
If you do not specify a key policy for your new KMS key, the default key policy that CreateKey
applies differs from the default key policy that the console applies when you use it to
create a new KMS key.
For example, this call to the GetKeyPolicy operation returns the key policy that CreateKey
applies. It gives the Amazon Web Services account access to the KMS key and allows it to create
Amazon Identity and Access Management (IAM) policies for the KMS key. For detailed information about IAM
policies and key policies for KMS keys, see Authentication and access control for Amazon KMS
$
aws kms get-key-policy --key-id 1234abcd-12ab-34cd-56ef-1234567890ab --policy-name default --output text
{ "Version" : "2012-10-17", "Id" : "key-default-1", "Statement" : [ { "Sid" : "Enable IAM User Permissions", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] }