全部产品
Search
文档中心

密钥管理服务:CreateSecret

更新时间:Sep 11, 2024

创建凭据并存入凭据的初始版本。

您需要指定凭据名称、初始版本的凭据值和版本号。初始版本的状态被标记为ACSCurrent。

KMS使用您指定的密钥对凭据值进行加密保护,密钥和凭据需要属于同一个KMS实例,且密钥必须为对称密钥。

说明 KMS对每个版本的凭据值进行加密,凭据名称、版本号、版本的状态标记等元数据不会被加密。

您对凭据值进行加密前,需要具备密钥的kms:GenerateDataKey权限。

本文将提供一个示例,创建一个名称为mydbconninfo、初始版本号VersionIdv1、凭据值SecretData{"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}的RDS凭据。

调试

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

请求参数

名称

类型

是否必选

示例值

描述

Action String CreateSecret

要执行的操作。取值:CreateSecret

SecretName String mydbconninfo

凭据名称。 凭据名称在当前地域下唯一。

长度不超过192个字符,可包含英文字母、数字、下划线(_)、正斜线(/)、加号(+)、等号(=)、半角句号(.)、短划线(-)和字符(@)。不同类型的凭据名称要求如下:

  • 当SecretType取值为Generic(通用凭据)、Rds(RDS凭据)、Redis(Redis/Tair凭据)时,不能以acs/开头。
  • 当SecretType取值为RAMCredentials(RAM凭据)时,使用固定值$Auto。此时KMS自动生成凭据名称,以acs/ram/user/开头,包含RAM用户显示名称。
  • 当SecretType取值为ECS(ECS凭据)时,必须以acs/ecs/开头。
VersionId String v1

初始版本的版本号,版本号在该凭据内唯一。

长度不超过64个字符。

EncryptionKeyId String key-gzz63ff0db5hg3qje****

用于加密凭据值的密钥ID。

说明 密钥和凭据需要属于同一个KMS实例,且密钥必须为对称密钥。
SecretData String {"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}

凭据值。长度不超过30720字节(30KB)。KMS使用指定的密钥对其加密后,存入初始版本中。

  • 当SecretType取值为Generic(通用凭据)时,您可以自定义凭据值。
  • 当SecretType取值为Rds(RDS凭据)时,凭据值格式为:{"Accounts":[{"AccountName":"","AccountPassword":""}]}。其中,AccountName为RDS实例的账号名称,AccountPassword为RDS实例的账号口令。
  • 当SecretType取值为Redis(Redis凭据)时,凭据值格式为:{"Accounts":[{"AccountName":"","AccountPassword":""}]}。其中,AccountName为Redis实例的账号名称,AccountPassword为Redis实例的账号口令。
  • 当SecretType取值为RAMCredentials(RAM凭据)时,凭据值格式为:{"AccessKeys":[{"AccessKeyId":"","AccessKeySecret":""}]}。其中,AccessKeyId是访问密钥ID,AccessKeySecret是访问密钥内容。您需要指定RAM用户的所有AccessKey。
  • 当SecretType取值为ECS(ECS凭据)时,凭据值格式为:
    • 当ExtendedConfig参数中SecretSubType取值为Password时:{"UserName":"","Password": ""}。其中,UserName为登录ECS实例的用户名,Password为登录ECS实例的密码。
    • 当ExtendedConfig参数中SecretSubType取值为SSHKey时:{"UserName":"","PublicKey": "", "PrivateKey": ""}。其中,PublicKey为登录ECS实例的SSH格式公钥,PrivateKey为登录ECS实例的私钥。
SecretDataType String text

凭据值类型。取值:

  • text(默认值):文本类型
  • binary:二进制类型
说明 当SecretType取值为Rds、Redis、RAMCredentials或ECS时,SecretDataType取值只能为text。
Description String mydbinfo

凭据的描述信息。

Tags String [{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]

凭据的标签。每个标签由一个键值对(Key:Value)组成,包含标签键(Key)、标签值(Value)。

标签建和标签值的格式:最多支持128个字符,可以包含英文大小写字母、数字、正斜线(/)、反斜线(\)、下划线(_)、短划线(-)、半角句号(.)、加号(+)、等于号(=)、半角冒号(:)、字符at(@)。

  • 标签键不能以aliyun或acs:开头。
  • 每个凭据最多可以设置20个标签键值对。
SecretType String Rds

凭据类型。取值:

  • Generic(默认值):通用凭据。
  • Rds:RDS凭据。
  • Redis:Redis凭据。
  • RAMCredentials:RAM凭据。
  • ECS:ECS凭据。
ExtendedConfig Map {"SecretSubType":"SingleUser", "DBInstanceId":"rm-bp1b3dd3a506e****" ,"CustomData":{"Key1": "v1", "fds":"fdsf"}}

凭据的拓展配置,用于指定特定凭据类型的属性。长度不超过1024个字符。

  • 当SecretType取值为Generic(通用凭据)时,忽略该参数。
  • 当SecretType取值为Rds(RDS凭据)时,需要指定ExtendedConfig的如下参数:
    • SecretSubType(必填):凭据子类型。取值:
      • SingleUser:指定凭据管家以单账号模式RDS凭据。凭据轮转时,指定账号的口令会被重置为新的随机口令。
      • DoubleUsers:指定凭据管家以双账号模式RDS凭据,ACSCurrent和ACSPrevious分别引用其中一个账号。凭据轮转时,ACSPrevious引用账号的口令会被重置为新的随机口令,随后凭据管家交换ACSCurrent和ACSPrevious对RDS账号的引用。
    • DBInstanceId(必填):指定RDS账号所在的RDS实例ID。
    • CustomData(可选):自定义数据。取值为JSON格式的键值对,最多不超过10个键值对,多个键值对用半角逗号(,)间隔。取值示例:{"Key1": "v1", "fds":"fdsf"}。默认值为空{}
  • 当SecretType取值为Redis(Redis凭据)时,需要指定ExtendedConfig的如下参数:
    • SecretSubType(必填):凭据子类型。取值:
      • DoubleUsers:指定凭据管家以双账号模式Redis凭据,ACSCurrent和ACSPrevious分别引用其中一个账号。凭据轮转时,ACSPrevious引用账号的口令会被重置为新的随机口令,随后凭据管家交换ACSCurrent和ACSPrevious对Redis账号的引用。
    • AccountName(必填):数据库用户名。
    • CloneAccountName(必填):数据库用户名,为AccountName加上后缀_clone
    • AccountPrivilege(必填):访问数据库的权限。
    • InstanceId(必填):Redis实例ID。
    • RegionId(必填):Redis实例所在地域ID。
    • CustomData(可选):自定义数据。取值为JSON格式的键值对,最多不超过10个键值对,多个键值对用半角逗号(,)间隔。取值示例:{"Key1": "v1", "fds":"fdsf"}。默认值为空{}
  • 当SecretType取值为RAMCredentials(RAM凭据)时,需要指定ExtendedConfig的如下参数:
    • SecretSubType(必填):凭据子类型。取值: RamUserAccessKey。
    • UserName(必填):RAM用户名称。
    • CustomData(可选):自定义数据。取值为JSON格式的键值对,最多不超过10个键值对,多个键值对用半角逗号(,)间隔。默认值为空{}
  • 当SecretType取值为ECS(ECS凭据)时,需要指定ExtendedConfig的如下参数:
    • SecretSubType(必填):凭据子类型。取值:
      • Password:ECS口令。
      • SSHKey:ECS SSH公私钥。
    • RegionId(必填):ECS实例所在地域ID。
    • InstanceId(必填):ECS实例ID。
    • CustomData(可选):自定义数据。取值为JSON格式的键值对,最多不超过10个键值对,多个键值对用半角逗号(,)间隔。默认值为空{}
说明 当SecretType取值为Rds、Redis、RAMCredentials或ECS时,必须设置该参数。
EnableAutomaticRotation Boolean true

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

  • true:开启自动轮转。
  • false(默认值):不开启自动轮转。
说明 当SecretType取值为Rds(RDS凭据)、Redis(Redis凭据)、RAMCredentials(RAM凭据)或ECS(ECS凭据)时,该参数有效。当SecretType取值为Generic(通用凭据)时,不支持自动轮转,您可通过PutSecretValue操作手工轮转。
RotationInterval String 30d

自动轮转的周期。取值范围:6小时~8,760小时(365天)。

格式为integer[unit],其中integer表示时间长度,unit表示时间单位。

unit取值:d(天)、h(小时)、m(分钟)、s(秒)。例如:7d或者604,800s均表示7天的周期。

说明 仅当EnableAutomaticRotation取值为true时,必须设置该参数,否则无需设置。
DKMSInstanceId String kst-bjj62d8f5e0sgtx8h****

KMS实例的实例ID。

Policy String {"Version":"1","Statement": [{"Sid":"kms default secret policy","Effect":"Allow","Principal":{"RAM": ["acs:ram::119285303511****:*"]},"Action":["kms:*"],"Resource": ["*"] }] }

凭据策略的具体内容,JSON格式。最大长度为32768个字节。

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

凭据策略内容包含:

  • Version:凭据策略的版本,目前版本仅支持设置为1。
  • Statement:凭据策略的语句,每个凭据策略包含一个或多个语句。

凭据策略格式为:

{
    "Version": "1",
    "Statement": [
        {
            "Sid": "Enable RAM User Permissions",
            "Effect": "Allow",
            "Principal": {
              "RAM": ["acs:ram::123456789012: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凭据。
  • Condition:可选,表示授权生效的限制条件。通过使用条件可以评估API请求的上下文,以确定策略语句是否适用。格式为"Condition": {"condition operator": {"condition key": "condition value"}}。详细介绍,请参见凭据策略概述
说明 授权给其他阿里云账号下的RAM用户、RAM角色后,您仍需在访问控制RAM侧,使用该RAM用户、RAM角色的阿里云账号为其授权使用该凭据,RAM用户、RAM角色才能使用该凭据。集体操作,请参见密钥管理服务自定义权限策略参考为RAM用户授权为RAM角色授权

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

返回数据

名称

类型

示例值

描述

RequestId String 3bf02f7a-015b-4f93-be0f-cc043fda2dd3

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

AutomaticRotation String Enabled

是否开启自动轮转。取值:

  • Enabled:开启自动轮转。
  • Disabled:不开启自动轮转。
  • Invalid:轮转状态异常,凭据管家无法为您自动轮转。
说明 SecretType取值为Rds、Redis、RAMCredentials或ECS时,返回该参数。
SecretName String mydbconninfo

凭据名称。

VersionId String v1

凭据版本号。

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

下一次轮转的时间。

说明 当自动轮转开启时,返回该参数。
SecretType String Rds

凭据类型。取值:

  • Generic:通用凭据。
  • Rds:RDS凭据。
  • Redis:Redis凭据。
  • RAMCredentials:RAM凭据。
  • ECS:ECS凭据。
RotationInterval String 604800s

凭据自动轮转的周期。

格式为integer[unit],其中integer表示时间长度,unit表示时间单位。 unit取值:s(秒)。例如:7天的轮转周期为604800s。

说明 当自动轮转开启时,返回该参数。
Arn String acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo

阿里云资源名称。

ExtendedConfig String {\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\", \"CustomData\":"Key1": "v1", "fds":"fdsf"} }

凭据的拓展配置。

说明 当SecretType取值为Rds、Redis、RAMCredentials或ECS时,返回该参数。
DKMSInstanceId String kst-bjj62d8f5e0sgtx8h****

KMS实例的实例ID。

示例

请求示例

http(s)://[Endpoint]/?Action=CreateSecret
&SecretName=mydbconninfo
&VersionId=v1
&EncryptionKeyId=key-gzz63ff0db5hg3qje****
&SecretData={"Accounts":[{"AccountName":"user1","AccountPassword":"****"}]}
&SecretDataType=text
&Description=mydbinfo
&Tags=[{\"TagKey\":\"key1\",\"TagValue\":\"val1\"},{\"TagKey\":\"key2\",\"TagValue\":\"val2\"}]
&SecretType=Rds
&EnableAutomaticRotation=true
&RotationInterval=30d
&DKMSInstanceId=kst-bjj62d8f5e0sgtx8h****
&Policy={"Version":"1","Statement": [{"Sid":"kms default secret policy","Effect":"Allow","Principal":{"RAM": ["acs:ram::119285303511****:*"]},"Action":["kms:*"],"Resource": ["*"] }] }
&公共请求参数

正常返回示例

XML格式

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

<CreateSecretResponse>
    <RequestId>3bf02f7a-015b-4f93-be0f-cc043fda2dd3</RequestId>
    <AutomaticRotation>Enabled</AutomaticRotation>
    <SecretName>mydbconninfo</SecretName>
    <VersionId>v1</VersionId>
    <NextRotationDate>2023-07-06T18:22:03Z</NextRotationDate>
    <SecretType>Rds</SecretType>
    <RotationInterval>604800s</RotationInterval>
    <Arn>acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo</Arn>
    <ExtendedConfig>{\"SecretSubType\":\"SingleUser\", \"DBInstanceId\":\"rm-uf667446pc955****\",  \"CustomData\":"Key1": "v1", "fds":"fdsf"} }</ExtendedConfig>
    <DKMSInstanceId>kst-bjj62d8f5e0sgtx8h****</DKMSInstanceId>
</CreateSecretResponse>

JSON格式

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

{
  "RequestId" : "3bf02f7a-015b-4f93-be0f-cc043fda2dd3",
  "AutomaticRotation" : "Enabled",
  "SecretName" : "mydbconninfo",
  "VersionId" : "v1",
  "NextRotationDate" : "2023-07-06T18:22:03Z",
  "SecretType" : "Rds",
  "RotationInterval" : "604800s",
  "Arn" : "acs:kms:cn-hangzhou:154035569884****:secret/mydbconninfo",
  "ExtendedConfig" : "{\\\"SecretSubType\\\":\\\"SingleUser\\\", \\\"DBInstanceId\\\":\\\"rm-uf667446pc955****\\\",  \\\"CustomData\\\":\"Key1\": \"v1\", \"fds\":\"fdsf\"} }",
  "DKMSInstanceId" : "kst-bjj62d8f5e0sgtx8h****"
}

错误码

HttpCode

错误码

错误信息

描述

400 UnsupportedOperation This action is not supported. 不支持的操作
400 Rejected.LimitExceeded The request was rejected because user create resource limit was exceeded 创建的资源达到上限,请求被拒绝。
400 InvalidParameter The specified parameter is not valid. 参数非法。
400 Rejected.ShareQuotaExceedLimit Instance Share Quota Exceed Limit. 实例份额配额超过限制。
403 Forbidden.DKMSInstanceNotFound The specified DKMS Instance is not found. 您指定的专属kms实例未找到。
404 Forbidden.ResourceNotFound The resource is not found. 资源不存在。
409 Rejected.ResourceExist The resource already exists. 资源已存在。
409 Rejected.ResourceInDeleteWindow The secret is planned to be deleted. 此凭据在计划删除中
500 InternalFailure Internal Failure 内部错误

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