Creates a customer master key (CMK).

A CMK can be symmetric or asymmetric. Symmetric CMKs are used to generate data keys that can be used to encrypt large amounts of data. You can also use symmetric CMKs to directly encrypt data of less than 6 KB. For more information, see GenerateDataKey. Asymmetric CMKs are used to encrypt, decrypt, and sign data, and verify signatures, but cannot be used to generate data keys.

The following table describes the key types and operations supported by different CMKs.

Type

KeySpec

Description

Encryption and decryption

Signature generation and verification

Symmetric CMK

Aliyun_AES_256

Advanced Encryption Standard (AES) key with a length of 256 bits

Supported

Not supported

Symmetric CMK

Aliyun_SM4

SM4 key

Supported

Not supported

Asymmetric CMK

RSA_2048

Rivest-Shamir-Adleman (RSA) key with a length of 2,048 bits

Supported

Supported

Asymmetric CMK

RSA_3072

RSA key with a length of 3,072 bits

Supported

Supported

Asymmetric CMK

EC_P256

National Institute of Standards and Technology (NIST)-recommended elliptic curve P-256 (secp256r1)

Not supported

Supported

Asymmetric CMK

EC_P256K

Standards for Efficient Cryptography Group (SECG) elliptic curve secp256k1

Not supported

Supported

Asymmetric CMK

EC_SM2

256-bit elliptic curves over the prime field that is defined in GB/T 32918

Supported

Supported

Note
  • The KeySpec parameter for a symmetric CMK consists of the standard key type prefixed with Aliyun_. The prefix indicates that the CMK uses a standard encryption algorithm. However, the ciphertext that is generated by using the CMK is not standard. An asymmetric CMK generates standard ciphertext or signatures.
  • An RSA CMK supports encryption or decryption and signature generation or verification, but cannot support them at the same time.
  • SM4 and SM2 are block ciphers used in the Chinese National Standards. Key Management Service (KMS) supports SM4 and SM2 CMKs created in a managed hardware security module (HSM) that is deployed in mainland China.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes CreateKey

The operation that you want to perform. Set the value to CreateKey.

Description String No key description example

The description of the CMK.

The description can be 0 to 8,192 characters in length.

KeySpec String No Aliyun_AES_256

The type of the CMK. Valid values:

  • Aliyun_AES_256
  • Aliyun_SM4
  • RSA_2048
  • RSA_3072
  • EC_P256
  • EC_P256K
  • EC_SM2
Note If the CMK is created in a managed HSM in mainland China, the default value is Aliyun_SM4. In other cases, the default value is Aliyun_AES_256.
KeyUsage String No ENCRYPT/DECRYPT

The usage of the CMK. Valid values:

  • ENCRYPT/DECRYPT: The CMK is used to encrypt or decrypt data.
  • SIGN/VERIFY: The CMK is used to generate or verify a digital signature.
Origin String No Aliyun_KMS

The source of key material. Valid values:

  • Aliyun_KMS. This is the default value.
  • EXTERNAL
Note
  • The value of this parameter is case-sensitive.
  • If you set the KeySpec parameter to an asymmetric CMK type, do not set the Origin parameter to EXTERNAL.
  • If you set the Origin parameter to EXTERNAL, you must import key material.
ProtectionLevel String No SOFTWARE

The protection level of the CMK. Valid values:

  • SOFTWARE. This is the default value.
  • HSM
Note
  • The value of this parameter is case-sensitive.
  • Assume that you set this parameter to HSM. If you set the Origin parameter to Aliyun_KMS, the CMK is created in a managed HSM. If you set the Origin parameter to EXTERNA, you can import an external key to the managed HSM.
EnableAutomaticRotation Boolean No false

Specifies whether to enable automatic key rotation. Valid values:

  • true
  • false: This is the default value.
Note If the Origin parameter is set to EXTERNAL or the KeySpec parameter is set to an asymmetric CMK type, automatic rotation is unavailable.
RotationInterval String No 365d

The interval of automatic rotation. Format: integer[unit]. Unit: d (day), h (hour), m (minute), or s (second). For example, both 7d and 604800s represent a seven-day interval. Valid values: 7 to 730 days.

Note You must specify this parameter if the EnableAutomaticRotation parameter is set to true. If the EnableAutomaticRotation parameter is set to false, this parameter is ignored.

For more information about common request parameters, see Common parameters.

Response parameters

Parameter Type Example Description
KeyMetadata Struct

The metadata of the CMK.

Arn String acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****

The Alibaba Cloud Resource Name (ARN) of the CMK.

AutomaticRotation String Disabled

