TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / e26ccadad2903200a70e2bda85902c009246a59a / . / docs / html / api / keys / lifetimes.html
blob: 60a42b9ec7eafc71cfe84303be3df227c46c918d [file] [log] [blame]
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]2<!DOCTYPE html>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[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.3. Key lifetimes &#8212; PSA Crypto API 1.0.1 documentation</title>
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 Peskinec2db5f02021-01-18 20:36:53 +0100[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" />
16 <link rel="index" title="Index" href="../../genindex.html" />
17 <link rel="search" title="Search" href="../../search.html" />
18 <link rel="next" title="9.4. Key identifiers" href="ids.html" />
19 <link rel="prev" title="9.2. Key types" href="types.html" />
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 Peskinec2db5f02021-01-18 20:36:53 +0100[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 Peskinec2db5f02021-01-18 20:36:53 +0100[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 Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="key-lifetimes">
37<span id="id1"></span><h1>9.3. Key lifetimes</h1>
38<p>The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.</p>
39<p>Lifetime values are composed from:</p>
40<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]41<li><p>A persistence level, which indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is volatile or persistent. See <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a> for more information.</p></li>
42<li><p>A location indicator, which indicates where the key is stored and where operations on the key are performed. See <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_location_t</span></code></a> for more information.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]43</ul>
44<p>There are two main types of lifetime, indicated by the persistence level: <em>volatile</em> and <em>persistent</em>.</p>
45<div class="section" id="volatile-keys">
46<h2>9.3.1. Volatile keys</h2>
47<p>Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Volatile keys can be explicitly destroyed by the application.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]48<p>Conceptually, a volatile key is stored in RAM. Volatile keys have the lifetime <a class="reference internal" href="#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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]49<p>To create a volatile key:</p>
50<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]51<li><p>Populate a <a class="reference internal" href="attributes.html#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 with the required type, size, policy and other key attributes.</p></li>
52<li><p>Create the key with one of the key creation functions. If successful, these functions output a transient <a class="reference internal" href="ids.html#key-identifiers"><span class="std std-ref">key identifier</span></a>.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]53</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]54<p>To destroy a volatile key: call <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier. There must be a matching call to <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_destroy_key()</span></code></a> for each successful call to a create a volatile key.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]55</div>
56<div class="section" id="persistent-keys">
57<h2>9.3.2. Persistent keys</h2>
58<p>Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.</p>
59<p>Each persistent key has a permanent key identifier, which acts as a name for the key.
60Within an application, the key identifier corresponds to a single key. The
61application specifies the key identifier when the key is created and when
62using the key.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]63<p>The lifetime attribute of a persistent key indicates how and where it is stored. The default lifetime value for a persistent key is <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>, which corresponds to a default storage area. This specification defines how implementations can provide other lifetime values corresponding to
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]64different storage areas with different retention policies, or to secure elements
65with different security characteristics.</p>
66<p>To create a persistent key:</p>
67<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]68<li><p>Populate a <a class="reference internal" href="attributes.html#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 with the key’s type, size, policy and other attributes.</p></li>
69<li><p>In the attributes object, set the desired lifetime and persistent identifier for the key.</p></li>
70<li><p>Create the key with one of the key creation functions. If successful, these functions output the <a class="reference internal" href="ids.html#key-identifiers"><span class="std std-ref">key identifier</span></a> that was specified by the application in step 2.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]71</ol>
72<p>To access an existing persistent key: use the key identifier in any API that requires a key.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]73<p>To destroy a persistent key: call <a class="reference internal" href="management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier. Destroying a persistent key permanently removes it from memory and storage.</p>
74<p>By default, persistent key material is removed from volatile memory when not in use. Frequently used persistent keys can benefit from caching, depending on the implementation and the application. Caching can be enabled by creating the key with the <a class="reference internal" href="policy.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> policy. Cached keys can be removed from volatile memory by calling <a class="reference internal" href="management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_purge_key()</span></code></a>. See also <a class="reference internal" href="../../overview/implementation.html#memory-cleanup"><span class="secref">Memory cleanup</span></a> and <a class="reference internal" href="../../overview/implementation.html#key-material"><span class="secref">Managing key material</span></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]75</div>
76<div class="section" id="lifetime-encodings">
77<h2>9.3.3. Lifetime encodings</h2>
78<div class="section" id="psa_key_lifetime_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]79<span id="c.psa_key_lifetime_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code> (type)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]80<p>Encoding of key lifetimes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]81<pre class="literal-block">typedef uint32_t <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>;</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]82<p>The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.</p>
83<p>Lifetime values have the following structure:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]84<dl>
85<dt>Bits[7:0]: Persistence level</dt><dd><p>This value indicates what device management actions can cause it to be destroyed. In particular, it indicates whether the key is <em>volatile</em> or <em>persistent</em>. See <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a> for more information.</p>
86<p><a class="reference internal" href="#c.PSA_KEY_LIFETIME_GET_PERSISTENCE" title="PSA_KEY_LIFETIME_GET_PERSISTENCE"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_GET_PERSISTENCE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">lifetime</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> returns the persistence level for a key <code class="docutils literal notranslate"><span class="pre">lifetime</span></code> value.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]87</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]88<dt>Bits[31:8]: Location indicator</dt><dd><p>This value indicates where the key material is stored (or at least where it is accessible in cleartext) and where operations on the key are performed. See <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_location_t</span></code></a> for more information.</p>
89<p><a class="reference internal" href="#c.PSA_KEY_LIFETIME_GET_LOCATION" title="PSA_KEY_LIFETIME_GET_LOCATION"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_GET_LOCATION</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">lifetime</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> returns the location indicator for a key <code class="docutils literal notranslate"><span class="pre">lifetime</span></code> value.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]90</dd>
91</dl>
92<p>Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]93<p>Persistent keys have a key identifier of type <a class="reference internal" href="ids.html#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_id_t</span></code></a>. This identifier remains valid throughout the lifetime of the key, even if the application instance that created the key terminates.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]94<p>This specification defines two basic lifetime values:</p>
95<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]96<li><p>Keys with the lifetime <a class="reference internal" href="#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> are volatile. All implementations should support this lifetime.</p></li>
97<li><p>Keys with the lifetime <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a> are persistent. All implementations that have access to persistent storage with appropriate security guarantees should support this lifetime.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]98</ul>
99</div>
100<div class="section" id="psa_key_persistence_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]101<span id="c.psa_key_persistence_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code> (type)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]102<p>Encoding of key persistence levels.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]103<pre class="literal-block">typedef uint8_t <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t">psa_key_persistence_t</a>;</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]104<p>What distinguishes different persistence levels is which device management events can cause keys to be destroyed. For example, power reset, transfer of device ownership, or a factory reset are device management events that can affect keys at different persistence levels. The specific management events which affect persistent keys at different levels is outside the scope of the PSA Cryptography specification.</p>
105<p>Values for persistence levels defined by this specification are shown in <span><a class="reference internal" href="#persistence-levels"><span class="numref">Table 3</span></a></span>.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]106<table class="colwidths-given longtable docutils align-left" id="persistence-levels">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]107<caption><span class="caption-number">Table 3 </span><span class="caption-text">Key persistence level values</span></caption>
108<colgroup>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]109<col style="width: 40%" />
110<col style="width: 60%" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]111</colgroup>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]112<thead>
113<tr class="row-odd"><th class="head"><p>Persistence level</p></th>
114<th class="head"><p>Definition</p></th>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]115</tr>
116</thead>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]117<tbody>
118<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span> <span class="pre">=</span> </code><a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_VOLATILE" title="PSA_KEY_PERSISTENCE_VOLATILE"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_VOLATILE</span></code></a></p></td>
119<td><p>Volatile key.</p>
120<p>A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]121</td>
122</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]123<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">1</span> <span class="pre">=</span> </code><a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_DEFAULT" title="PSA_KEY_PERSISTENCE_DEFAULT"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_DEFAULT</span></code></a></p></td>
124<td><p>Persistent key with a default lifetime.</p>
125<p>Implementations should support this value if they support persistent keys at all. Applications should use this value if they have no specific needs that are only met by implementation-specific features.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]126</td>
127</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]128<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">2</span> <span class="pre">-</span> <span class="pre">127</span></code></p></td>
129<td><p>Persistent key with a PSA-specified lifetime.</p>
130<p>The PSA Cryptography specification does not define the meaning of these values, but other PSA specifications may do so.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]131</td>
132</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]133<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">128</span> <span class="pre">-</span> <span class="pre">254</span></code></p></td>
134<td><p>Persistent key with a vendor-specified lifetime.</p>
135<p>No PSA specification will define the meaning of these values, so implementations may choose the meaning freely. As a guideline, higher persistence levels should cause a key to survive more management events than lower levels.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]136</td>
137</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]138<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">255</span> <span class="pre">=</span> </code><a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_READ_ONLY" title="PSA_KEY_PERSISTENCE_READ_ONLY"><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_READ_ONLY</span></code></a></p></td>
139<td><p>Read-only or write-once key.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]140<p>A key with this persistence level cannot be destroyed. Implementations that support such keys may either allow their creation through the PSA Cryptography API, preferably only to applications with the appropriate privilege, or only expose keys created through implementation-specific means such as a factory ROM engraving process.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]141<p>Note that keys that are read-only due to policy restrictions rather than due to physical limitations should not have this persistence level.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]142</td>
143</tr>
144</tbody>
145</table>
146<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]147<p class="admonition-title">Note</p>
148<p>Key persistence levels are 8-bit values. Key management interfaces operate on lifetimes (type <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a>), and encode the persistence value as the lower 8 bits of a 32-bit value.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]149</div>
150</div>
151<div class="section" id="psa_key_location_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]152<span id="c.psa_key_location_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_location_t</span></code> (type)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]153<p>Encoding of key location indicators.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]154<pre class="literal-block">typedef uint32_t <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t">psa_key_location_t</a>;</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]155<p>If an implementation of this API can make calls to external cryptoprocessors such as secure elements, the location of a key indicates which secure element performs the operations on the key. If the key material is not stored persistently inside the secure element, it must be stored in a wrapped form such that only the secure element can access the key material in cleartext.</p>
156<p>Values for location indicators defined by this specification are shown in <span><a class="reference internal" href="#location-indicators"><span class="numref">Table 4</span></a></span>.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]157<table class="colwidths-given longtable docutils align-left" id="location-indicators">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]158<caption><span class="caption-number">Table 4 </span><span class="caption-text">Key location indicator values</span></caption>
159<colgroup>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]160<col style="width: 25%" />
161<col style="width: 75%" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]162</colgroup>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]163<thead>
164<tr class="row-odd"><th class="head"><p>Location indicator</p></th>
165<th class="head"><p>Definition</p></th>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]166</tr>
167</thead>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]168<tbody>
169<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">0</span></code></p></td>
170<td><p>Primary local storage.</p>
171<p>All implementations should support this value. The primary local storage is typically the same storage area that contains the key metadata.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]172</td>
173</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]174<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">1</span></code></p></td>
175<td><p>Primary secure element.</p>
176<p>Implementations should support this value if there is a secure element attached to the operating environment. As a guideline, secure elements may provide higher resistance against side channel and physical attacks than the primary local storage, but may have restrictions on supported key types, sizes, policies and operations and may have different performance characteristics.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]177</td>
178</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]179<tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">2</span> <span class="pre">-</span> <span class="pre">0x7fffff</span></code></p></td>
180<td><p>Other locations defined by a PSA specification.</p>
181<p>The PSA Cryptography API does not currently assign any meaning to these locations, but future versions of this specification or other PSA specifications may do so.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]182</td>
183</tr>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]184<tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">0x800000</span> <span class="pre">-</span> <span class="pre">0xffffff</span></code></p></td>
185<td><p>Vendor-defined locations.</p>
186<p>No PSA specification will assign a meaning to locations in this range.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]187</td>
188</tr>
189</tbody>
190</table>
191<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]192<p class="admonition-title">Note</p>
193<p>Key location indicators are 24-bit values. Key management interfaces operate on lifetimes (type <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a>), and encode the location as the upper 24 bits of a 32-bit value.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]194</div>
195</div>
196</div>
197<div class="section" id="lifetime-values">
198<h2>9.3.4. Lifetime values</h2>
199<div class="section" id="PSA_KEY_LIFETIME_VOLATILE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]200<span id="c.PSA_KEY_LIFETIME_VOLATILE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]201<p>The default lifetime for volatile keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]202<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE">PSA_KEY_LIFETIME_VOLATILE</a> ((<a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>) 0x00000000)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]203<p>A volatile key only exists as long as its identifier is not destroyed. The key material is guaranteed to be erased on a power reset.</p>
204<p>A key with this lifetime is typically stored in the RAM area of the PSA Crypto subsystem. However this is an implementation choice. If an implementation stores data about the key in a non-volatile memory, it must release all the resources associated with the key and erase the key material if the calling application terminates.</p>
205</div>
206<div class="section" id="PSA_KEY_LIFETIME_PERSISTENT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]207<span id="c.PSA_KEY_LIFETIME_PERSISTENT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]208<p>The default lifetime for persistent keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]209<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT">PSA_KEY_LIFETIME_PERSISTENT</a> ((<a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a>) 0x00000001)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]210<p>A persistent key remains in storage until it is explicitly destroyed or until the corresponding storage area is wiped. This specification does not define any mechanism to wipe a storage area. Implementations are permitted to provide their own mechanism, for example, to perform a factory reset, to prepare for device refurbishment, or to uninstall an application.</p>
211<p>This lifetime value is the default storage area for the calling application. Implementations can offer other storage areas designated by other lifetime values as implementation-specific extensions.</p>
212</div>
213<div class="section" id="PSA_KEY_PERSISTENCE_VOLATILE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]214<span id="c.PSA_KEY_PERSISTENCE_VOLATILE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_VOLATILE</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]215<p>The persistence level of volatile keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]216<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_VOLATILE" title="PSA_KEY_PERSISTENCE_VOLATILE">PSA_KEY_PERSISTENCE_VOLATILE</a> ((<a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t">psa_key_persistence_t</a>) 0x00)</pre>
217<p>See <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a> for more information.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]218</div>
219<div class="section" id="PSA_KEY_PERSISTENCE_DEFAULT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]220<span id="c.PSA_KEY_PERSISTENCE_DEFAULT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_DEFAULT</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]221<p>The default persistence level for persistent keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]222<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_DEFAULT" title="PSA_KEY_PERSISTENCE_DEFAULT">PSA_KEY_PERSISTENCE_DEFAULT</a> ((<a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t">psa_key_persistence_t</a>) 0x01)</pre>
223<p>See <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a> for more information.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]224</div>
225<div class="section" id="PSA_KEY_PERSISTENCE_READ_ONLY">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]226<span id="c.PSA_KEY_PERSISTENCE_READ_ONLY"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_PERSISTENCE_READ_ONLY</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]227<p>A persistence level indicating that a key is never destroyed.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]228<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_READ_ONLY" title="PSA_KEY_PERSISTENCE_READ_ONLY">PSA_KEY_PERSISTENCE_READ_ONLY</a> ((<a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t">psa_key_persistence_t</a>) 0xff)</pre>
229<p>See <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a> for more information.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]230</div>
231<div class="section" id="PSA_KEY_LOCATION_LOCAL_STORAGE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]232<span id="c.PSA_KEY_LOCATION_LOCAL_STORAGE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LOCATION_LOCAL_STORAGE</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]233<p>The local storage area for persistent keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]234<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LOCATION_LOCAL_STORAGE" title="PSA_KEY_LOCATION_LOCAL_STORAGE">PSA_KEY_LOCATION_LOCAL_STORAGE</a> ((<a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t">psa_key_location_t</a>) 0x000000)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]235<p>This storage area is available on all systems that can store persistent keys without delegating the storage to a third-party cryptoprocessor.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]236<p>See <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_location_t</span></code></a> for more information.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]237</div>
238<div class="section" id="PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]239<span id="c.PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]240<p>The default secure element storage area for persistent keys.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]241<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT" title="PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT">PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT</a> ((<a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t">psa_key_location_t</a>) 0x000001)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]242<p>This storage location is available on systems that have one or more secure elements that are able to store keys.</p>
243<p>Vendor-defined locations must be provided by the system for storing keys in additional secure elements.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]244<p>See <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_location_t</span></code></a> for more information.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]245</div>
246</div>
247<div class="section" id="attribute-accessors">
248<h2>9.3.5. Attribute accessors</h2>
249<div class="section" id="psa_set_key_lifetime">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]250<span id="c.psa_set_key_lifetime"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_set_key_lifetime</span></code> (function)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]251<p>Set the location of a persistent key.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]252<pre class="literal-block">void <a class="reference internal" href="#c.psa_set_key_lifetime" title="psa_set_key_lifetime">psa_set_key_lifetime</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
253 <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a> lifetime);</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]254<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]255<dl class="simple">
256<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>The attribute object to write to.</p>
257</dd>
258<dt> <code class="docutils literal notranslate"><span class="pre">lifetime</span></code></dt><dd><p>The lifetime for the key. If this is <a class="reference internal" href="#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>, the key will be volatile, and the key identifier attribute is reset to <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>.</p>
259</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]260</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]261<p class="rubric">Returns: <code class="docutils literal notranslate"><span class="pre">void</span></code></p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]262<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]263<p>To make a key persistent, give it a persistent key identifier by using <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>. By default, a key that has a persistent identifier is stored in the default storage area identifier by <a class="reference internal" href="#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>. Call this function to choose a storage area, or to explicitly declare the key as volatile.</p>
264<p>This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as <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>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]265<div class="admonition-implementation-note admonition">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]266<p class="admonition-title">Implementation note</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]267<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]268<ul class="simple">
269<li><p>This function can be declared as <code class="docutils literal notranslate"><span class="pre">static</span></code> or <code class="docutils literal notranslate"><span class="pre">inline</span></code>, instead of using the default external linkage.</p></li>
270<li><p>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]271</ul>
272</div>
273</div>
274<div class="section" id="psa_get_key_lifetime">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]275<span id="c.psa_get_key_lifetime"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_get_key_lifetime</span></code> (function)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]276<p>Retrieve the lifetime from key attributes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]277<pre class="literal-block"><a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t">psa_key_lifetime_t</a> <a class="reference internal" href="#c.psa_get_key_lifetime" title="psa_get_key_lifetime">psa_get_key_lifetime</a>(const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes);</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]278<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]279<dl class="simple">
280<dt> <code class="docutils literal notranslate"><span class="pre">attributes</span></code></dt><dd><p>The key attribute object to query.</p>
281</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]282</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]283<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a></p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]284<p>The lifetime value stored in the attribute object.</p>
285<p class="rubric">Description</p>
286<div class="admonition-implementation-note admonition">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]287<p class="admonition-title">Implementation note</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]288<p>This is a simple accessor function that is not required to validate its inputs. The following approaches can be used to provide an efficient implementation:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]289<ul class="simple">
290<li><p>This function can be declared as <code class="docutils literal notranslate"><span class="pre">static</span></code> or <code class="docutils literal notranslate"><span class="pre">inline</span></code>, instead of using the default external linkage.</p></li>
291<li><p>This function can be provided as a function-like macro. In this form, the macro must evaluate each of its arguments exactly once, as if it was a function call.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]292</ul>
293</div>
294</div>
295</div>
296<div class="section" id="support-macros">
297<h2>9.3.6. Support macros</h2>
298<div class="section" id="PSA_KEY_LIFETIME_GET_PERSISTENCE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]299<span id="c.PSA_KEY_LIFETIME_GET_PERSISTENCE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_GET_PERSISTENCE</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]300<p>Extract the persistence level from a key lifetime.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]301<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_GET_PERSISTENCE" title="PSA_KEY_LIFETIME_GET_PERSISTENCE">PSA_KEY_LIFETIME_GET_PERSISTENCE</a>(lifetime) \
302 ((<a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t">psa_key_persistence_t</a>) ((lifetime) &amp; 0x000000ff))</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]303<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]304<dl class="simple">
305<dt> <code class="docutils literal notranslate"><span class="pre">lifetime</span></code></dt><dd><p>The lifetime value to query (value of type <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a>).</p>
306</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]307</dl>
308</div>
309<div class="section" id="PSA_KEY_LIFETIME_GET_LOCATION">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]310<span id="c.PSA_KEY_LIFETIME_GET_LOCATION"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_GET_LOCATION</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]311<p>Extract the location indicator from a key lifetime.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]312<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_GET_LOCATION" title="PSA_KEY_LIFETIME_GET_LOCATION">PSA_KEY_LIFETIME_GET_LOCATION</a>(lifetime) \
313 ((<a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t">psa_key_location_t</a>) ((lifetime) &gt;&gt; 8))</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]314<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]315<dl class="simple">
316<dt> <code class="docutils literal notranslate"><span class="pre">lifetime</span></code></dt><dd><p>The lifetime value to query (value of type <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a>).</p>
317</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]318</dl>
319</div>
320<div class="section" id="PSA_KEY_LIFETIME_IS_VOLATILE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]321<span id="c.PSA_KEY_LIFETIME_IS_VOLATILE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_IS_VOLATILE</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]322<p>Whether a key lifetime indicates that the key is volatile.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]323<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_IS_VOLATILE" title="PSA_KEY_LIFETIME_IS_VOLATILE">PSA_KEY_LIFETIME_IS_VOLATILE</a>(lifetime) \
324 (<a class="reference internal" href="#c.PSA_KEY_LIFETIME_GET_PERSISTENCE" title="PSA_KEY_LIFETIME_GET_PERSISTENCE">PSA_KEY_LIFETIME_GET_PERSISTENCE</a>(lifetime) == <a class="reference internal" href="#c.PSA_KEY_PERSISTENCE_VOLATILE" title="PSA_KEY_PERSISTENCE_VOLATILE">PSA_KEY_PERSISTENCE_VOLATILE</a>)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]325<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]326<dl class="simple">
327<dt> <code class="docutils literal notranslate"><span class="pre">lifetime</span></code></dt><dd><p>The lifetime value to query (value of type <a class="reference internal" href="#c.psa_key_lifetime_t" title="psa_key_lifetime_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_lifetime_t</span></code></a>).</p>
328</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]329</dl>
330<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]331<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if the key is volatile, otherwise <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]332<p class="rubric">Description</p>
333<p>A volatile key is automatically destroyed by the implementation when the application instance terminates. In particular, a volatile key is automatically destroyed on a power reset of the device.</p>
334<p>A key that is not volatile is persistent. Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset.</p>
335</div>
336<div class="section" id="PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]337<span id="c.PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]338<p>Construct a lifetime from a persistence level and a location.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]339<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION" title="PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION">PSA_KEY_LIFETIME_FROM_PERSISTENCE_AND_LOCATION</a>(persistence, location) \
340 ((location) &lt;&lt; 8 | (persistence))</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]341<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]342<dl class="simple">
343<dt> <code class="docutils literal notranslate"><span class="pre">persistence</span></code></dt><dd><p>The persistence level (value of type <a class="reference internal" href="#c.psa_key_persistence_t" title="psa_key_persistence_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_persistence_t</span></code></a>).</p>
344</dd>
345<dt> <code class="docutils literal notranslate"><span class="pre">location</span></code></dt><dd><p>The location indicator (value of type <a class="reference internal" href="#c.psa_key_location_t" title="psa_key_location_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_location_t</span></code></a>).</p>
346</dd>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]347</dl>
348<p class="rubric">Returns</p>
349<p>The constructed lifetime value.</p>
350</div>
351</div>
352</div>
353
354
355 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]356
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]357 </div>
358 </div>
359 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
360 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
361IHI 0086<br/>
362Non-confidential<br/>
363Version 1.0.1
364<span style="color: red; font-weight: bold;"></span>
365<ul>
366<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
367</ul>
368<ul class="current">
369<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
370<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
371<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
372<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
373<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
374<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
375<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
376<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
377<li class="toctree-l1 current"><a class="reference internal" href="index.html">9. Key management reference</a><ul class="current">
378<li class="toctree-l2"><a class="reference internal" href="attributes.html">9.1. Key attributes</a></li>
379<li class="toctree-l2"><a class="reference internal" href="types.html">9.2. Key types</a></li>
380<li class="toctree-l2 current"><a class="current reference internal" href="#">9.3. Key lifetimes</a><ul>
381<li class="toctree-l3"><a class="reference internal" href="#volatile-keys">9.3.1. Volatile keys</a></li>
382<li class="toctree-l3"><a class="reference internal" href="#persistent-keys">9.3.2. Persistent keys</a></li>
383<li class="toctree-l3"><a class="reference internal" href="#lifetime-encodings">9.3.3. Lifetime encodings</a></li>
384<li class="toctree-l3"><a class="reference internal" href="#lifetime-values">9.3.4. Lifetime values</a></li>
385<li class="toctree-l3"><a class="reference internal" href="#attribute-accessors">9.3.5. Attribute accessors</a></li>
386<li class="toctree-l3"><a class="reference internal" href="#support-macros">9.3.6. Support macros</a></li>
387</ul>
388</li>
389<li class="toctree-l2"><a class="reference internal" href="ids.html">9.4. Key identifiers</a></li>
390<li class="toctree-l2"><a class="reference internal" href="policy.html">9.5. Key policies</a></li>
391<li class="toctree-l2"><a class="reference internal" href="management.html">9.6. Key management functions</a></li>
392</ul>
393</li>
394<li class="toctree-l1"><a class="reference internal" href="../ops/index.html">10. Cryptographic operation reference</a></li>
395</ul>
396<ul>
397<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
398<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
399<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
400</ul>
401<ul>
402<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
403</ul>
404<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]405 <h3 id="searchlabel">Quick search</h3>
406 <div class="searchformwrapper">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]407 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]408 <input type="text" name="q" aria-labelledby="searchlabel" />
409 <input type="submit" value="Go" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]410 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]411 </div>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]412</div>
413<script type="text/javascript">$('#searchbox').show(0);</script>
414 </div>
415 </div>
416 <div class="clearer"></div>
417 </div>
418 <div class="footer">
419 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
420
421 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]422 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
423 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]424
425 </div>
426
427
428
429
430 </body>
431</html>