全部產品
Search

搜尋本產品

    ：CreateKey

    文件中心

    ：CreateKey

    更新時間：Jan 22, 2025

    調用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": [
        "*"
      ],
      "Condition": {
        "condition operator": {
          "condition key": "condition value"
        }
      }
    }
  ]
}

    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角色才能使用該密鑰。集體操作，請參見Key Management Service自訂權限原則參考、為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 服務臨時不可用。

    訪問錯誤中心查看更多錯誤碼。