Creates a customer master key (CMK).
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 |
- 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
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:
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:
Note
|
ProtectionLevel | String | No | SOFTWARE |
The protection level of the CMK. Valid values:
Default value: SOFTWARE. Note
|
EnableAutomaticRotation | Boolean | No | false |
Specifies whether to enable automatic key rotation. Valid values:
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:
Note
|
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
|
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:
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.