CreateKey - Key Management Service - Alibaba Cloud Documentation Center

Usage notes

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 encrypt small volume of data that is less than 6 KB. For more information, see GenerateDataKey. Asymmetric CMKs are used to encrypt data, decrypt data, generate digital signatures, and verify digital signatures. However, you cannot use asymmetric CMKs to generate data keys.

The following table describes different types of CMKs and the operations that are supported by the CMKs.


CMK category	CMK type	Description	Encryption and decryption	Signature generation and verification
Symmetric CMK	Aliyun_AES_256	An advanced Encryption Standard (AES) CMK with a length of 256 bits.	Yes	No
Symmetric CMK	Aliyun_AES_128	An AES CMK with a length of 128 bits. Only Dedicated KMS supports this CMK type.	Yes	No
Symmetric CMK	Aliyun_AES_192	An AES CMK with a length of 192 bits. Only Dedicated KMS supports this CMK type.	Yes	No
Symmetric CMK	Aliyun_SM4	SM4 CMK.	Yes	No
Asymmetric CMK	RSA_2048	Rivest-Shamir-Adleman (RSA) CMK with a length of 2,048 bits.	Supported	Supported
Asymmetric CMK	RSA_3072	RSA CMK 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

If the value of the KeySpec parameter that is used to create a symmetric CMK is prefixed with Aliyun_, a standard cryptographic algorithm is used, but non-standard ciphertext is generated. An asymmetric CMK can be used to generate standard ciphertext or signatures.
You can use an RSA CMK to perform one of the two types of operations: encrypt and decrypt data, and generate and verify signatures. You cannot use the RSA CMK to perform both two types of operations.

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.
KeyUsage	String	No	ENCRYPT/DECRYPT	The usage of the CMK. Valid values: ENCRYPT/DECRYPT: encrypts or decrypts data. SIGN/VERIFY: generates or verifies a digital signature. If the CMK supports signature verification, the default value is SIGN/VERIFY. If the CMK does not support signature verification, the default value is ENCRYPT/DECRYPT.
Origin	String	No	Aliyun_KMS	The source of key material. Valid values: Aliyun_KMS (default value) EXTERNAL Note The value of this parameter is case-sensitive. If you set the KeySpec parameter to an asymmetric CMK type, you are not allowed to set the Origin parameter to EXTERNAL. If you set the Origin parameter to EXTERNAL, you must import key material. For more information, see Import key material.
ProtectionLevel	String	No	SOFTWARE	The protection level of the CMK. Valid values: SOFTWARE HSM Default value: SOFTWARE. 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 EXTERNAL, you can import an external key into the managed HSM.
EnableAutomaticRotation	Boolean	No	false	Specifies whether to enable automatic key rotation. Valid values: true false Default value: false. Note If the Origin parameter is set to EXTERNAL or the KeySpec parameter is set to an asymmetric CMK type, automatic key rotation is not supported.
RotationInterval	String	No	365d	The period of automatic key rotation. Specify the value in the integer[unit] format. Unit: d (day), h (hour), m (minute), or s (second). For example, you can use either 7d or 604800s to specify a seven-day period. The period can range from 7 days to 730 days. Note If you set the EnableAutomaticRotation parameter to true, you must also specify this parameter. If you set the EnableAutomaticRotation parameter to false, you can leave this parameter unspecified.
KeySpec	String	No	Aliyun_AES_256	The type of the CMK. Valid values: Aliyun_AES_256 Aliyun_AES_128 Aliyun_AES_192 Aliyun_SM4 RSA_2048 RSA_3072 EC_P256 EC_P256K EC_SM2 Note The default type of the CMK is Aliyun_AES_256. Only Dedicated KMS supports Aliyun_AES_128 and Aliyun_AES_192.
DKMSInstanceId	String	No	kst-bjj62d8f5e0sgtx8h****	The ID of the dedicated KMS instance.

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

Response parameters


