TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 64e4c9e6baeca190562d79feeedeb8f0c5736ebe / . / docs / html / api / keys / attributes.html
blob: 13e833e5b8805c9457b91b5f54a7545b4e68aac8 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>9.1. Key attributes &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]10 <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../../_static/jquery.js"></script>
12 <script type="text/javascript" src="../../_static/underscore.js"></script>
13 <script type="text/javascript" src="../../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]14 <script type="text/javascript" src="../../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../../genindex.html" />
17 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="9.2. Key types" href="types.html" />
19 <link rel="prev" title="9. Key management reference" href="index.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="key-attributes">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="id1"></span><h1>9.1. Key attributes</h1>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]38<p>Key attributes are managed in a <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code></a> object. These are used when a key is created, after which the key attributes are fixed. Attributes of an existing key can be queried using <a class="reference internal" href="#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_get_key_attributes()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<p>Description of the individual attributes is found in the following sections:</p>
40<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]41<li><p><a class="reference internal" href="types.html#key-types"><span class="secref">Key types</span></a></p></li>
42<li><p><a class="reference internal" href="ids.html#key-identifiers"><span class="secref">Key identifiers</span></a></p></li>
43<li><p><a class="reference internal" href="lifetimes.html#key-lifetimes"><span class="secref">Key lifetimes</span></a></p></li>
44<li><p><a class="reference internal" href="policy.html#key-policy"><span class="secref">Key policies</span></a></p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]45</ul>
46<div class="section" id="managing-key-attributes">
47<h2>9.1.1. Managing key attributes</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]48<div class="section" id="psa_key_attributes_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]49<span id="c.psa_key_attributes_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code> (type)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]50<p>The type of an object containing key attributes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]51<pre class="literal-block">typedef <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>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]52<p>This is the object that represents the metadata of a key object. Metadata that can be stored in attributes includes:</p>
53<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]54<li><p>The location of the key in storage, indicated by its key identifier and its lifetime.</p></li>
55<li><p>The key’s policy, comprising usage flags and a specification of the permitted algorithm(s).</p></li>
56<li><p>Information about the key itself: the key type and its size.</p></li>
57<li><p>Implementations can define additional attributes.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]58</ul>
59<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>
60<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]61<p class="admonition-title">Note</p>
62<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 notranslate"><span class="pre">psa_set_key_xxx()</span></code> sets a field and the corresponding function <code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx()</span></code> retrieves the value of the field.</p>
63<p>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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]64</div>
65<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>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]66<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_reset_key_attributes()</span></code></a>:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]67<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]68<li><p><a class="reference internal" href="ids.html#c.psa_set_key_id" title="psa_set_key_id"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_id()</span></code></a></p></li>
69<li><p><a class="reference internal" href="lifetimes.html#c.psa_set_key_lifetime" title="psa_set_key_lifetime"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_lifetime()</span></code></a></p></li>
70<li><p><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 notranslate"><span class="pre">psa_set_key_type()</span></code></a></p></li>
71<li><p><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 notranslate"><span class="pre">psa_set_key_bits()</span></code></a></p></li>
72<li><p><a class="reference internal" href="policy.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_usage_flags()</span></code></a></p></li>
73<li><p><a class="reference internal" href="policy.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_algorithm()</span></code></a></p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]74</ul>
75<p>Before calling any function on a key attribute object, the application must initialize it by any of the following means:</p>
76<ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]77<li><p>Set the object to all-bits-zero, for example:</p>
78<pre class="literal-block"><a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;
79memset(&amp;attributes, 0, sizeof(attributes));</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]80</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]81<li><p>Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
82<pre class="literal-block">static <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]83</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]84<li><p>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 notranslate"><span class="pre">PSA_KEY_ATTRIBUTES_INIT</span></code></a>, for example:</p>
85<pre class="literal-block"><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>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]86</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]87<li><p>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 notranslate"><span class="pre">psa_key_attributes_init()</span></code></a> to the object, for example:</p>
88<pre class="literal-block"><a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes;
89attributes = <a class="reference internal" href="#c.psa_key_attributes_init" title="psa_key_attributes_init">psa_key_attributes_init</a>();</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]90</li>
91</ul>
92<p>A freshly initialized attribute object contains the following values:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]93<table class="colwidths-auto docutils align-left">
94<thead>
95<tr class="row-odd"><th class="head"><p>Attribute</p></th>
96<th class="head"><p>Value</p></th>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]97</tr>
98</thead>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]99<tbody>
100<tr class="row-even"><td><p>lifetime</p></td>
101<td><p><a class="reference internal" href="lifetimes.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]102</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]103<tr class="row-odd"><td><p>key identifier</p></td>
104<td><p><a class="reference internal" href="ids.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_ID_NULL</span></code></a> - which is not a valid key identifier.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]105</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]106<tr class="row-even"><td><p>type</p></td>
107<td><p><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 notranslate"><span class="pre">PSA_KEY_TYPE_NONE</span></code></a> - meaning that the type is unspecified.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]108</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]109<tr class="row-odd"><td><p>key size</p></td>
110<td><p><code class="docutils literal notranslate"><span class="pre">0</span></code> - meaning that the size is unspecified.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]111</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]112<tr class="row-even"><td><p>usage flags</p></td>
113<td><p><code class="docutils literal notranslate"><span class="pre">0</span></code> - which allows no usage except exporting a public key.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]114</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]115<tr class="row-odd"><td><p>algorithm</p></td>
116<td><p><a class="reference internal" href="../ops/algorithms.html#c.PSA_ALG_NONE" title="PSA_ALG_NONE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_NONE</span></code></a> - which does not allow cryptographic usage, but allows exporting.</p></td>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]117</tr>
118</tbody>
119</table>
120<p class="rubric">Usage</p>
121<p>A typical sequence to create a key is as follows:</p>
122<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]123<li><p>Create and initialize an attribute object.</p></li>
124<li><p>If the key is persistent, call <a class="reference internal" href="ids.html#c.psa_set_key_id" title="psa_set_key_id"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_id()</span></code></a>. Also call <a class="reference internal" href="lifetimes.html#c.psa_set_key_lifetime" title="psa_set_key_lifetime"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_lifetime()</span></code></a> to place the key in a non-default location.</p></li>
125<li><p>Set the key policy with <a class="reference internal" href="policy.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_usage_flags()</span></code></a> and <a class="reference internal" href="policy.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_set_key_algorithm()</span></code></a>.</p></li>
126<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_copy_key()</span></code></a>.</p></li>
127<li><p>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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_set_key_bits()</span></code></a>.</p></li>
128<li><p>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 notranslate"><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 notranslate"><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 notranslate"><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 notranslate"><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.</p></li>
129<li><p>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 notranslate"><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.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]130</ol>
131<p>A typical sequence to query a key’s attributes is as follows:</p>
132<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]133<li><p>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 notranslate"><span class="pre">psa_get_key_attributes()</span></code></a>.</p></li>
134<li><p>Call <code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx()</span></code> functions to retrieve the required attribute(s).</p></li>
135<li><p>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 notranslate"><span class="pre">psa_reset_key_attributes()</span></code></a> to free any resources that can be used by the attribute object.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]136</ol>
137<p>Once a key has been created, it is impossible to change its attributes.</p>
138</div>
139<div class="section" id="PSA_KEY_ATTRIBUTES_INIT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]140<span id="c.PSA_KEY_ATTRIBUTES_INIT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_ATTRIBUTES_INIT</span></code> (macro)</h3>
141<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 notranslate"><span class="pre">psa_key_attributes_t</span></code></a>.</p>
142<pre class="literal-block">#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></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]143</div>
144<div class="section" id="psa_key_attributes_init">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]145<span id="c.psa_key_attributes_init"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_attributes_init</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]146<p>Return an initial value for a key attribute object.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]147<pre class="literal-block"><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);</pre>
148<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="docutils literal notranslate"><span class="pre">psa_key_attributes_t</span></code></a></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]149</div>
150<div class="section" id="psa_get_key_attributes">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]151<span id="c.psa_get_key_attributes"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_get_key_attributes</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]152<p>Retrieve the attributes of a key.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]153<pre class="literal-block"><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="ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
154 <a class="reference internal" href="#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]155<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]156<dl class="simple">
157<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to query.</p>
158</dd>
159<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>On entry, <code class="docutils literal notranslate"><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.</p>
160</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]161</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]162<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
163<dl class="simple">
164<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd></dd>
165<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
166<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
167<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
168<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
169<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
170<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
171<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
172<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
173</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]174</dl>
175<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]176<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]177<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]178<p class="admonition-title">Note</p>
179<p>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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]180</div>
181<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]182<p class="admonition-title">Note</p>
183<p>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 notranslate"><span class="pre">psa_reset_key_attributes()</span></code></a> must be called to free these resources.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]184</div>
185</div>
186<div class="section" id="psa_reset_key_attributes">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]187<span id="c.psa_reset_key_attributes"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_reset_key_attributes</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]188<p>Reset a key attribute object to a freshly initialized state.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]189<pre class="literal-block">void <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);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]190<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]191<dl class="simple">
192<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>The attribute object to reset.</p>
193</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]194</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]195<p class="rubric">Returns: <code class="docutils literal notranslate"><span class="pre">void</span></code></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]196<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]197<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]198<p>This function frees any auxiliary resources that the object might contain.</p>
199</div>
200</div>
201</div>
202
203
204 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]205
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]206 </div>
207 </div>
208 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]209 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
210IHI 0086<br/>
211Non-confidential<br/>
212Version 1.0.1
213<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]214<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]215<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]216</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]217<ul class="current">
218<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
219<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
220<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
221<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
222<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
223<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
224<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
225<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
226<li class="toctree-l1 current"><a class="reference internal" href="index.html">9. Key management reference</a><ul class="current">
227<li class="toctree-l2 current"><a class="current reference internal" href="#">9.1. Key attributes</a><ul>
228<li class="toctree-l3"><a class="reference internal" href="#managing-key-attributes">9.1.1. Managing key attributes</a></li>
229</ul>
230</li>
231<li class="toctree-l2"><a class="reference internal" href="types.html">9.2. Key types</a></li>
232<li class="toctree-l2"><a class="reference internal" href="lifetimes.html">9.3. Key lifetimes</a></li>
233<li class="toctree-l2"><a class="reference internal" href="ids.html">9.4. Key identifiers</a></li>
234<li class="toctree-l2"><a class="reference internal" href="policy.html">9.5. Key policies</a></li>
235<li class="toctree-l2"><a class="reference internal" href="management.html">9.6. Key management functions</a></li>
236</ul>
237</li>
238<li class="toctree-l1"><a class="reference internal" href="../ops/index.html">10. Cryptographic operation reference</a></li>
239</ul>
240<ul>
241<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
242<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
243<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
244</ul>
245<ul>
246<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
247</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]248<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]249 <h3 id="searchlabel">Quick search</h3>
250 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]251 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]252 <input type="text" name="q" aria-labelledby="searchlabel" />
253 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]254 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]255 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]256</div>
257<script type="text/javascript">$('#searchbox').show(0);</script>
258 </div>
259 </div>
260 <div class="clearer"></div>
261 </div>
262 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]263 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]264
265 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]266 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
267 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]268
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]269 </div>
270
271
272
273
274 </body>
275</html>