调用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两者之一，单个密钥无法同时支持两种操作。

调试

您可以在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

默认值：SOFTWARE

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

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

  • true
  • false

默认值：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_AES_256。

  • 仅专属KMS支持Aliyun_AES_128和Aliyun_AES_192。
DKMSInstanceId String 否 kst-bjj62d8f5e0sgtx8h****

专属KMS实例的实例ID。

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

返回数据

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

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

主密钥的Metadata。
KeyId String d6bee1cb-2e14-4277-ba6b-73786b21****

主密钥的全局唯一标识符。
NextRotationDate String 2022-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 2022-06-06T18:22:03Z

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

如果是新创建密钥，则为初始密钥版本生成时间。
DeleteDate String 2022-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 2022-07-06T18:22:03Z

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

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

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

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

密钥的保护级别。
KeyUsage String ENCRYPT/DECRYPT

主密钥的用途。
CreationDate String 2022-03-25T10:42:40Z

创建主密钥的日期和时间（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=false
&RotationInterval=365d
&KeySpec=Aliyun_AES_256
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&公共请求参数

正常返回示例

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>2022-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>2022-06-06T18:22:03Z</LastRotationDate>
        <DeleteDate>2022-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>2022-07-06T18:22:03Z</MaterialExpireTime>
        <AutomaticRotation>Disabled</AutomaticRotation>
        <ProtectionLevel>SOFTWARE</ProtectionLevel>
        <KeyUsage>ENCRYPT/DECRYPT</KeyUsage>
        <CreationDate>2022-03-25T10:42:40Z</CreationDate>
        <DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
    </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" : "2022-07-06T18:22:03Z",
    "KeyState" : "Enabled",
    "RotationInterval" : "31536000s",
    "Arn" : "acs:kms:cn-qingdao:154035569884****:key/d6bee1cb-2e14-4277-ba6b-73786b21****",
    "Creator" : "154035569884****",
    "LastRotationDate" : "2022-06-06T18:22:03Z",
    "DeleteDate" : "2022-07-06T18:22:03Z",
    "PrimaryKeyVersion" : "7ce1d081-06cb-42e6-aab6-5c5de030****",
    "Description" : "key description example",
    "KeySpec" : "Aliyun_AES_256",
    "Origin" : "Aliyun_KMS",
    "MaterialExpireTime" : "2022-07-06T18:22:03Z",
    "AutomaticRotation" : "Disabled",
    "ProtectionLevel" : "SOFTWARE",
    "KeyUsage" : "ENCRYPT/DECRYPT",
    "CreationDate" : "2022-03-25T10:42:40Z",
    "DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
  }
}

错误码

HttpCode 错误码 错误信息 描述
400 InvalidParameter The specified parameter is not valid. 参数非法。
404 InvalidAccessKeyId.NotFound The Access Key ID provided does not exist in our records. 提供的 Access Key ID不存在

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