doc-exports/docs/kms/api-ref/kms_02_0028.html
Li, Qiao dfe65b9551 KMS API 20230817 version.
Reviewed-by: Belejkanic, Lukas <lukas.belejkanic@t-systems.com>
Co-authored-by: Li, Qiao <qiaoli@huawei.com>
Co-committed-by: Li, Qiao <qiaoli@huawei.com>
2024-04-02 13:42:22 +00:00

196 lines
19 KiB
HTML

<a name="kms_02_0028"></a><a name="kms_02_0028"></a>
<h1 class="topictitle1">Creating a Grant</h1>
<div id="body1497317398920"><div class="section" id="kms_02_0028__en-us_topic_0112992333_section37533920154934"><h4 class="sectiontitle">Function</h4><p id="kms_02_0028__en-us_topic_0112992333_p30759225155040">This API enables you to create a grant to grant permissions on a CMK to a user so that the user can perform operations on the CMK.</p>
<div class="note" id="kms_02_0028__en-us_topic_0112992333_note324568691063"><img src="public_sys-resources/note_3.0-en-us.png"><span class="notetitle"> </span><div class="notebody"><p id="kms_02_0028__en-us_topic_0112992333_p268776511065">A Default Master Key (the alias suffix of which is <strong id="kms_02_0028__en-us_topic_0112992333_b842352706103952">/default</strong>) does not allow permission granting.</p>
</div></div>
</div>
<div class="section" id="kms_02_0028__en-us_topic_0112992333_section37627629154934"><h4 class="sectiontitle">URI</h4><ul id="kms_02_0028__en-us_topic_0112992333_ul27939100154934"><li id="kms_02_0028__en-us_topic_0112992333_li50125315154934">URI format<p id="kms_02_0028__en-us_topic_0112992333_p48474652154934"><a name="kms_02_0028__en-us_topic_0112992333_li50125315154934"></a><a name="en-us_topic_0112992333_li50125315154934"></a>POST /v1.0/{project_id}/kms/create-grant</p>
</li><li id="kms_02_0028__en-us_topic_0112992333_li34132757154934">Parameter description
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="kms_02_0028__en-us_topic_0112992333_table38759358154934" frame="border" border="1" rules="all"><caption><b>Table 1 </b>Parameter description</caption><thead align="left"><tr id="kms_02_0028__en-us_topic_0112992333_row60644171154934"><th align="left" class="cellrowborder" valign="top" width="22.74%" id="mcps1.3.2.2.2.1.2.5.1.1"><p id="kms_02_0028__en-us_topic_0112992333_p13230838154934"><strong id="kms_02_0028__en-us_topic_0112992333_b842352706191249">Parameter</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="16.919999999999998%" id="mcps1.3.2.2.2.1.2.5.1.2"><p id="kms_02_0028__en-us_topic_0112992333_p65064970154934"><strong id="kms_02_0028__en-us_topic_0112992333_b842352706191255">Mandatory</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="19.55%" id="mcps1.3.2.2.2.1.2.5.1.3"><p id="kms_02_0028__en-us_topic_0112992333_p35771181154934">Type</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="40.79%" id="mcps1.3.2.2.2.1.2.5.1.4"><p id="kms_02_0028__en-us_topic_0112992333_p11784586154934">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="kms_02_0028__en-us_topic_0112992333_row15027399154934"><td class="cellrowborder" valign="top" width="22.74%" headers="mcps1.3.2.2.2.1.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p9259788154934">project_id</p>
</td>
<td class="cellrowborder" valign="top" width="16.919999999999998%" headers="mcps1.3.2.2.2.1.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p11845378154934">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="19.55%" headers="mcps1.3.2.2.2.1.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p4386100291125">String</p>
</td>
<td class="cellrowborder" valign="top" width="40.79%" headers="mcps1.3.2.2.2.1.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p5464351154934">Project ID</p>
</td>
</tr>
</tbody>
</table>
</div>
</li></ul>
</div>
<div class="section" id="kms_02_0028__en-us_topic_0112992333_section49179167154934"><h4 class="sectiontitle">Requests</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="kms_02_0028__en-us_topic_0112992333_table5096792154934" frame="border" border="1" rules="all"><caption><b>Table 2 </b>Request parameters</caption><thead align="left"><tr id="kms_02_0028__en-us_topic_0112992333_row37570371154934"><th align="left" class="cellrowborder" valign="top" width="17%" id="mcps1.3.3.2.2.5.1.1"><p id="kms_02_0028__en-us_topic_0112992333_p114081546134418"><strong id="kms_02_0028__en-us_topic_0112992333_b252108086">Parameter</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="16%" id="mcps1.3.3.2.2.5.1.2"><p id="kms_02_0028__en-us_topic_0112992333_p9408546124415"><strong id="kms_02_0028__en-us_topic_0112992333_b664774389">Mandatory</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="17%" id="mcps1.3.3.2.2.5.1.3"><p id="kms_02_0028__en-us_topic_0112992333_p164081146134413">Type</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="50%" id="mcps1.3.3.2.2.5.1.4"><p id="kms_02_0028__en-us_topic_0112992333_p10408194611444">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="kms_02_0028__en-us_topic_0112992333_row3735252154934"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p5492758715522">key_id</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p530110015522">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p3346736533">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p2673593115522">36-byte ID of a CMK that matches the regular expression <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue80435593163333"><b>^[0-9a-z]{8}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{4}-[0-9a-z]{12}$</b></span></p>
<p id="kms_02_0028__en-us_topic_0112992333_p5898392715522">Example: 0d0466b0-e727-4d9c-b35d-f84bb474a37f</p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row2233745154934"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p4383626015522">grantee_principal</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p4822598815522">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p16572391317">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p1538695162811">Indicates the ID of the authorized user. The value is between 1 to 64 bytes and meets the regular expression <strong id="kms_02_0028__en-us_topic_0112992333_b112401647135813">"^[a-zA-Z0-9]{1,64}$"</strong>.</p>
<p id="kms_02_0028__en-us_topic_0112992333_p5880995015522">Example: 0d0466b00d0466b00d0466b00d0466b0</p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row23632615154934"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p1108616615530">operations</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p5743624615530">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p1941514414456">Array of strings</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p34245185181036">Permissions that can be granted</p>
<p id="kms_02_0028__en-us_topic_0112992333_p58016892181046">Values: <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname711983078104314"><b>create-datakey</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname1476402418104314"><b>create-datakey-without-plaintext</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname833542488104314"><b>encrypt-datakey</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname876101735104314"><b>decrypt-datakey</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname150410567104314"><b>describe-key</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname1533829523104314"><b>create-grant</b></span>, <span class="parmname" id="kms_02_0028__en-us_topic_0112992333_parmname1728175126175753"><b>retire-grant</b></span></p>
<p id="kms_02_0028__en-us_topic_0112992333_p2182438615530"><span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue1365452364619"><b>create-grant</b></span> cannot be the only value.</p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row20487414155231"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p517669515530">name</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p721574715530">No</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p16985457636">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p4760460115530">Name of a grant which can be 1 to 255 characters in length and matches the regular expression <strong id="kms_02_0028__en-us_topic_0112992333_b842352706104539">^[a-zA-Z0-9:/_-]{1,255}$</strong></p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row7628893155234"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p847179515530">retiring_principal</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p1731110115530">No</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p31154020414">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p851655562816">Indicates the ID of the retiring user. The value is between 1 to 64 bytes and meets the regular expression <strong id="kms_02_0028__en-us_topic_0112992333_b1580910581588">"^[a-zA-Z0-9]{1,64}$"</strong>.</p>
<p id="kms_02_0028__en-us_topic_0112992333_p342916081631">Example: 0d0466b00d0466b00d0466b00d0466b0</p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row143985550598"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p83991455105914">grantee_principal_type</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p039985520593">No</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p139905525911">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p83991055195915">Authorization type</p>
<p id="kms_02_0028__en-us_topic_0112992333_p5157725907">Values: <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue106019481808"><b>user</b></span>, <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue152665511503"><b>domain</b></span>. The default value is <strong id="kms_02_0028__en-us_topic_0112992333_b749044561411">user</strong>.</p>
</td>
</tr>
<tr id="kms_02_0028__en-us_topic_0112992333_row4011877155238"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p906222915530">sequence</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.3.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p6594517215530">No</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.3.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p1774218113418">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.3.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p2406104219271">36-byte serial number of a request message</p>
<p id="kms_02_0028__en-us_topic_0112992333_p3995872615530">Example: 919c82d4-8046-4722-9094-35c3c6524cff</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="kms_02_0028__en-us_topic_0112992333_section35819930154934"><h4 class="sectiontitle">Responses</h4>
<div class="tablenoborder"><table cellpadding="4" cellspacing="0" summary="" id="kms_02_0028__en-us_topic_0112992333_table66429519154934" frame="border" border="1" rules="all"><caption><b>Table 3 </b>Response parameters</caption><thead align="left"><tr id="kms_02_0028__en-us_topic_0112992333_row58318988154934"><th align="left" class="cellrowborder" valign="top" width="17%" id="mcps1.3.4.2.2.5.1.1"><p id="kms_02_0028__en-us_topic_0112992333_p1832914587446"><strong id="kms_02_0028__en-us_topic_0112992333_b225175057">Parameter</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="16%" id="mcps1.3.4.2.2.5.1.2"><p id="kms_02_0028__en-us_topic_0112992333_p932911586447"><strong id="kms_02_0028__en-us_topic_0112992333_b1830984169">Mandatory</strong></p>
</th>
<th align="left" class="cellrowborder" valign="top" width="17%" id="mcps1.3.4.2.2.5.1.3"><p id="kms_02_0028__en-us_topic_0112992333_p9329155814416">Type</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="50%" id="mcps1.3.4.2.2.5.1.4"><p id="kms_02_0028__en-us_topic_0112992333_p19329358144416">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="kms_02_0028__en-us_topic_0112992333_row12703112154934"><td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.4.2.2.5.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_p6454391416846">grant_id</p>
</td>
<td class="cellrowborder" valign="top" width="16%" headers="mcps1.3.4.2.2.5.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_p4593721154934">Yes</p>
</td>
<td class="cellrowborder" valign="top" width="17%" headers="mcps1.3.4.2.2.5.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_p6511947417">String</p>
</td>
<td class="cellrowborder" valign="top" width="50%" headers="mcps1.3.4.2.2.5.1.4 "><p id="kms_02_0028__en-us_topic_0112992333_p445028111690">64-byte ID of a grant</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="kms_02_0028__en-us_topic_0112992333_section194314434818"><h4 class="sectiontitle">Examples</h4><p id="kms_02_0028__en-us_topic_0112992333_p1373983134818">The following example shows how to grant the <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue911203912192045"><b>describe-key</b></span>, <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue551814606192045"><b>create-datakey</b></span>, and <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue1073362460192045"><b>encrypt-datakey</b></span> permissions of CMK (ID: <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue377730832192120"><b>bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e</b></span>) to the user whose ID is <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue1421217713192147"><b>13gg44z4g2sglzk0egw0u726zoyzvrs8</b></span>. The authorization name is <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue1447592340192212"><b>my_grant</b></span>, and the user (ID: <span class="parmvalue" id="kms_02_0028__en-us_topic_0112992333_parmvalue145990539019275"><b>13gg44z4g2sglzk0egw0u726zoyzvrs8</b></span>) can retire a grant.</p>
<ul id="kms_02_0028__en-us_topic_0112992333_ul398354134811"><li id="kms_02_0028__en-us_topic_0112992333_li12982348487">Example request<pre class="screen" id="kms_02_0028__en-us_topic_0112992333_screen49827415485">{
"key_id": "bb6a3d22-dc93-47ac-b5bd-88df7ad35f1e",
"operations": [
"describe-key",
"create-datakey",
"encrypt-datakey"
],
"grantee_principal":"13gg44z4g2sglzk0egw0u726zoyzvrs8",
"name":"my_grant",
"retiring_principal":"13gg44z4g2sglzk0egw0u726zoyzvrs8"
}</pre>
</li><li id="kms_02_0028__en-us_topic_0112992333_li169835410485">Example response<pre class="screen" id="kms_02_0028__en-us_topic_0112992333_screen209829414486">{
"grant_id": "7c9a3286af4fcca5f0a385ad13e1d21a50e27b6dbcab50f37f30f93b8939827d"
}</pre>
<p id="kms_02_0028__en-us_topic_0112992333_p12982194174819">or</p>
<pre class="screen" id="kms_02_0028__en-us_topic_0112992333_screen29833413488">{
"error": {
"error_code": "KMS.XXXX",
"error_msg": "XXX"
}
}</pre>
</li></ul>
</div>
<div class="section" id="kms_02_0028__en-us_topic_0112992333_section3454223421"><h4 class="sectiontitle">Status Codes</h4><div class="p" id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_p17772351"><a href="#kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_table20596071">Table 4</a> lists the normal status code returned by the response.
<div class="tablenoborder"><a name="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_table20596071"></a><a name="en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_table20596071"></a><table cellpadding="4" cellspacing="0" summary="" id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_table20596071" frame="border" border="1" rules="all"><caption><b>Table 4 </b>Status codes</caption><thead align="left"><tr id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_row9746163"><th align="left" class="cellrowborder" valign="top" width="16.16%" id="mcps1.3.6.2.2.2.4.1.1"><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p57545694203043">Status Code</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="28.28%" id="mcps1.3.6.2.2.2.4.1.2"><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p4531342288">Status</p>
</th>
<th align="left" class="cellrowborder" valign="top" width="55.559999999999995%" id="mcps1.3.6.2.2.2.4.1.3"><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p30689603203043">Description</p>
</th>
</tr>
</thead>
<tbody><tr id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_row48621261"><td class="cellrowborder" valign="top" width="16.16%" headers="mcps1.3.6.2.2.2.4.1.1 "><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_en-us_topic_0079615001_p46008046">200</p>
</td>
<td class="cellrowborder" valign="top" width="28.28%" headers="mcps1.3.6.2.2.2.4.1.2 "><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p7538425819">OK</p>
</td>
<td class="cellrowborder" valign="top" width="55.559999999999995%" headers="mcps1.3.6.2.2.2.4.1.3 "><p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p1885682315512">Request processed successfully.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
<p id="kms_02_0028__en-us_topic_0112992333_en-us_topic_0112992294_p5626181018551">Exception status code. For details, see <a href="kms_02_0301.html#kms_02_0301">Status Codes</a>.</p>
</div>
</div>
<div>
<div class="familylinks">
<div class="parentlink"><strong>Parent topic:</strong> <a href="kms_02_0011.html">CMK Management</a></div>
</div>
</div>