Parameter	Type	Example	Description
RequestId	String	36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06	The ID of the request, which is used to locate and troubleshoot issues.
KeyMetadata	Object		The metadata of the CMK.
KeyId	String	d6bee1cb-2e14-4277-ba6b-73786b21****	The ID of the CMK. The ID must be globally unique.
NextRotationDate	String	2022-07-06T18:22:03Z	The time when the next rotation will be performed. Note This value is returned only when the value of the AutomaticRotation parameter is Enabled or Suspended.
KeyState	String	Enabled	The status of the CMK. For more information, see Impact of CMK status on API operations.
RotationInterval	String	31536000s	The period of automatic key rotation. Unit: seconds. The value is in the format of an integer followed by the letter s. For example, if the rotation period is seven days, this parameter is set to 604800s. This value is returned only when the value of the AutomaticRotation parameter is Enabled or Suspended.
Arn	String	acs:kms:cn-qingdao:154035569884**:key/d6bee1cb-2e14-4277-ba6b-73786b21**	The Alibaba Cloud Resource Name (ARN) of the CMK.
Creator	String	154035569884****	The creator of the CMK.
LastRotationDate	String	2022-06-06T18:22:03Z	The time when the last rotation was performed. The time is displayed in UTC. For a new CMK, this parameter value is the time when the initial version of the CMK was generated.
DeleteDate	String	2022-07-06T18:22:03Z	The 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.
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.
Description	String	key description example	The description of the CMK.
KeySpec	String	Aliyun_AES_256	The type of the CMK.
Origin	String	Aliyun_KMS	The source of the key material for the CMK.
MaterialExpireTime	String	2022-07-06T18:22:03Z	The time when the key material expires. The time is displayed in UTC. If this parameter value is empty, the key material does not expire.
AutomaticRotation	String	Disabled	Indicates whether automatic key rotation is enabled. Valid values: Enabled: Automatic key rotation is enabled. Disabled: Automatic key rotation is disabled. Suspended: Automatic key rotation is suspended. For more information, see Automatic key rotation. Note Automatic key rotation is available only for symmetric CMKs.
ProtectionLevel	String	SOFTWARE	The protection level of the CMK.
KeyUsage	String	ENCRYPT/DECRYPT	The usage of the CMK.
CreationDate	String	2022-03-25T10:42:40Z	The date and time when the CMK was created. The time is displayed in UTC.
DKMSInstanceId	String	kst-bjj62d8f5e0sgtx8h****	The ID of the dedicated KMS instance.

Examples

Sample requests

http(s)://[Endpoint]/?Action=CreateKey
&Description=key description example
&KeyUsage=ENCRYPT/DECRYPT
&Origin=Aliyun_KMS
&ProtectionLevel=SOFTWARE
&EnableAutomaticRotation=false
&RotationInterval=365d
&KeySpec=Aliyun_AES_256
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateKeyResponse>
    <RequestId>36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06</RequestId>
    <KeyMetadata>
        <KeyId>d6bee1cb-2e14-4277-ba6b-73786b21****</KeyId>
        <NextRotationDate>2022-07-06T18:22:03Z</NextRotationDate>
        <KeyState>Enabled</KeyState>
        <RotationInterval>31536000s</RotationInterval>
        <Arn>acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****</Arn>
        <Creator>154035569884****</Creator>
        <LastRotationDate>2022-06-06T18:22:03Z</LastRotationDate>
        <DeleteDate>2022-07-06T18:22:03Z</DeleteDate>
        <PrimaryKeyVersion>7ce1d081-06cb-42e6-aab6-5c5de030****</PrimaryKeyVersion>
        <Description>key description example</Description>
        <KeySpec>Aliyun_AES_256</KeySpec>
        <Origin>Aliyun_KMS</Origin>
        <MaterialExpireTime>2022-07-06T18:22:03Z</MaterialExpireTime>
        <AutomaticRotation>Disabled</AutomaticRotation>
        <ProtectionLevel>SOFTWARE</ProtectionLevel>
        <KeyUsage>ENCRYPT/DECRYPT</KeyUsage>
        <CreationDate>2022-03-25T10:42:40Z</CreationDate>
        <DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
    </KeyMetadata>
</CreateKeyResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06",
  "KeyMetadata" : {
    "KeyId" : "d6bee1cb-2e14-4277-ba6b-73786b21****",
    "NextRotationDate" : "2022-07-06T18:22:03Z",
    "KeyState" : "Enabled",
    "RotationInterval" : "31536000s",
    "Arn" : "acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****",
    "Creator" : "154035569884****",
    "LastRotationDate" : "2022-06-06T18:22:03Z",
    "DeleteDate" : "2022-07-06T18:22:03Z",
    "PrimaryKeyVersion" : "7ce1d081-06cb-42e6-aab6-5c5de030****",
    "Description" : "key description example",
    "KeySpec" : "Aliyun_AES_256",
    "Origin" : "Aliyun_KMS",
    "MaterialExpireTime" : "2022-07-06T18:22:03Z",
    "AutomaticRotation" : "Disabled",
    "ProtectionLevel" : "SOFTWARE",
    "KeyUsage" : "ENCRYPT/DECRYPT",
    "CreationDate" : "2022-03-25T10:42:40Z",
    "DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
  }
}

Error codes


HTTP status code	Error code	Error message	Description
400	InvalidParameter	The specified parameter is not valid.	The error message returned because an invalid value is specified for the parameter.
404	InvalidAccessKeyId.NotFound	The Access Key ID provided does not exist in our records.	The error message returned because the specified AccessKey ID does not exist.

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