Creates a key.
Key Management Service (KMS) supports common symmetric keys and asymmetric keys. For more information, see Key types and specifications.
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 key. The description can be 0 to 8,192 characters in length. |
KeyUsage | String | No | ENCRYPT/DECRYPT | The usage of the key. Valid values:
If the key supports signing and verification, the default value is SIGN/VERIFY. If the key does not support signing and verification, the default value is ENCRYPT/DECRYPT. |
Origin | String | No | Aliyun_KMS | The key material origin. Valid values:
Note
|
ProtectionLevel | String | No | SOFTWARE | The protection level of the key. You do not need to configure the parameter. KMS sets a protection level for the key. Valid values:
Note
|
EnableAutomaticRotation | Boolean | No | true | Specifies whether to enable automatic key rotation. Valid values:
The parameter is valid only when the key belongs to an instance type that supports automatic rotation. For more information, see Key rotation. |
RotationInterval | String | No | 365d | The period of automatic key 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.
Note If EnableAutomaticRotation is set to true, RotationInterval is required. |
KeySpec | String | No | Aliyun_AES_256 | The specification of the key. The valid values vary based on the KMS instance type. For more information about key specifications, standards, and key algorithms, see Key types and key specifications. Note If you do not specify a value for this parameter, the default key specification is Aliyun_AES_256. |
DKMSInstanceId | String | No | kst-bjj62d8f5e0sgtx8h**** | The ID of the KMS instance. Note You must specify this parameter if you need to create a key for the KMS instance. If you need to create a default key of the CMK type, you do not need to specify the parameter. |
Tags | String | No | [{"TagKey":"disk-encryption","TagValue":"true"}] | The tag that is added to the key. A tag consists of a key-value pair. You can enter up to 20 tags. Enter multiple tags in the Each tag key or tag value can be up to 128 characters in length and can contain letters, digits, forward slashes (/), backslashes (\), underscores (_), hyphens (-), periods (.), plus signs (+), equal signs (=), colons (:), and at signs (@). Note The tag key cannot start with aliyun or acs:. |
Policy | String | No | {"Statement":[{"Action":["kms:*"],"Effect":"Allow","Principal":{"RAM":["acs:ram::119285303511****:*"]},"Resource":["*"],"Sid":"kms default key policy"},{"Action":["kms:List*","kms:Describe*","kms:Create*","kms:Enable*","kms:Disable*","kms:Get*","kms:Set*","kms:Update*","kms:Delete*","kms:Cancel*","kms:TagResource","kms:UntagResource","kms:ImportKeyMaterial","kms:ScheduleKeyDeletion"],"Effect":"Allow","Principal":{"RAM":["acs:ram::119285303511****:user/for_test_policy"]},"Resource":["*"]}],"Version":"1"} | The content of the key policy. The value is in the JSON format. The value can be up to 32,768 bytes in length. For more information about key policies, see Overview. If you do not specify the parameter, the default policy is used. A key policy contains the following content:
Example:
Statement description:
Note If you grant a RAM user or RAM role of other Alibaba Cloud accounts permissions to use a key, you must use the Alibaba Cloud account of the RAM user or RAM role to grant the RAM user or RAM role permissions to use the key in RAM. For more information, see Custom policies, Grant permissions to a RAM user, and Grant permissions to a RAM role. |
For more information about common request parameters, see Common parameters.
Response parameters
Parameter | Type | Example | Description |
RequestId | String | 381D5D33-BB8F-395F-8EE4-AE3BB4B523C4 | The ID of the request, which is used to locate and troubleshoot issues. |
KeyMetadata | Object | The metadata of the key. | |
KeyId | String | key-hzz62f1cb66fa42qo**** | The globally unique ID of the key. |
NextRotationDate | String | 2024-03-25T10:00:00Z | The time when the key is next rotated. This value is returned only when the value of AutomaticRotation is Enabled or Suspended. |
KeyState | String | Enabled | The status of the key. For more information, see Impacts of key status on API operations. |
RotationInterval | String | 31536000s | The interval for automatic key rotation. Unit: seconds. The format is an integer value followed by the character 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 AutomaticRotation is Enabled or Suspended. |
Arn | String | acs:kms:cn-qingdao:154035569884****:key/key-hzz62f1cb66fa42qo**** | The Alibaba Cloud Resource Name (ARN) of the key. |
Creator | String | 154035569884**** | The user who created the key. |
LastRotationDate | String | 2023-03-25T10:00:00Z | The time when the last rotation is performed. The time is displayed in UTC. For a new key, the parameter value is the time when the initial version of the key is generated. |
DeleteDate | String | 2025-03-25T10:00:00Z | The time when the key is scheduled for deletion. For more information, see ScheduleKeyDeletion. The parameter is returned only when the value of KeyState is PendingDeletion. |
PrimaryKeyVersion | String | 7ce1d081-06cb-42e6-aab6-5c5de030**** | The current primary version identifier of the key. |
Description | String | key description example | The description of the key. |
KeySpec | String | Aliyun_AES_256 | The specification of the key. |
Origin | String | Aliyun_KMS | The key material origin. |
MaterialExpireTime | String | 2025-03-25T10:00:00Z | 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 | Enabled | The status of automatic key rotation. Valid values:
|
ProtectionLevel | String | SOFTWARE | The protection level of the key. |
KeyUsage | String | ENCRYPT/DECRYPT | The usage of the key. |
CreationDate | String | 2024-03-25T10:00:00Z | The date and time (UTC) when the key is created. |
DKMSInstanceId | String | kst-bjj62d8f5e0sgtx8h**** | The ID of the KMS instance. |
Examples
Sample requests
http(s)://[Endpoint]/?Action=CreateKey
&Description=key description example
&KeyUsage=ENCRYPT/DECRYPT
&Origin=Aliyun_KMS
&ProtectionLevel=SOFTWARE
&EnableAutomaticRotation=true
&RotationInterval=365d
&KeySpec=Aliyun_AES_256
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&Tags=[{"TagKey":"disk-encryption","TagValue":"true"}]
&Policy={"Statement":[{"Action":["kms:*"],"Effect":"Allow","Principal":{"RAM":["acs:ram::119285303511****:*"]},"Resource":["*"],"Sid":"kms default key policy"},{"Action":["kms:List*","kms:Describe*","kms:Create*","kms:Enable*","kms:Disable*","kms:Get*","kms:Set*","kms:Update*","kms:Delete*","kms:Cancel*","kms:TagResource","kms:UntagResource","kms:ImportKeyMaterial","kms:ScheduleKeyDeletion"],"Effect":"Allow","Principal":{"RAM":["acs:ram::119285303511****:user/for_test_policy"]},"Resource":["*"]}],"Version":"1"}
&<Common request parameters>
Sample success responses
XML
format
HTTP/1.1 200 OK
Content-Type:application/xml
<CreateKeyResponse>
<RequestId>381D5D33-BB8F-395F-8EE4-AE3BB4B523C4</RequestId>
<KeyMetadata>
<KeyId>key-hzz62f1cb66fa42qo****</KeyId>
<NextRotationDate>2024-03-25T10:00:00Z</NextRotationDate>
<KeyState>Enabled</KeyState>
<RotationInterval>31536000s</RotationInterval>
<Arn>acs:kms:cn-qingdao:154035569884****:key/key-hzz62f1cb66fa42qo****</Arn>
<Creator>154035569884****</Creator>
<LastRotationDate>2023-03-25T10:00:00Z</LastRotationDate>
<DeleteDate>2025-03-25T10:00:00Z</DeleteDate>
<PrimaryKeyVersion>7ce1d081-06cb-42e6-aab6-5c5de030****</PrimaryKeyVersion>
<Description>key description example</Description>
<KeySpec>Aliyun_AES_256</KeySpec>
<Origin>Aliyun_KMS</Origin>
<MaterialExpireTime>2025-03-25T10:00:00Z</MaterialExpireTime>
<AutomaticRotation>Enabled</AutomaticRotation>
<ProtectionLevel>SOFTWARE</ProtectionLevel>
<KeyUsage>ENCRYPT/DECRYPT</KeyUsage>
<CreationDate>2024-03-25T10:00:00Z</CreationDate>
<DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
</KeyMetadata>
</CreateKeyResponse>
JSON
format
HTTP/1.1 200 OK
Content-Type:application/json
{
"RequestId" : "381D5D33-BB8F-395F-8EE4-AE3BB4B523C4",
"KeyMetadata" : {
"KeyId" : "key-hzz62f1cb66fa42qo****",
"NextRotationDate" : "2024-03-25T10:00:00Z",
"KeyState" : "Enabled",
"RotationInterval" : "31536000s",
"Arn" : "acs:kms:cn-qingdao:154035569884****:key/key-hzz62f1cb66fa42qo****",
"Creator" : "154035569884****",
"LastRotationDate" : "2023-03-25T10:00:00Z",
"DeleteDate" : "2025-03-25T10:00:00Z",
"PrimaryKeyVersion" : "7ce1d081-06cb-42e6-aab6-5c5de030****",
"Description" : "key description example",
"KeySpec" : "Aliyun_AES_256",
"Origin" : "Aliyun_KMS",
"MaterialExpireTime" : "2025-03-25T10:00:00Z",
"AutomaticRotation" : "Enabled",
"ProtectionLevel" : "SOFTWARE",
"KeyUsage" : "ENCRYPT/DECRYPT",
"CreationDate" : "2024-03-25T10:00:00Z",
"DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
}
}
Error codes
HTTP status code | Error code | Error message | Description |
400 | Rejected.LimitExceeded | The request was rejected because user create resource limit was exceeded | The request is rejected because the number of created resources reaches the upper limit. |
400 | InvalidParameter | The specified parameter is not valid. | An invalid value is specified for the parameter. |
400 | UnsupportedOperation | This action is not supported. | The operation is not supported. |
400 | Forbidden.NoPermission | This operation is forbidden by permission system. | You are not authorized to perform this operation. |
400 | Rejected.ShareQuotaExceedLimit | Instance Share Quota Exceed Limit. | The access management quota is exceeded. |
403 | Forbidden.DKMSInstanceNotFound | The specified DKMS Instance is not found. | Your dedicated KMS instance is not found. |
500 | InternalFailure | Internal Failure | An internal error occurs. |
503 | SerivceUnvailableTemporary | Service Unvailable Temporary | The service is temporarily unavailable. |
For a list of error codes, see Service error codes.