Creating keys - AWS Key Management Service

Creating keys

You can create AWS KMS keys in the AWS Management Console, or by using the CreateKey operation or an AWS CloudFormation template. During this process, you determine the cryptographic configuration of your KMS key and the origin of 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.

If you are creating a KMS key to encrypt data you store or manage in an AWS service, create a symmetric KMS key. AWS services that are integrated with AWS KMS use symmetric KMS keys to encrypt your data. These services do not support encryption with asymmetric KMS keys. For help deciding which type of KMS key to create, see Choosing your KMS key configuration.

When you create a KMS key in the AWS 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 AWS KMS, see Using aliases.

Learn more:

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 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 AWS KMS.

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 parameter, which is not recommended.

KMS keys belong to the AWS 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 KMS keys

You can create symmetric KMS key in the AWS Management Console or by using the AWS KMS API. Symmetric key encryption uses the same key to encrypt and decrypt data.

Creating symmetric KMS keys (console)

You can use the AWS Management Console to create AWS KMS keys (KMS keys).

  1. Sign in to the AWS Management Console and open the AWS Key Management Service (AWS KMS) console at https://console.aws.amazon.com/kms.

  2. To change the AWS Region, use the Region selector in the upper-right corner of the page.

  3. In the navigation pane, choose Customer managed keys.

  4. Choose Create key.

  5. To create a symmetric KMS key, for Key type choose Symmetric.

    For information about how to create an asymmetric KMS key in the AWS KMS console, see Creating asymmetric KMS keys (console).

  6. Choose Next.

  7. Type an alias for the KMS key. The alias name cannot begin with aws/. The aws/ prefix is reserved by Amazon Web Services to represent AWS 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 AWS 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 AWS Management Console. They are optional when you use the CreateKey operation.

  8. (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 or Pending Replica Deletion. To add, change, or delete the description of an existing customer managed key, edit the description in the AWS Management Console or use the UpdateKeyDescription operation.

  9. Choose Next.

  10. (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 AWS KMS and Using tags to control access to KMS keys.

    When you add tags to your AWS resources, AWS 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 AWS KMS.

  11. Choose Next.

  12. Select the IAM users and roles that can administer the KMS key.

    Note

    IAM policies can give other IAM users and roles permission to manage the KMS key.

  13. (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.

  14. Choose Next.

  15. Select the IAM users and roles that can use the KMS key for cryptographic operations.

    Note

    The AWS account (root user) has full permissions by default. As a result, any IAM policies can also give users and roles permission to use the KMS key for cryptographic operations.

  16. (Optional) You can allow other AWS accounts to use this KMS key for cryptographic operations. To do so, in the Other AWS accounts section at the bottom of the page, choose Add another AWS account and enter the AWS 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.

  17. Choose Next.

  18. Review the key settings that you chose. You can still go back and change all settings.

  19. Choose Finish to create the KMS key.

Creating symmetric KMS keys (AWS KMS API)

You can use the CreateKey operation to create a new symmetric AWS KMS keys. These examples use the AWS Command Line Interface (AWS CLI), but you can use any supported programming language.

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. Also, if you are creating a KMS key for imported key material or a KMS key in a custom key store, the Origin parameter is required.

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 KMS key for encrypting and decrypting with key material generated by AWS 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 AWS account access to the KMS key and allows it to create AWS 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 AWS 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 policies", "Effect" : "Allow", "Principal" : { "AWS" : "arn:aws:iam::111122223333:root" }, "Action" : "kms:*", "Resource" : "*" } ] }