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

使用说明

主密钥可以是对称密钥或非对称密钥。对称密钥主要用于生成可以加密大量数据的DataKey,有时也直接用于加密少量数据(少于6KB)。更多信息,请参见GenerateDataKey。非对称密钥用于加密解密或签名验签,但无法生成数据密钥。

各种密钥类型支持的操作如下表所示:

密钥类型

密钥规格

说明

加密解密

签名验签

对称密钥

Aliyun_AES_256

AES密钥,长度为256比特

支持

不支持

对称密钥

Aliyun_AES_128

AES密钥,长度为128比特。仅专属KMS支持该密钥规格。

支持

不支持

对称密钥

Aliyun_AES_192

AES密钥,长度为192比特。仅专属KMS支持该密钥规格。

支持

不支持

对称密钥

Aliyun_SM4

SM4密钥

支持

不支持

非对称密钥

RSA_2048

RSA密钥,模长为2048比特

支持

支持

非对称密钥

RSA_3072

RSA密钥,模长为3072比特

支持

支持

非对称密钥

EC_P256

NIST推荐椭圆曲线P-256(secp256r1)

不支持

支持

非对称密钥

EC_P256K

SECG椭圆曲线secp256k1

不支持

支持

非对称密钥

EC_SM2

GBT32918定义的素数域256位椭圆曲线

支持

支持

说明
  • 对称密钥KeySpec在标准密钥类型前加上Aliyun_前缀,表示使用标准密钥的密码算法,但是会生成非标准密文;非对称密钥产生标准密文或者签名。
  • RSA密钥使用方式仅支持ENCRYPT/DECRYPT、SIGN/VERIFY两者之一,单个密钥无法同时支持两种操作。

  • SM4和SM2为中国国家密码管理局批准的密码算法,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(默认值)
  • EXTERNAL
说明
  • 请注意区分大小写。
  • 当KeySpec为非对称密钥类型时禁止选择EXTERNAL。
  • 如果选择EXTERNAL,您需要导入密钥材料
ProtectionLevel String SOFTWARE

密钥的保护级别,取值:

  • SOFTWARE(默认值)
  • HSM
说明
  • 请注意区分大小写。
  • 当取值为HSM时,如果Origin参数为Aliyun_KMS,则会在托管密码机中生成密钥,用于执行密码运算;如果Origin参数为EXTERNAL,您可以将外部密钥导入到托管密码机中,用于执行密码运算。
EnableAutomaticRotation Boolean false

是否开启自动密钥轮转,取值:

  • true
  • false(默认值)
说明 若Origin为EXTERNAL或KeySpec为非对称密钥类型则无法支持自动轮转。
RotationInterval String 365d

自动轮转的时间周期。格式为integer[unit],其中integer表示时间长度,unit表示时间单位。合法的unit单位为:d(天)、h(小时)、m(分钟)、s(秒)。7d或者604800s均表示7天的周期。取值范围:7~730天。

说明 当EnableAutomaticRotation参数为true时,必须设置此参数;否则,将忽略此参数。
KeySpec String Aliyun_AES_256

密钥规格,取值:

  • Aliyun_AES_256
  • Aliyun_AES_128
  • Aliyun_AES_192
  • Aliyun_SM4
  • RSA_2048
  • RSA_3072
  • EC_P256
  • EC_P256K
  • EC_SM2
说明
  • 在中国内地使用托管密码机创建的密钥,默认为Aliyun_SM4类型,其余情况下默认为Aliyun_AES_256。

  • 仅专属KMS支持Aliyun_AES_128和Aliyun_AES_192。

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

返回数据

名称 类型 示例值 描述
RequestId String 36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06

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

KeyMetadata Object

主密钥的Metadata。

KeyId String d6bee1cb-2e14-4277-ba6b-73786b21****

主密钥的全局唯一标识符。

NextRotationDate String 2020-07-06T18:22:03Z

下一次轮转的时间。

说明 只有当AutomaticRotation参数值为Enabled或Suspended时,才返回该值。
KeyState String Enabled

主密钥的状态。

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

RotationInterval String 31536000s