Indicates whether automatic key rotation is enabled.

  • Enabled: Automatic key rotation is enabled.
  • Disabled: Automatic key rotation is disabled.
  • Suspended: KMS suspended the execution of automatic key rotation. For more information, see Automatic key rotation.
Note Automatic key rotation is available only for symmetric CMKs.
CreationDate String 2016-03-25T10:42:40Z

The date and time when the CMK was created. The time is displayed in UTC.

Creator String 154035569884****

The creator of the CMK.

DeleteDate String 2020-07-06T18:22:03Z

The date and time when the CMK is scheduled for deletion.

For more information, see ScheduleKeyDeletion.

Note This value is returned only when the value of the KeyState parameter is PendingDeletion.
Description String key description example

The description of the CMK.

KeyId String d6bee1cb-2e14-4277-ba6b-73786b21****

The globally unique ID of the CMK.

KeySpec String Aliyun_AES_256

The type of the CMK.

KeyState String Enabled

The status of the CMK.

For more information, see Effects of CMK statuses on calling API operations.

KeyUsage String ENCRYPT/DECRYPT

The usage of the CMK.

LastRotationDate String 2019-06-06T18:22:03Z

The date and time when the last rotation was performed. The time is displayed in UTC.

For a new CMK, the value of this parameter is the date and time when the initial version of the CMK was generated.

MaterialExpireTime String 2020-07-06T18:22:03Z

The date and time when the key material for the CMK expires. The time is displayed in UTC.

If the value is empty, the key material for the CMK does not expire.

NextRotationDate String 2020-07-06T18:22:03Z

The time when the next rotation is scheduled for execution.

Note This value is returned only when the value of the AutomaticRotation parameter is Enabled or Suspended.
Origin String Aliyun_KMS

The source of the key material for the CMK.

PrimaryKeyVersion String 7ce1d081-06cb-42e6-aab6-5c5de030****

The ID of the current primary key version of the symmetric CMK.

Note
  • The primary key version of a symmetric CMK is an active encryption key. KMS uses the primary key version of a specified CMK to encrypt data.
  • This parameter is unavailable for asymmetric CMKs.
ProtectionLevel String SOFTWARE

The protection level of the CMK.

RotationInterval String 31536000s

The interval of automatic key rotation. Unit: seconds. The format is an integer followed by the letter s. For example, a seven-day rotation interval is expressed as 604800s. This value is returned only when the value of the AutomaticRotation parameter is Enabled or Suspended.

RequestId String 36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06

The ID of the request.

Examples

Sample requests

https://[Endpoint]/?Action=CreateKey
&<Common request parameters>

Sample success responses

XML format

<KMS>
	  <KeyMetadata>
		    <CreationDate>2021-04-12T06:00:54Z</CreationDate>
		    <Description></Description>
		    <KeyId>d6bee1cb-2e14-4277-ba6b-73786b21****</KeyId>
		    <KeySpec>Aliyun_AES_256</KeySpec>
		    <KeyState>Enabled</KeyState>
		    <KeyUsage>ENCRYPT/DECRYPT</KeyUsage>
		    <PrimaryKeyVersion>7ce1d081-06cb-42e6-aab6-5c5de030****</PrimaryKeyVersion>
		    <DeleteDate></DeleteDate>
		    <Creator>154035569884****</Creator>
		    <Arn>acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****</Arn>
		    <Origin>Aliyun_KMS</Origin>
		    <MaterialExpireTime></MaterialExpireTime>
		    <ProtectionLevel>SOFTWARE</ProtectionLevel>
		    <LastRotationDate>2021-04-12T06:00:54Z</LastRotationDate>
		    <AutomaticRotation>Disabled</AutomaticRotation>
	  </KeyMetadata>
	  <RequestId>36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06</RequestId>
</KMS>

JSON format

{
  "KeyMetadata": {
    "CreationDate": "2021-04-12T06:00:54Z",
    "Description": "",
    "KeyId": "d6bee1cb-2e14-4277-ba6b-73786b21****",
    "KeySpec": "Aliyun_AES_256",
    "KeyState": "Enabled",
    "KeyUsage": "ENCRYPT/DECRYPT",
    "PrimaryKeyVersion": "7ce1d081-06cb-42e6-aab6-5c5de030****",
    "DeleteDate": "",
    "Creator": "154035569884****",
    "Arn": "acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****",
    "Origin": "Aliyun_KMS",
    "MaterialExpireTime": "",
    "ProtectionLevel": "SOFTWARE",
    "LastRotationDate": "2021-04-12T06:00:54Z",
    "AutomaticRotation": "Disabled"
  },
  "RequestId": "36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06"
}

Error codes

For a list of error codes, visit the API Error Center.