All Products
Search
Document Center

Key Management Service:CreateKey

Last Updated:Jul 25, 2024

Creates a key.

Key Management Service (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: encrypts or decrypts data.

  • SIGN/VERIFY: signs data or verifies a digital signature.

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

The protection level of the key. You do not need to configure the parameter. KMS sets a protection level for the key.

Valid values:

  • SOFTWARE

  • HSM

Note
  • If you configure DKMSInstanceId, ProtectionLevel 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 configure DKMSInstanceId, we recommend that you do not configure ProtectionLevel. KMS sets a protection level for the 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)

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.

  • 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, 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 [{"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:.

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:

  • Version: the version of the key policy. Set the value to 1.

  • Statement: the statement of the key policy. Each key policy contains one or more statements.

Example:

{
  "Version": "1",
  "Statement": [
    {
      "Sid": "Enable RAM User Permissions",
      "Effect": "Allow",
      "Principal": {
        "RAM": ["acs:ram::112890462****:root"]
      },
      "Action": [
        "kms:*"
      ],
      "Resource": [
        "*"
      ],
      "Condition": {
        "condition operator": {
          "condition key": "condition value"
        }
      }
    }
  ]
}

Statement description:

  • Sid: optional. The statement identifier of a custom statement. The value can be up to 128 characters in length and can contain letters, digits, and the following special characters: _ / + = . @ -

  • Effect: required. Specifies whether the permissions in a policy statement are allowed or denied. Valid values: Allow and Deny.

  • Principal: required. The authorization principal of the policy. The following principals are supported: the current Alibaba Cloud account to which the key belongs, RAM users and RAM roles of the current Alibaba Cloud account, and RAM users and RAM roles of other Alibaba Cloud accounts.

  • Action: required. The API operation that you want to allow or deny. The value must start with kms:. For more information about the API operation scope, see Overview. If you specify an API operation outside the scope, the API operation does not take effect.

  • Resource: required. Set the value to an asterisk (*), which specifies the current key.

  • Condition: optional. The conditions that are required for a policy to take effect. Conditions allow you to evaluate the context of an API request to determine whether a policy statement applies. Format: "Condition": {"condition operator": {"condition key": "condition value"}}. For more information, see Overview.

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:

  • Enabled: Automatic key rotation is enabled.

  • Disabled: Automatic key rotation is disabled.

  • Suspended: Automatic key rotation is suspended.

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.