密钥自动轮转的周期(秒数)。格式为整数值后加上字符s。例如:7天的轮转周期为604800s。只有当AutomaticRotation参数值为Enabled或Suspended时,才返回该值。

Arn String acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****

主密钥ARN。

Creator String 154035569884****

主密钥创建者。

LastRotationDate String 2019-06-06T18:22:03Z

最近一次轮转的时间(UTC)。

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

DeleteDate String 2020-07-06T18:22:03Z

主密钥的预计删除时间。

更多信息,请参见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 2020-07-06T18:22:03Z

密钥材料的过期时间(UTC)。

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

AutomaticRotation String Disabled

是否开启自动密钥轮转,取值:

  • Enabled:自动轮转处于开启状态。
  • Disabled:自动轮转处于未开启状态。
  • Suspended:自动轮转被暂停执行。更多信息,请参见自动轮转密钥
说明 仅适用于对称类型的主密钥,非对称类型的主密钥不支持自动轮转。
ProtectionLevel String SOFTWARE

密钥的保护级别。

KeyUsage String ENCRYPT/DECRYPT

主密钥的用途。

CreationDate String 2016-03-25T10:42:40Z

创建主密钥的日期和时间(UTC)。

示例

请求示例

http(s)://[Endpoint]/?Action=CreateKey
&Description=key description example
&KeyUsage=ENCRYPT/DECRYPT
&Origin=Aliyun_KMS
&ProtectionLevel=SOFTWARE
&EnableAutomaticRotation=false
&RotationInterval=365d
&KeySpec=Aliyun_AES_256
&公共请求参数

正常返回示例

XML格式

HTTP/1.1 200 OK
Content-Type:application/xml

<CreateKeyResponse>
    <RequestId>36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06</RequestId>
    <KeyMetadata>
        <KeyId>d6bee1cb-2e14-4277-ba6b-73786b21****</KeyId>
        <NextRotationDate>2020-07-06T18:22:03Z</NextRotationDate>
        <KeyState>Enabled</KeyState>
        <RotationInterval>31536000s</RotationInterval>
        <Arn>acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****</Arn>
        <Creator>154035569884****</Creator>
        <LastRotationDate>2019-06-06T18:22:03Z</LastRotationDate>
        <DeleteDate>2020-07-06T18:22:03Z</DeleteDate>
        <PrimaryKeyVersion>7ce1d081-06cb-42e6-aab6-5c5de030****</PrimaryKeyVersion>
        <Description>key description example</Description>
        <KeySpec>Aliyun_AES_256</KeySpec>
        <Origin>Aliyun_KMS</Origin>
        <MaterialExpireTime>2020-07-06T18:22:03Z</MaterialExpireTime>
        <AutomaticRotation>Disabled</AutomaticRotation>
        <ProtectionLevel>SOFTWARE</ProtectionLevel>
        <KeyUsage>ENCRYPT/DECRYPT</KeyUsage>
        <CreationDate>2016-03-25T10:42:40Z</CreationDate>
    </KeyMetadata>
</CreateKeyResponse>

JSON格式

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "36c7e41a-3f2c-45f7-9bdd-d1dc1e7e7e06",
  "KeyMetadata" : {
    "KeyId" : "d6bee1cb-2e14-4277-ba6b-73786b21****",
    "NextRotationDate" : "2020-07-06T18:22:03Z",
    "KeyState" : "Enabled",
    "RotationInterval" : "31536000s",
    "Arn" : "acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****",
    "Creator" : "154035569884****",
    "LastRotationDate" : "2019-06-06T18:22:03Z",
    "DeleteDate" : "2020-07-06T18:22:03Z",
    "PrimaryKeyVersion" : "7ce1d081-06cb-42e6-aab6-5c5de030****",
    "Description" : "key description example",
    "KeySpec" : "Aliyun_AES_256",
    "Origin" : "Aliyun_KMS",
    "MaterialExpireTime" : "2020-07-06T18:22:03Z",
    "AutomaticRotation" : "Disabled",
    "ProtectionLevel" : "SOFTWARE",
    "KeyUsage" : "ENCRYPT/DECRYPT",
    "CreationDate" : "2016-03-25T10:42:40Z"
  }
}

错误码

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