备案控制台
文档
产品文档
输入文档关键字查找
首页 密钥管理服务 服务支持 旧版本产品文档 API参考 KMS API 密钥 CreateKey

CreateKey

更新时间：
一键部署
产品详情
相关技术圈
我的收藏

调用CreateKey接口创建一个主密钥。

阿里云KMS支持常见的对称密钥规格和非对称密钥规格。具体内容，请参见密钥管理类型和密钥规格。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

请求参数

名称

类型

是否必选

示例值

描述

Action

String

是

CreateKey

要执行的操作。取值：CreateKey。

Description

String

否

key description example

密钥的描述。

长度为0~8192个字符。

KeyUsage

String

否

ENCRYPT/DECRYPT

密钥的用途。取值：

  • ENCRYPT/DECRYPT：数据加密和解密。

  • SIGN/VERIFY：产生和验证数字签名。

默认值：如果密钥支持签名验签，默认值为SIGN/VERIFY，否则默认值为ENCRYPT/DECRYPT。

Origin

String

否

Aliyun_KMS

密钥材料来源。取值：

  • Aliyun_KMS（默认值）：密钥材料由阿里云KMS生成。

  • EXTERNAL：密钥材料由您自行导入。

说明

  • 请注意区分大小写。

  • 默认密钥（主密钥）支持选择Aliyun_KMS或EXTERNAL；软件密钥管理实例中的密钥仅支持选择Aliyun_KMS；硬件密钥管理实例中的密钥支持选择Aliyun_KMS或EXTERNAL。

  • 如果选择EXTERNAL，您需要自行导入密钥材料。具体操作，请参见导入对称密钥材料或导入非对称密钥材料。

ProtectionLevel

String

否

SOFTWARE

您无需输入本参数，KMS会为您的密钥设置合适的保护级别。

密钥的保护级别，取值：

  • SOFTWARE

  • HSM

说明

  • 如果指定了DKMSInstanceId：本参数输入后不生效。当实例为KMS软件密钥管理实例时，密钥保护级别为SOFTWARE；当实例为KMS硬件密钥管理实例时，密钥保护级别为HSM。

  • 如果未指定DKMSInstanceId：建议您不输入，由KMS设置。当KMS在该地域有托管密码机时，本参数将设置HSM，否则为SOFTWARE。更多信息，请参见托管密码机概述。

EnableAutomaticRotation

Boolean

否

true

是否开启密钥自动轮转。取值：

  • true：开启

  • false（默认值）：不开启

仅当密钥所属的密钥管理类型支持自动轮转时，该参数值有效。具体内容，请参见密钥轮转。

RotationInterval

String

否

365d

自动轮转的时间周期。格式为integer[unit]，其中integer表示时间长度，unit表示时间单位。合法的unit单位为：d（天）、h（小时）、m（分钟）、s（秒）。7d或者604800s均表示7天的周期。

  • 当密钥为默认密钥时，取值为365天。

  • 当密钥为软件密钥时，取值为7~365天。

  • 当密钥为硬件密钥时，不支持自动轮转。

说明

当EnableAutomaticRotation参数为true时，必须设置此参数。

KeySpec

String

否

Aliyun_AES_256

密钥规格，不同密钥管理类型的取值不同。关于密钥规格、遵循的标准、密钥算法的详细介绍，请参见密钥管理类型和密钥规格。

说明

不输入参数值时，密钥规格默认为Aliyun_AES_256。

DKMSInstanceId

String

否

kst-bjj62d8f5e0sgtx8h****

KMS实例的实例ID。

说明

当您需要为KMS实例创建密钥时，必须指定本参数。当您需要创建默认密钥（主密钥）时，不需要指定本参数。

Tags

String

否

[{"TagKey":"disk-encryption","TagValue":"true"}]

为密钥绑定标签。每个标签由一个键值对（Key:Value）组成，包含标签键（Key）、标签值（Value）。

最多输入20个标签。输入多个标签时，格式为[{"TagKey":"key1","TagValue":"value1"},{"TagKey":"key2","TagValue":"value2"},...]。

每个标签键（Key）和每个标签值（Value）最多支持128个字符，可以包含英文大小写字母、数字、正斜线（/）、反斜线（\）、下划线（_）、短划线（-）、半角句号（.）、加号（+）、等于号（=）、半角冒号（:）、字符at（@）。

说明

标签键不能以aliyun和acs:开头。

Policy

String

否

{"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"}

密钥策略的具体内容，JSON格式。最大长度为32768个字节。

关于密钥策略的详细介绍，请参见密钥策略概述。不输入该参数时，使用默认凭据策略。

密钥策略内容包含：

  • Version：密钥策略的版本，目前版本仅支持设置为1。

  • Statement：密钥策略的语句，每个密钥策略包含一个或多个语句。

密钥策略格式为：

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

