CreateKey - Key Management Service - Alibaba Cloud Documentation Center

Creates a Key Management Service (KMS) key.

KMS supports common symmetric keys and asymmetric keys. For more information, see Key types and specifications.

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 key. The description can be 0 to 8,192 characters in length.
KeyUsage	String	No	ENCRYPT/DECRYPT	The usage of the key. Valid values: ENCRYPT/DECRYPT SIGN/VERIFY 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: Aliyun_KMS (default): KMS generates key material. EXTERNAL: You import key material. Note The value of this parameter is case-sensitive. Default keys of the customer master key (CMK) type support Aliyun_KMS and EXTERNAL. Keys in instances of the software key management type support only Aliyun_KMS. Keys in instances of the hardware key management type support Aliyun_KMS and EXTERNAL. If you set Origin to EXTERNAL, you must import key material. For more information, see Import key material into a symmetric key or Import key material into an asymmetric key.
ProtectionLevel	String	No	SOFTWARE	You do not need to specify this parameter. KMS sets a protection level for your key. The protection level of the key. Valid values: SOFTWARE HSM Note If DKMSInstanceId is specified, this parameter does not take effect. If your instance is an instance of the software key management type, set the value to SOFTWARE. If your instance is an instance of the hardware key management type, set the value to HSM. If you do not specify DKMSInstanceId, we recommend that you do not specify this parameter. KMS sets a protection level for your key. If managed hardware security modules (HSMs) exist in the region of your KMS instance, set the value to HSM. If managed HSMs do not exist in the region of your KMS instance, set the value to SOFTWARE. For more information, see Managed HSM overview.
EnableAutomaticRotation	Boolean	No	true	Specifies whether to enable automatic key rotation. Valid values: true false (default) This 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. For a default key, set the value to 365 days. For a software-protected key, set a value that ranges from 7 to 365 days. A hardware-protected key does not support automatic rotation. Note If EnableAutomaticRotation is set to true, this parameter is required.
KeySpec	String	No	Aliyun_AES_256	The key specification. The valid values vary based on the KMS instance type. For more information, see Overview. 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 a KMS instance. If you need to create a default key of the CMK type, you do not need to specify this 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 `[{"TagKey":"key1","TagValue":"value1"},{"TagKey":"key2","TagValue":"value2"},..]` format. 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:.

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 was performed. The time is displayed in UTC. For a new key, this parameter value is the time when the initial version of the key was generated.
DeleteDate	String	2025-03-25T10:00:00Z	The time when the key is scheduled for deletion. For more information, see ScheduleKeyDeletion. This 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: Enabled Disabled Suspended
ProtectionLevel	String	SOFTWARE	The protection level of the key.
KeyUsage	String	ENCRYPT/DECRYPT	The usage of the key.
CreationDate	String	2023-03-25T10:00:00Z	The date and time (UTC) when the key was 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"}]
&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>2023-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" : "2023-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.

For a list of error codes, see Service error codes.