TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c2db5f0e443752021c73fb4440a339e2cbc10fb7 / . / docs / html / api / keys / policy.html
blob: 7cf34e49461081a0de2c0790b96029f4026628f7 [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" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]8 <title>9.5. Key policies &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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: '../../',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]14 VERSION: '1.0.1',
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]17 HAS_SOURCE: false,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]24 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]25 <link rel="index" title="Index" href="../../genindex.html" />
26 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]27 <link rel="next" title="9.6. Key management functions" href="management.html" />
28 <link rel="prev" title="9.4. Key identifiers" href="ids.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]29
30 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
31
32 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
33
34 </head>
35 <body>
36
37
38 <div class="document">
39 <div class="documentwrapper">
40 <div class="bodywrapper">
41 <div class="body" role="main">
42
43 <div class="section" id="key-policies">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]44<span id="key-policy"></span><h1>9.5. Key policies</h1>
45<p>All keys have an associated policy that regulates which operations are permitted on the key. A key policy is composed of two elements:</p>
46<ul class="simple">
47<li>A set of usage flags. See <a class="reference internal" href="#key-usage-flags"><span class="secref">Key usage flags</span></a>.</li>
48<li>A specific algorithm that is permitted with the key. See <a class="reference internal" href="#permitted-algorithms"><span class="secref">Permitted algorithms</span></a>.</li>
49</ul>
50<p>The policy is part of the key attributes that are managed by 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"><span class="pre">psa_key_attributes_t</span></code></a> object.</p>
51<p>A highly constrained implementation might not be able to support all the policies that can be expressed through this interface. If an implementation cannot create a key with the required policy, it must return an appropriate error code when the key is created.</p>
52<div class="section" id="permitted-algorithms">
53<span id="id1"></span><h2>9.5.1. Permitted algorithms</h2>
54<p>The permitted algorithm is encoded using a algorithm identifier, as described in <a class="reference internal" href="../ops/algorithms.html#algorithms"><span class="secref">Algorithms</span></a>.</p>
55<p>This specification only defines policies that restrict keys to a single algorithm, which is consistent with both common practice and security good practice.</p>
56<p>The following algorithm policies are supported:</p>
57<ul class="simple">
58<li><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"><span class="pre">PSA_ALG_NONE</span></code></a> does not allow any cryptographic operation with the key. The key can still be used for non-cryptographic actions such as exporting, if permitted by the usage flags.</li>
59<li>A specific algorithm value permits this particular algorithm.</li>
60<li>A signature algorithm wildcard built from <a class="reference internal" href="../ops/sign.html#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> allows the specified signature scheme with any hash algorithm.</li>
61</ul>
62<p>When a key is used in a cryptographic operation, the application must supply the algorithm to use for the operation. This algorithm is checked against the key’s permitted algorithm policy.</p>
63<div class="section" id="psa_set_key_algorithm">
64<span id="c.psa_set_key_algorithm"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_algorithm</span></code> (function)</h3>
65<p>Declare the permitted algorithm policy for a key.</p>
66<pre class="literal-block">
67void <a class="reference internal" href="#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
68 <a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
69</pre>
70<p class="rubric">Parameters</p>
71<dl class="docutils">
72<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
73<dd>The attribute object to write to.</dd>
74<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
75<dd>The permitted algorithm to write.</dd>
76</dl>
77<p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p>
78<p class="rubric">Description</p>
79<p>The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key.</p>
80<p>This function overwrites any permitted algorithm policy previously set in <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
81<div class="admonition-implementation-note admonition">
82<p class="first admonition-title">Implementation note</p>
83<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>
84<ul class="last simple">
85<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
86<li>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.</li>
87</ul>
88</div>
89</div>
90<div class="section" id="psa_get_key_algorithm">
91<span id="c.psa_get_key_algorithm"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_algorithm</span></code> (function)</h3>
92<p>Retrieve the permitted algorithm policy from key attributes.</p>
93<pre class="literal-block">
94<a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> <a class="reference internal" href="#c.psa_get_key_algorithm" title="psa_get_key_algorithm">psa_get_key_algorithm</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);
95</pre>
96<p class="rubric">Parameters</p>
97<dl class="docutils">
98<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
99<dd>The key attribute object to query.</dd>
100</dl>
101<p class="rubric">Returns: <a class="reference internal" href="../ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code></a></p>
102<p>The algorithm stored in the attribute object.</p>
103<p class="rubric">Description</p>
104<div class="admonition-implementation-note admonition">
105<p class="first admonition-title">Implementation note</p>
106<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>
107<ul class="last simple">
108<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
109<li>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.</li>
110</ul>
111</div>
112</div>
113</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]114<div class="section" id="key-usage-flags">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]115<span id="id2"></span><h2>9.5.2. Key usage flags</h2>
116<p>The usage flags are encoded in a bitmask, which has the type <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_usage_t</span></code></a>. Four kinds of usage flag can be specified:</p>
117<ul class="simple">
118<li>The extractable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a> determines whether the key material can be extracted.</li>
119<li>The copyable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> determines whether the key material can be copied into a new key, which can have a different lifetime or a more restrictive policy.</li>
120<li>The cacheable flag <a class="reference internal" href="#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> determines whether the implementation is permitted to retain non-essential copies of the key material in RAM. This policy only applies to persistent keys. See also <a class="reference internal" href="../../overview/implementation.html#key-material"><span class="secref">Managing key material</span></a>.</li>
121<li>The other usage flags, for example, <a class="reference internal" href="#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> and <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>, determine whether the corresponding operation is permitted on the key.</li>
122</ul>
123<div class="section" id="psa_key_usage_t">
124<span id="c.psa_key_usage_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code> (type)</h3>
125<p>Encoding of permitted usage on a key.</p>
126<pre class="literal-block">
127typedef uint32_t <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>;
128</pre>
129</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]130<div class="section" id="PSA_KEY_USAGE_EXPORT">
131<span id="c.PSA_KEY_USAGE_EXPORT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code> (macro)</h3>
132<p>Permission to export the key.</p>
133<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]134#define <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT">PSA_KEY_USAGE_EXPORT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000001)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]135</pre>
136<p>This flag allows the use of <a class="reference internal" href="management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a> to export a key from the cryptoprocessor. A public key or the public part of a key pair can always be exported regardless of the value of this permission flag.</p>
137<p>This flag can also be required to copy a key using <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> outside of a secure element. See also <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a>.</p>
138<p>If a key does not have export permission, implementations must not allow the key to be exported in plain form from the cryptoprocessor, whether through <a class="reference internal" href="management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a> or through a proprietary interface. The key might still be exportable in a wrapped form, i.e. in a form where it is encrypted by another key.</p>
139</div>
140<div class="section" id="PSA_KEY_USAGE_COPY">
141<span id="c.PSA_KEY_USAGE_COPY"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code> (macro)</h3>
142<p>Permission to copy the key.</p>
143<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]144#define <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY">PSA_KEY_USAGE_COPY</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000002)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]145</pre>
146<p>This flag allows the use of <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> to make a copy of the key with the same policy or a more restrictive policy.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]147<p>For lifetimes for which the key is located in a secure element which enforce the non-exportability of keys, copying a key outside the secure element also requires the usage flag <a class="reference internal" href="#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a>. Copying the key inside the secure element is permitted with just <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> if the secure element supports it. For keys with the lifetime <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"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a> or <a class="reference internal" href="lifetimes.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a>, the usage flag <a class="reference internal" href="#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> is sufficient to permit the copy.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]148</div>
149<div class="section" id="PSA_KEY_USAGE_CACHE">
150<span id="c.PSA_KEY_USAGE_CACHE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code> (macro)</h3>
151<p>Permission for the implementation to cache the key.</p>
152<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]153#define <a class="reference internal" href="#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE">PSA_KEY_USAGE_CACHE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000004)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]154</pre>
155<p>This flag allows the implementation to make additional copies of the key material that are not in storage and not for the purpose of an ongoing operation. Applications can use it as a hint to keep the key around for repeated access.</p>
156<p>An application can request that cached key material is removed from 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"><span class="pre">psa_purge_key()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]157<p>The presence of this usage flag when creating a key is a hint:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]158<ul class="simple">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]159<li>An implementation is not required to cache keys that have this usage flag.</li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]160<li>An implementation must not report an error if it does not cache keys.</li>
161</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]162<p>If this usage flag is not present, the implementation must ensure key material is removed from memory as soon as it is not required for an operation or for maintenance of a volatile key.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]163<p>This flag must be preserved when reading back the attributes for all keys, regardless of key type or implementation behavior.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]164<p>See also <a class="reference internal" href="../../overview/implementation.html#key-material"><span class="secref">Managing key material</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]165</div>
166<div class="section" id="PSA_KEY_USAGE_ENCRYPT">
167<span id="c.PSA_KEY_USAGE_ENCRYPT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code> (macro)</h3>
168<p>Permission to encrypt a message with the key.</p>
169<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]170#define <a class="reference internal" href="#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT">PSA_KEY_USAGE_ENCRYPT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000100)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]171</pre>
172<p>This flag allows the key to be used for a symmetric encryption operation, for an AEAD encryption-and-authentication operation, or for an asymmetric encryption operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p>
173<ul class="simple">
174<li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a></li>
175<li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a></li>
176<li><a class="reference internal" href="../ops/aead.html#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a></li>
177<li><a class="reference internal" href="../ops/aead.html#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a></li>
178<li><a class="reference internal" href="../ops/pke.html#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_encrypt()</span></code></a></li>
179</ul>
180<p>For a key pair, this concerns the public key.</p>
181</div>
182<div class="section" id="PSA_KEY_USAGE_DECRYPT">
183<span id="c.PSA_KEY_USAGE_DECRYPT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code> (macro)</h3>
184<p>Permission to decrypt a message with the key.</p>
185<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]186#define <a class="reference internal" href="#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT">PSA_KEY_USAGE_DECRYPT</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000200)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]187</pre>
188<p>This flag allows the key to be used for a symmetric decryption operation, for an AEAD decryption-and-verification operation, or for an asymmetric decryption operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p>
189<ul class="simple">
190<li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a></li>
191<li><a class="reference internal" href="../ops/ciphers.html#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a></li>
192<li><a class="reference internal" href="../ops/aead.html#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a></li>
193<li><a class="reference internal" href="../ops/aead.html#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a></li>
194<li><a class="reference internal" href="../ops/pke.html#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_decrypt()</span></code></a></li>
195</ul>
196<p>For a key pair, this concerns the private key.</p>
197</div>
198<div class="section" id="PSA_KEY_USAGE_SIGN_MESSAGE">
199<span id="c.PSA_KEY_USAGE_SIGN_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code> (macro)</h3>
200<p>Permission to sign a message with the key.</p>
201<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]202#define <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000400)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]203</pre>
204<p>This flag allows the key to be used for a MAC calculation operation or for an asymmetric message signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p>
205<ul class="simple">
206<li><a class="reference internal" href="../ops/macs.html#c.psa_mac_compute" title="psa_mac_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_compute()</span></code></a></li>
207<li><a class="reference internal" href="../ops/macs.html#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a></li>
208<li><a class="reference internal" href="../ops/sign.html#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a></li>
209</ul>
210<p>For a key pair, this concerns the private key.</p>
211</div>
212<div class="section" id="PSA_KEY_USAGE_VERIFY_MESSAGE">
213<span id="c.PSA_KEY_USAGE_VERIFY_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code> (macro)</h3>
214<p>Permission to verify a message signature with the key.</p>
215<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]216#define <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE">PSA_KEY_USAGE_VERIFY_MESSAGE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00000800)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]217</pre>
218<p>This flag allows the key to be used for a MAC verification operation or for an asymmetric message signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used with the following APIs:</p>
219<ul class="simple">
220<li><a class="reference internal" href="../ops/macs.html#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a></li>
221<li><a class="reference internal" href="../ops/macs.html#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a></li>
222<li><a class="reference internal" href="../ops/sign.html#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a></li>
223</ul>
224<p>For a key pair, this concerns the public key.</p>
225</div>
226<div class="section" id="PSA_KEY_USAGE_SIGN_HASH">
227<span id="c.PSA_KEY_USAGE_SIGN_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code> (macro)</h3>
228<p>Permission to sign a message hash with the key.</p>
229<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]230#define <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH">PSA_KEY_USAGE_SIGN_HASH</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00001000)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]231</pre>
232<p>This flag allows the key to be used to sign a message hash as part of an asymmetric signature operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling <a class="reference internal" href="../ops/sign.html#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]233<p>This flag automatically sets <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>: if an application sets the flag <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a> when creating a key, then the key always has the permissions conveyed by <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>, and the flag <a class="reference internal" href="#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a> will also be present when the application queries the usage flags of the key.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]234<p>For a key pair, this concerns the private key.</p>
235</div>
236<div class="section" id="PSA_KEY_USAGE_VERIFY_HASH">
237<span id="c.PSA_KEY_USAGE_VERIFY_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code> (macro)</h3>
238<p>Permission to verify a message hash with the key.</p>
239<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]240#define <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH">PSA_KEY_USAGE_VERIFY_HASH</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00002000)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]241</pre>
242<p>This flag allows the key to be used to verify a message hash as part of an asymmetric signature verification operation, if otherwise permitted by the key’s type and policy. The flag must be present on keys used when calling <a class="reference internal" href="../ops/sign.html#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]243<p>This flag automatically sets <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>: if an application sets the flag <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a> when creating a key, then the key always has the permissions conveyed by <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>, and the flag <a class="reference internal" href="#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> will also be present when the application queries the usage flags of the key.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]244<p>For a key pair, this concerns the public key.</p>
245</div>
246<div class="section" id="PSA_KEY_USAGE_DERIVE">
247<span id="c.PSA_KEY_USAGE_DERIVE"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code> (macro)</h3>
248<p>Permission to derive other keys from this key.</p>
249<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]250#define <a class="reference internal" href="#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE">PSA_KEY_USAGE_DERIVE</a> ((<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a>)0x00004000)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]251</pre>
252<p>This flag allows the key to be used for a key derivation operation or for a key agreement operation, if otherwise permitted by by the key’s type and policy. The flag must be present on keys used with the following APIs:</p>
253<ul class="simple">
254<li><a class="reference internal" href="../ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a></li>
255<li><a class="reference internal" href="../ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a></li>
256<li><a class="reference internal" href="../ops/ka.html#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a></li>
257</ul>
258</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]259<div class="section" id="psa_set_key_usage_flags">
260<span id="c.psa_set_key_usage_flags"></span><h3><code class="docutils literal"><span class="pre">psa_set_key_usage_flags</span></code> (function)</h3>
261<p>Declare usage flags for a key.</p>
262<pre class="literal-block">
263void <a class="reference internal" href="#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]264 <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a> usage_flags);
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]265</pre>
266<p class="rubric">Parameters</p>
267<dl class="docutils">
268<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
269<dd>The attribute object to write to.</dd>
270<dt> <code class="docutils literal"><span class="pre">usage_flags</span></code></dt>
271<dd>The usage flags to write.</dd>
272</dl>
273<p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p>
274<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]275<p>Usage flags are part of a key’s policy. They encode what kind of operations are permitted on the key. For more details, see <a class="reference internal" href="#key-policy"><span class="secref">Key policies</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]276<p>This function overwrites any usage flags previously set in <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
277<div class="admonition-implementation-note admonition">
278<p class="first admonition-title">Implementation note</p>
279<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>
280<ul class="last simple">
281<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
282<li>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.</li>
283</ul>
284</div>
285</div>
286<div class="section" id="psa_get_key_usage_flags">
287<span id="c.psa_get_key_usage_flags"></span><h3><code class="docutils literal"><span class="pre">psa_get_key_usage_flags</span></code> (function)</h3>
288<p>Retrieve the usage flags from key attributes.</p>
289<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]290<a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t">psa_key_usage_t</a> <a class="reference internal" href="#c.psa_get_key_usage_flags" title="psa_get_key_usage_flags">psa_get_key_usage_flags</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);
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]291</pre>
292<p class="rubric">Parameters</p>
293<dl class="docutils">
294<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
295<dd>The key attribute object to query.</dd>
296</dl>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]297<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_usage_t" title="psa_key_usage_t"><code class="docutils literal"><span class="pre">psa_key_usage_t</span></code></a></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]298<p>The usage flags stored in the attribute object.</p>
299<p class="rubric">Description</p>
300<div class="admonition-implementation-note admonition">
301<p class="first admonition-title">Implementation note</p>
302<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>
303<ul class="last simple">
304<li>This function can be declared as <code class="docutils literal"><span class="pre">static</span></code> or <code class="docutils literal"><span class="pre">inline</span></code>, instead of using the default external linkage.</li>
305<li>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.</li>
306</ul>
307</div>
308</div>
309</div>
310</div>
311
312
313 </div>
314 </div>
315 </div>
316 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]317 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
318IHI 0086<br/>
319Non-confidential<br/>
320Version 1.0.1
321<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]322<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]323<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]324</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]325<ul class="current">
326<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
327<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
328<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
329<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
330<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
331<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
332<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
333<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
334<li class="toctree-l1 current"><a class="reference internal" href="index.html">9. Key management reference</a><ul class="current">
335<li class="toctree-l2"><a class="reference internal" href="attributes.html">9.1. Key attributes</a></li>
336<li class="toctree-l2"><a class="reference internal" href="types.html">9.2. Key types</a></li>
337<li class="toctree-l2"><a class="reference internal" href="lifetimes.html">9.3. Key lifetimes</a></li>
338<li class="toctree-l2"><a class="reference internal" href="ids.html">9.4. Key identifiers</a></li>
339<li class="toctree-l2 current"><a class="current reference internal" href="#">9.5. Key policies</a><ul>
340<li class="toctree-l3"><a class="reference internal" href="#permitted-algorithms">9.5.1. Permitted algorithms</a></li>
341<li class="toctree-l3"><a class="reference internal" href="#key-usage-flags">9.5.2. Key usage flags</a></li>
342</ul>
343</li>
344<li class="toctree-l2"><a class="reference internal" href="management.html">9.6. Key management functions</a></li>
345</ul>
346</li>
347<li class="toctree-l1"><a class="reference internal" href="../ops/index.html">10. Cryptographic operation reference</a></li>
348</ul>
349<ul>
350<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
351<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
352<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
353</ul>
354<ul>
355<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
356</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]357<div id="searchbox" style="display: none" role="search">
358 <h3>Quick search</h3>
359 <form class="search" action="../../search.html" method="get">
360 <div><input type="text" name="q" /></div>
361 <div><input type="submit" value="Go" /></div>
362 <input type="hidden" name="check_keywords" value="yes" />
363 <input type="hidden" name="area" value="default" />
364 </form>
365</div>
366<script type="text/javascript">$('#searchbox').show(0);</script>
367 </div>
368 </div>
369 <div class="clearer"></div>
370 </div>
371 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]372 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]373
374 |
375 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
376 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
377
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]378 </div>
379
380
381
382
383 </body>
384</html>