Statement详细介绍：

  • Sid：可选，表示自定义的语句标识符。内容长度小于等于128字符，支持的字符为：大写英文字母（A-Z）、小写英文字母（a-z）、数字（0-9），特殊字符（ _/+=.@-）。

  • Effect：必选，表示是允许还是拒绝该策略语句中的权限。取值为：Allow或Deny。

  • Principal：必选，表示权限策略的授权主体，支持设置为当前阿里云账号（即密钥所属的阿里云账号），当前阿里云账号下的RAM用户、RAM角色，其他阿里云账号下的RAM用户、RAM角色。

  • Action：必选，表示要允许或拒绝的API操作，内容必须以"kms:"开头。操作权限列表的范围，请参见密钥策略概述。如果您设置了列表外的操作，设置后也不会生效。

  • Resource：必选，取值只能是*，表示本KMS密钥。

说明

授权给其他阿里云账号下的RAM用户、RAM角色后，您仍需在访问控制RAM侧，使用该RAM用户、RAM角色的阿里云账号为其授权使用该密钥，RAM用户、RAM角色才能使用该密钥。集体操作，请参见密钥管理服务自定义权限策略参考、为RAM用户授权、为RAM角色授权。

关于公共请求参数的详情，请参见公共参数。

返回数据

名称

类型

示例值

描述

RequestId

String

381D5D33-BB8F-395F-8EE4-AE3BB4B523C4

本次调用请求的ID，是由阿里云为该请求生成的唯一标识符，可用于排查和定位问题。

KeyMetadata

Object

密钥的元数据。

KeyId

String

key-hzz62f1cb66fa42qo****

密钥的全局唯一标识符。

NextRotationDate

String

2024-03-25T10:00:00Z

密钥下一次轮转的时间。

仅当AutomaticRotation参数值为Enabled或Suspended时，才返回该值。

KeyState

String

Enabled

密钥的状态。

更多信息，请参见用户主密钥的状态对API调用的影响。

RotationInterval

String

31536000s

密钥自动轮转的周期。单位为秒，格式为整数值后加上字符s。例如：7天的轮转周期为604800s。

仅当AutomaticRotation参数值为Enabled或Suspended时，才返回该值。

Arn

String

acs:kms:cn-qingdao:154035569884****:key/key-hzz62f1cb66fa42qo****

密钥的ARN。

Creator

String

154035569884****

密钥的创建者。

LastRotationDate

String

2023-03-25T10:00:00Z

最近一次轮转的时间（UTC）。

如果是新创建密钥，则为初始密钥版本生成时间。

DeleteDate

String

2025-03-25T10:00:00Z

密钥的预计删除时间。 更多信息，请参见ScheduleKeyDeletion。

仅当KeyState值为PendingDeletion时，才返回该参数。

PrimaryKeyVersion

String

7ce1d081-06cb-42e6-aab6-5c5de030****

密钥的当前主版本标识符。

Description

String

key description example

密钥的描述。

KeySpec

String

Aliyun_AES_256

密钥的规格。

Origin

String

Aliyun_KMS

密钥材料来源。

MaterialExpireTime

String

2025-03-25T10:00:00Z

密钥材料的过期时间（UTC）。

当该值为空时，表示密钥材料不会过期。

AutomaticRotation

String

Enabled

是否开启了密钥自动轮转，取值：

  • Enabled：自动轮转处于开启状态。

  • Disabled：自动轮转处于未开启状态。

  • Suspended：自动轮转被暂停执行。

ProtectionLevel

String

SOFTWARE

密钥的保护级别。

KeyUsage

String

ENCRYPT/DECRYPT

密钥的用途。

CreationDate

String

2024-03-25T10:00:00Z

密钥创建的日期和时间（UTC）。

DKMSInstanceId

String

kst-bjj62d8f5e0sgtx8h****

KMS实例的实例ID。

示例

请求示例

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"}
&公共请求参数

正常返回示例

XML格式

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格式

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****"
  }
}

错误码

HttpCode

错误码

错误信息

描述

400

Rejected.LimitExceeded

The request was rejected because user create resource limit was exceeded

创建的资源达到上限，请求被拒绝。

400

InvalidParameter

The specified parameter is not valid.

参数非法。

400

UnsupportedOperation

This action is not supported.

不支持的操作

400

Forbidden.NoPermission

This operation is forbidden by permission system.

该操作无权限

400

Rejected.ShareQuotaExceedLimit

Instance Share Quota Exceed Limit.

实例份额配额超过限制。

403

Forbidden.DKMSInstanceNotFound

The specified DKMS Instance is not found.

您指定的专属kms实例未找到。

500

InternalFailure

Internal Failure

内部错误

503

SerivceUnvailableTemporary

Service Unvailable Temporary

服务临时不可用。

访问错误中心查看更多错误码。

上一篇：密钥下一篇：GetParametersForImport
文档推荐
  • 本页导读 （1）