All Products
Search
Document Center

Key Management Service:CreateKey

Last Updated:Dec 08, 2023

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 KMSInstanceId 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 KMSInstanceId, 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.