TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 0f4df8f3e48921cf9577526366e94a6f0f3ec37c / . / docs / html / api / keys / attributes.html
blob: cd78ebb130ac3b784796a10c7ac99ae3a0fe1ffd [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8 <title>Key attributes &#8212; PSA Crypto API 1.0.0 documentation</title>
9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
14 VERSION: '1.0.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: true,
18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
24 <link rel="index" title="Index" href="../../genindex.html" />
25 <link rel="search" title="Search" href="../../search.html" />
26 <link rel="next" title="Key locations" href="locations.html" />
27 <link rel="prev" title="Key management reference" href="index.html" />
28
29 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
30
31 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
32
33 </head>
34 <body>
35
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <div class="section" id="key-attributes">
43<span id="id1"></span><h1>Key attributes</h1>
44<div class="section" id="attribute-types">
45<h2>Attribute types</h2>
46<div class="section" id="psa_key_lifetime_t">
47<span id="c.psa_key_lifetime_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_lifetime_t</span></code> (type)</h3>
48<p>Encoding of key lifetimes.</p>
49<pre class="literal-block">
50typedef uint32_t <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>;
51</pre>
52<p>The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.</p>
53<p>Keys with the lifetime <a class="reference internal" href="locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a> are automatically destroyed when the application terminates or on a power reset.</p>
54<p>Keys with a lifetime other than <a class="reference internal" href="locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a> are said to be <em>persistent</em>. Persistent keys are preserved if the application or the system restarts. Persistent keys have a key identifier of type <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_id_t</span></code></a>.</p>
55<p>See <em><a class="reference internal" href="locations.html#key-locations"><span class="std std-ref">Key locations</span></a></em> for a list of defined key lifetimes.</p>
56</div>
57<div class="section" id="psa_key_id_t">
58<span id="c.psa_key_id_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_id_t</span></code> (type)</h3>
59<p>Key identifier.</p>
60<pre class="literal-block">
61typedef uint32_t <a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a>;
62</pre>
63<p>A key identifiers can be a permanent name for a persistent key, or a transient reference to volatile key. The range of identifier values is divided as follows:</p>
64<dl class="docutils">
65<dt><a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a></dt>
66<dd>Reserved as an invalid key identifier.</dd>
67<dt><a class="reference internal" href="locations.html#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="locations.html#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a></dt>
68<dd>Applications can freely choose persistent key identifiers in this range.</dd>
69<dt><a class="reference internal" href="locations.html#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="locations.html#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code></a></dt>
70<dd>Implementations can define additional persistent key identifiers in this
71range, and allocate key identifiers for volatile keys from this range.</dd>
72</dl>
73<p>Key identifiers outside these ranges are reserved for future use.</p>
74<p>See also <em><a class="reference internal" href="../../overview/functionality.html#key-ids"><span class="std std-ref">Key identifiers</span></a></em>.</p>
75</div>
76<div class="section" id="psa_key_type_t">
77<span id="c.psa_key_type_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_type_t</span></code> (type)</h3>
78<p>Encoding of a key type.</p>
79<pre class="literal-block">
80typedef uint16_t <a class="reference internal" href="#c.psa_key_type_t" title="psa_key_type_t">psa_key_type_t</a>;
81</pre>
82<p>This is a structured bitfield that identifies the category and type of key. The range of key type values is divided as follows:</p>
83<dl class="docutils">
84<dt><a class="reference internal" href="types.html#c.PSA_KEY_TYPE_NONE" title="PSA_KEY_TYPE_NONE"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_NONE</span></code></a><code class="docutils literal"> <span class="pre">==</span> <span class="pre">0</span></code></dt>
85<dd>Reserved as an invalid key type.</dd>
86<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x0001</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">x7fff</span></code></dt>
87<dd>Specification-defined key types.
88Key types defined by this standard always have bit 15 clear.
89Unallocated key type values in this range are reserved for future use.</dd>
90<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x8000</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">xffff</span></code></dt>
91<dd>Implementation-defined key types.
92Implementations that define additional key types must use an encoding with bit 15 set.
93The related support macros will be easier to write if these key encodings also respect the bitwise structure used by standard encodings.</dd>
94</dl>
95<p>See <em><a class="reference internal" href="types.html#key-types"><span class="std std-ref">Key types</span></a></em> for a complete list of key types.</p>
96</div>
97<div class="section" id="psa_key_usage_t">
98<span id="c.psa_key_usage_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code> (type)</h3>
99<p>Encoding of permitted usage on a key.</p>
100<pre class="literal-block">
101typedef uint32_t <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>;
102</pre>
103<p>See <em><a class="reference internal" href="usage.html#key-usage"><span class="std std-ref">Key policies</span></a></em> for a full list of key usage policies.</p>
104</div>
105<div class="section" id="psa_algorithm_t">
106<span id="c.psa_algorithm_t"></span><h3><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code> (type)</h3>
107<p>Encoding of a cryptographic algorithm.</p>
108<pre class="literal-block">
109typedef uint32_t <a class="reference internal" href="#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>;
110</pre>
111<p>This is a structured bitfield that identifies the category and type of algorithm. The range of algorithm identifier values is divided as follows:</p>
112<dl class="docutils">
113<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x00000000</span></code></dt>
114<dd>Reserved as an invalid algorithm identifier.</dd>
115<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x00000001</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">x7fffffff</span></code></dt>
116<dd>Specification-defined algorithm identifiers.
117Algorithm identifiers defined by this standard always have bit 31 clear.
118Unallocated algorithm identifier values in this range are reserved for future use.</dd>
119<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x80000000</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">xffffffff</span></code></dt>
120<dd>Implementation-defined algorithm identifiers.
121Implementations that define additional algorithms must use an encoding with bit 31 set.
122The related support macros will be easier to write if these algorithm identifier encodings also respect the bitwise structure used by standard encodings.</dd>
123</dl>
124<p>For algorithms that can be applied to multiple key types, this identifier does not encode the key type. For example, for symmetric ciphers based on a block cipher, <a class="reference internal" href="#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> encodes the block cipher mode and the padding mode while the block cipher itself is encoded via <a class="reference internal" href="#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a>.</p>
125<p>See <em><a class="reference internal" href="algorithms.html#algorithms"><span class="std std-ref">Algorithms</span></a></em> for a full list of algorithm identifiers.</p>
126</div>
127</div>
128<div class="section" id="managing-attributes">
129<h2>Managing attributes</h2>
130<div class="section" id="psa_key_attributes_t">
131<span id="c.psa_key_attributes_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_attributes_t</span></code> (type)</h3>
132<p>The type of an object containing key attributes.</p>
133<pre class="literal-block">
134typedef <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a>;
135</pre>
136<p>This is the object that represents the metadata of a key object. Metadata that can be stored in attributes includes:</p>
137<ul class="simple">
138<li>The location of the key in storage, indicated by its key identifier and its lifetime.</li>
139<li>The key’s policy, comprising usage flags and a specification of the permitted algorithm(s).</li>
140<li>Information about the key itself: the key type and its size.</li>
141<li>Implementations can define additional attributes.</li>
142</ul>
143<p>The actual key material is not considered an attribute of a key. Key attributes do not contain information that is generally considered highly confidential.</p>
144<div class="admonition note">
145<p class="first admonition-title">Note</p>
146<p>Implementations are recommended to define the attribute object as a simple data structure, with fields corresponding to the individual key attributes. In such an implementation, each function <code class="docutils literal"><span class="pre">psa_set_key_xxx()</span></code> sets a field and the corresponding function <code class="docutils literal"><span class="pre">psa_get_key_xxx()</span></code> retrieves the value of the field.</p>
147<p class="last">An implementations can report attribute values that are equivalent to the original one, but have a different encoding. For example, an implementation can use a more compact representation for types where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which might not be the one that was originally stored.</p>
148</div>
149<p>This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.</p>
150<p>An attribute object can contain references to auxiliary resources, for example pointers to allocated memory or indirect references to pre-calculated values. In order to free such resources, the application must call <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a>. As an exception, calling <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a> on an attribute object is optional if the object has only been modified by the following functions since it was initialized or last reset with <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a>:</p>
151<ul class="simple">
152<li><a class="reference internal" href="locations.html#c.psa_set_key_id" title="psa_set_key_id"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_id()</span></code></a></li>
153<li><a class="reference internal" href="locations.html#c.psa_set_key_lifetime" title="psa_set_key_lifetime"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_lifetime()</span></code></a></li>
154<li><a class="reference internal" href="types.html#c.psa_set_key_type" title="psa_set_key_type"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_type()</span></code></a></li>
155<li><a class="reference internal" href="types.html#c.psa_set_key_bits" title="psa_set_key_bits"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_bits()</span></code></a></li>
156<li><a class="reference internal" href="usage.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_usage_flags()</span></code></a></li>
157<li><a class="reference internal" href="algorithms.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_algorithm()</span></code></a></li>
158</ul>
159<p>Before calling any function on a key attribute object, the application must initialize it by any of the following means:</p>
160<ul>
161<li><p class="first">Set the object to all-bits-zero, for example:</p>
162<pre class="literal-block">
163<a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;
164memset(&amp;attributes, 0, sizeof(attributes));
165</pre>
166</li>
167<li><p class="first">Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
168<pre class="literal-block">
169static <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;
170</pre>
171</li>
172<li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_KEY_ATTRIBUTES_INIT" title="PSA_KEY_ATTRIBUTES_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ATTRIBUTES_INIT</span></code></a>, for example:</p>
173<pre class="literal-block">
174<a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes = <a class="reference internal" href="#c.PSA_KEY_ATTRIBUTES_INIT" title="PSA_KEY_ATTRIBUTES_INIT">PSA_KEY_ATTRIBUTES_INIT</a>;
175</pre>
176</li>
177<li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_key_attributes_init" title="psa_key_attributes_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_attributes_init()</span></code></a> to the object, for example:</p>
178<pre class="literal-block">
179<a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;
180attributes = <a class="reference internal" href="#c.psa_key_attributes_init" title="psa_key_attributes_init">psa_key_attributes_init</a>();
181</pre>
182</li>
183</ul>
184<p>A freshly initialized attribute object contains the following values:</p>
185<table border="1" class="docutils">
186<colgroup>
187<col width="15%" />
188<col width="85%" />
189</colgroup>
190<thead valign="bottom">
191<tr class="row-odd"><th class="head">Attribute</th>
192<th class="head">Value</th>
193</tr>
194</thead>
195<tbody valign="top">
196<tr class="row-even"><td>lifetime</td>
197<td><a class="reference internal" href="locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>.</td>
198</tr>
199<tr class="row-odd"><td>key identifier</td>
200<td><a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> - which is not a valid key identifier.</td>
201</tr>
202<tr class="row-even"><td>type</td>
203<td><a class="reference internal" href="types.html#c.PSA_KEY_TYPE_NONE" title="PSA_KEY_TYPE_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_NONE</span></code></a> - meaning that the type is unspecified.</td>
204</tr>
205<tr class="row-odd"><td>key size</td>
206<td><code class="docutils literal"><span class="pre">0</span></code> - meaning that the size is unspecified.</td>
207</tr>
208<tr class="row-even"><td>usage flags</td>
209<td><code class="docutils literal"><span class="pre">0</span></code> - which allows no usage except exporting a public key.</td>
210</tr>
211<tr class="row-odd"><td>algorithm</td>
212<td><a class="reference internal" href="algorithms.html#c.PSA_ALG_NONE" title="PSA_ALG_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_NONE</span></code></a> - which does not allow cryptographic usage, but allows exporting.</td>
213</tr>
214</tbody>
215</table>
216<p class="rubric">Usage</p>
217<p>A typical sequence to create a key is as follows:</p>
218<ol class="arabic simple">
219<li>Create and initialize an attribute object.</li>
220<li>If the key is persistent, call <a class="reference internal" href="locations.html#c.psa_set_key_id" title="psa_set_key_id"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_id()</span></code></a>. Also call <a class="reference internal" href="locations.html#c.psa_set_key_lifetime" title="psa_set_key_lifetime"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_lifetime()</span></code></a> to place the key in a non-default location.</li>
221<li>Set the key policy with <a class="reference internal" href="usage.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_usage_flags()</span></code></a> and <a class="reference internal" href="algorithms.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_algorithm()</span></code></a>.</li>
222<li>Set the key type with <a class="reference internal" href="types.html#c.psa_set_key_type" title="psa_set_key_type"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_type()</span></code></a>. Skip this step if copying an existing key with <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>.</li>
223<li>When generating a random key with <a class="reference internal" href="management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a> or deriving a key with <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a>, set the desired key size with <a class="reference internal" href="types.html#c.psa_set_key_bits" title="psa_set_key_bits"><code class="xref any c c-func docutils literal"><span class="pre">psa_set_key_bits()</span></code></a>.</li>
224<li>Call a key creation function: <a class="reference internal" href="management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>, <a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>. This function reads the attribute object, creates a key with these attributes, and outputs an identifier for the newly created key.</li>
225<li>Optionally call <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a>, now that the attribute object is no longer needed. Currently this call is not required as the attributes defined in this specification do not require additional resources beyond the object itself.</li>
226</ol>
227<p>A typical sequence to query a key’s attributes is as follows:</p>
228<ol class="arabic simple">
229<li>Call <a class="reference internal" href="#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_get_key_attributes()</span></code></a>.</li>
230<li>Call <code class="docutils literal"><span class="pre">psa_get_key_xxx()</span></code> functions to retrieve the required attribute(s).</li>
231<li>Call <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a> to free any resources that can be used by the attribute object.</li>
232</ol>
233<p>Once a key has been created, it is impossible to change its attributes.</p>
234</div>
235<div class="section" id="PSA_KEY_ATTRIBUTES_INIT">
236<span id="c.PSA_KEY_ATTRIBUTES_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_ATTRIBUTES_INIT</span></code> (macro)</h3>
237<p>This macro returns a suitable initializer for a key attribute object of type <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a>.</p>
238<pre class="literal-block">
239#define <a class="reference internal" href="#c.PSA_KEY_ATTRIBUTES_INIT" title="PSA_KEY_ATTRIBUTES_INIT">PSA_KEY_ATTRIBUTES_INIT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
240</pre>
241</div>
242<div class="section" id="psa_key_attributes_init">
243<span id="c.psa_key_attributes_init"></span><h3><code class="docutils literal"><span class="pre">psa_key_attributes_init</span></code> (function)</h3>
244<p>Return an initial value for a key attribute object.</p>
245<pre class="literal-block">
246<a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> <a class="reference internal" href="#c.psa_key_attributes_init" title="psa_key_attributes_init">psa_key_attributes_init</a>(void);
247</pre>
248<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="docutils literal"><span class="pre">psa_key_attributes_t</span></code></a></p>
249</div>
250<div class="section" id="psa_get_key_attributes">
251<span id="c.psa_get_key_attributes"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_attributes</span></code> (function)</h3>
252<p>Retrieve the attributes of a key.</p>
253<pre class="literal-block">
254<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_get_key_attributes" title="psa_get_key_attributes">psa_get_key_attributes</a>(<a class="reference internal" href="#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
255 <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);
256</pre>
257<p class="rubric">Parameters</p>
258<dl class="docutils">
259<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
260<dd>Identifier of the key to query.</dd>
261<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
262<dd>On entry, <code class="docutils literal"><span class="pre">*attributes</span></code> must be in a valid state. On successful return, it contains the attributes of the key. On failure, it is equivalent to a freshly-initialized attribute object.</dd>
263</dl>
264<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
265<dl class="docutils">
266<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
267<dd></dd>
268<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
269<dd></dd>
270<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
271<dd></dd>
272<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
273<dd></dd>
274<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
275<dd></dd>
276<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
277<dd></dd>
278<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
279<dd></dd>
280<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
281<dd></dd>
282<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
283<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
284</dl>
285<p class="rubric">Description</p>
286<p>This function first resets the attribute object as with <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a>. It then copies the attributes of the given key into the given attribute object.</p>
287<div class="admonition note">
288<p class="first admonition-title">Note</p>
289<p class="last">This function clears any previous content from the attribute object and therefore expects it to be in a valid state. In particular, if this function is called on a newly allocated attribute object, the attribute object must be initialized before calling this function.</p>
290</div>
291<div class="admonition note">
292<p class="first admonition-title">Note</p>
293<p class="last">This function might allocate memory or other resources. Once this function has been called on an attribute object, <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_reset_key_attributes()</span></code></a> must be called to free these resources.</p>
294</div>
295</div>
296<div class="section" id="psa_reset_key_attributes">
297<span id="c.psa_reset_key_attributes"></span><h3><code class="docutils literal"><span class="pre">psa_reset_key_attributes</span></code> (function)</h3>
298<p>Reset a key attribute object to a freshly initialized state.</p>
299<pre class="literal-block">
300void <a class="reference internal" href="#c.psa_reset_key_attributes" title="psa_reset_key_attributes">psa_reset_key_attributes</a>(<a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);
301</pre>
302<p class="rubric">Parameters</p>
303<dl class="docutils">
304<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
305<dd>The attribute object to reset.</dd>
306</dl>
307<p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p>
308<p class="rubric">Description</p>
309<p>The attribute object must be initialized as described in the documentation of the type <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> before calling this function. Once the object has been initialized, this function can be called at any time.</p>
310<p>This function frees any auxiliary resources that the object might contain.</p>
311</div>
312</div>
313</div>
314
315
316 </div>
317 </div>
318 </div>
319 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
320 <div class="sphinxsidebarwrapper">
321 <h3><a href="../../index.html">Table Of Contents</a></h3>
322 <ul>
323<li><a class="reference internal" href="#">Key attributes</a><ul>
324<li><a class="reference internal" href="#attribute-types">Attribute types</a><ul>
325<li><a class="reference internal" href="#psa_key_lifetime_t"><code class="docutils literal"><span class="pre">psa_key_lifetime_t</span></code> (type)</a></li>
326<li><a class="reference internal" href="#psa_key_id_t"><code class="docutils literal"><span class="pre">psa_key_id_t</span></code> (type)</a></li>
327<li><a class="reference internal" href="#psa_key_type_t"><code class="docutils literal"><span class="pre">psa_key_type_t</span></code> (type)</a></li>
328<li><a class="reference internal" href="#psa_key_usage_t"><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code> (type)</a></li>
329<li><a class="reference internal" href="#psa_algorithm_t"><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code> (type)</a></li>
330</ul>
331</li>
332<li><a class="reference internal" href="#managing-attributes">Managing attributes</a><ul>
333<li><a class="reference internal" href="#psa_key_attributes_t"><code class="docutils literal"><span class="pre">psa_key_attributes_t</span></code> (type)</a></li>
334<li><a class="reference internal" href="#PSA_KEY_ATTRIBUTES_INIT"><code class="docutils literal"><span class="pre">PSA_KEY_ATTRIBUTES_INIT</span></code> (macro)</a></li>
335<li><a class="reference internal" href="#psa_key_attributes_init"><code class="docutils literal"><span class="pre">psa_key_attributes_init</span></code> (function)</a></li>
336<li><a class="reference internal" href="#psa_get_key_attributes"><code class="docutils literal"><span class="pre">psa_get_key_attributes</span></code> (function)</a></li>
337<li><a class="reference internal" href="#psa_reset_key_attributes"><code class="docutils literal"><span class="pre">psa_reset_key_attributes</span></code> (function)</a></li>
338</ul>
339</li>
340</ul>
341</li>
342</ul>
343<div class="relations">
344<h3>Related Topics</h3>
345<ul>
346 <li><a href="../../index.html">Documentation overview</a><ul>
347 <li><a href="index.html">Key management reference</a><ul>
348 <li>Previous: <a href="index.html" title="previous chapter">Key management reference</a></li>
349 <li>Next: <a href="locations.html" title="next chapter">Key locations</a></li>
350 </ul></li>
351 </ul></li>
352</ul>
353</div>
354 <div role="note" aria-label="source link">
355 <h3>This Page</h3>
356 <ul class="this-page-menu">
357 <li><a href="../../_sources/api/keys/attributes.rst.txt"
358 rel="nofollow">Show Source</a></li>
359 </ul>
360 </div>
361<div id="searchbox" style="display: none" role="search">
362 <h3>Quick search</h3>
363 <form class="search" action="../../search.html" method="get">
364 <div><input type="text" name="q" /></div>
365 <div><input type="submit" value="Go" /></div>
366 <input type="hidden" name="check_keywords" value="yes" />
367 <input type="hidden" name="area" value="default" />
368 </form>
369</div>
370<script type="text/javascript">$('#searchbox').show(0);</script>
371 </div>
372 </div>
373 <div class="clearer"></div>
374 </div>
375 <div class="footer">
376 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
377
378 |
379 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
380 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
381
382 |
383 <a href="../../_sources/api/keys/attributes.rst.txt"
384 rel="nofollow">Page source</a>
385 </div>
386
387
388
389
390 </body>
391</html>