TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 6c723a2f46051a3543bb7856b41761e84f5a8a15 / . / docs / html / api / keys / management.html
blob: 234fa72c4e49dec252b3626d0505d3ab5f2a5ac6 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame^]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
8 <title>Key management functions &#8212; PSA Crypto API 1.0.0 documentation</title>
9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
14 VERSION: '1.0.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: true,
18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
24 <link rel="index" title="Index" href="../../genindex.html" />
25 <link rel="search" title="Search" href="../../search.html" />
26 <link rel="next" title="Cryptographic operation reference" href="../ops/index.html" />
27 <link rel="prev" title="Algorithms" href="algorithms.html" />
28
29 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
30
31 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
32
33 </head>
34 <body>
35
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <div class="section" id="key-management-functions">
43<h1>Key management functions</h1>
44<div class="section" id="key-creation">
45<span id="id1"></span><h2>Key creation</h2>
46<div class="section" id="psa_import_key">
47<span id="c.psa_import_key"></span><h3><code class="docutils literal"><span class="pre">psa_import_key</span></code> (function)</h3>
48<p>Import a key in binary format.</p>
49<pre class="literal-block">
50<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_import_key" title="psa_import_key">psa_import_key</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,
51 const uint8_t * data,
52 size_t data_length,
53 <a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
54</pre>
55<p class="rubric">Parameters</p>
56<dl class="docutils">
57<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
58<dd>The attributes for the new key. The key size is always determined from the <code class="docutils literal"><span class="pre">data</span></code> buffer. If the key size in <code class="docutils literal"><span class="pre">attributes</span></code> is nonzero, it must be equal to the size from <code class="docutils literal"><span class="pre">data</span></code>.</dd>
59<dt> <code class="docutils literal"><span class="pre">data</span></code></dt>
60<dd>Buffer containing the key data.
61The content of this buffer is interpreted according to the type declared in <code class="docutils literal"><span class="pre">attributes</span></code>.
62All implementations must support at least the format described in the documentation of <a class="reference internal" href="#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 <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> for the chosen type.
63Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.</dd>
64<dt> <code class="docutils literal"><span class="pre">data_length</span></code></dt>
65<dd>Size of the <code class="docutils literal"><span class="pre">data</span></code> buffer in bytes.</dd>
66<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
67<dd>On success, an identifier for the newly created key. <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
68</dl>
69<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
70<dl class="docutils">
71<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
72<dd>Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.</dd>
73<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_ALREADY_EXISTS" title="PSA_ERROR_ALREADY_EXISTS"><code class="docutils literal"><span class="pre">PSA_ERROR_ALREADY_EXISTS</span></code></a></dt>
74<dd>This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.</dd>
75<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
76<dd>The key type or key size is not supported, either by the implementation in general or in this particular persistent location.</dd>
77<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
78<dd>The key attributes, as a whole, are invalid.</dd>
79<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
80<dd>The key data is not correctly formatted.</dd>
81<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
82<dd>The size in <code class="docutils literal"><span class="pre">attributes</span></code> is nonzero and does not match the size of the key data.</dd>
83<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
84<dd></dd>
85<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_STORAGE" title="PSA_ERROR_INSUFFICIENT_STORAGE"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_STORAGE</span></code></a></dt>
86<dd></dd>
87<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
88<dd></dd>
89<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
90<dd></dd>
91<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
92<dd></dd>
93<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
94<dd></dd>
95<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
96<dd></dd>
97<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
98<dd></dd>
99<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
100<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
101</dl>
102<p class="rubric">Description</p>
103<p>This function supports any output from <a class="reference internal" href="#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>. Refer to the documentation of <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> for the format of public keys and to the documentation of <a class="reference internal" href="#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> for the format for other key types.</p>
104<p>The key data determines the key size. The attributes can optionally specify a key size; in this case it must match the size determined from the key data. A key size of <code class="docutils literal"><span class="pre">0</span></code> in <code class="docutils literal"><span class="pre">attributes</span></code> indicates that the key size is solely determined by the key data.</p>
105<p>Implementations must reject an attempt to import a key of size <code class="docutils literal"><span class="pre">0</span></code>.</p>
106<p>This specification defines a single format for each key type. Implementations can optionally support other formats in addition to the standard format. It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.</p>
107</div>
108<div class="section" id="psa_generate_key">
109<span id="c.psa_generate_key"></span><h3><code class="docutils literal"><span class="pre">psa_generate_key</span></code> (function)</h3>
110<p>Generate a key or key pair.</p>
111<pre class="literal-block">
112<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_generate_key" title="psa_generate_key">psa_generate_key</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,
113 <a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
114</pre>
115<p class="rubric">Parameters</p>
116<dl class="docutils">
117<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
118<dd>The attributes for the new key.</dd>
119<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
120<dd>On success, an identifier for the newly created key. <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
121</dl>
122<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
123<dl class="docutils">
124<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
125<dd>Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.</dd>
126<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_ALREADY_EXISTS" title="PSA_ERROR_ALREADY_EXISTS"><code class="docutils literal"><span class="pre">PSA_ERROR_ALREADY_EXISTS</span></code></a></dt>
127<dd>This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.</dd>
128<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
129<dd></dd>
130<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
131<dd></dd>
132<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
133<dd></dd>
134<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_ENTROPY" title="PSA_ERROR_INSUFFICIENT_ENTROPY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></a></dt>
135<dd></dd>
136<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
137<dd></dd>
138<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
139<dd></dd>
140<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
141<dd></dd>
142<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_STORAGE" title="PSA_ERROR_INSUFFICIENT_STORAGE"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_STORAGE</span></code></a></dt>
143<dd></dd>
144<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
145<dd></dd>
146<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
147<dd></dd>
148<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
149<dd></dd>
150<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
151<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
152</dl>
153<p class="rubric">Description</p>
154<p>The key is generated randomly. Its location, usage policy, type and size are taken from <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
155<p>Implementations must reject an attempt to generate a key of size <code class="docutils literal"><span class="pre">0</span></code>.</p>
156<p>The following type-specific considerations apply:</p>
157<ul class="simple">
158<li>For RSA keys (<a class="reference internal" href="types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.</li>
159</ul>
160</div>
161<div class="section" id="psa_copy_key">
162<span id="c.psa_copy_key"></span><h3><code class="docutils literal"><span class="pre">psa_copy_key</span></code> (function)</h3>
163<p>Make a copy of a key.</p>
164<pre class="literal-block">
165<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_copy_key" title="psa_copy_key">psa_copy_key</a>(<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> source_key,
166 const <a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
167 <a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * target_key);
168</pre>
169<p class="rubric">Parameters</p>
170<dl class="docutils">
171<dt> <code class="docutils literal"><span class="pre">source_key</span></code></dt>
172<dd>The key to copy.
173It must allow the usage <a class="reference internal" href="usage.html#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>.
174If a private or secret key is being copied outside of a secure element it must also allow <a class="reference internal" href="usage.html#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>.</dd>
175<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
176<dd><p class="first">The attributes for the new key. They are used as follows:</p>
177<ul class="last simple">
178<li>The key type and size can be <code class="docutils literal"><span class="pre">0</span></code>. If either is nonzero, it must match the corresponding attribute of the source key.</li>
179<li>The key location (the lifetime and, for persistent keys, the key identifier) is used directly.</li>
180<li>The policy constraints (usage flags and algorithm policy) are combined from the source key and <code class="docutils literal"><span class="pre">attributes</span></code> so that both sets of restrictions apply, as described in the documentation of this function.</li>
181</ul>
182</dd>
183<dt> <code class="docutils literal"><span class="pre">target_key</span></code></dt>
184<dd>On success, an identifier for the newly created key. <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
185</dl>
186<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
187<dl class="docutils">
188<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
189<dd></dd>
190<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
191<dd><code class="docutils literal"><span class="pre">source_key</span></code> is invalid.</dd>
192<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_ALREADY_EXISTS" title="PSA_ERROR_ALREADY_EXISTS"><code class="docutils literal"><span class="pre">PSA_ERROR_ALREADY_EXISTS</span></code></a></dt>
193<dd>This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.</dd>
194<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
195<dd>The lifetime or identifier in <code class="docutils literal"><span class="pre">attributes</span></code> are invalid.</dd>
196<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
197<dd>The policy constraints on <code class="docutils literal"><span class="pre">source_key</span></code> and specified in <code class="docutils literal"><span class="pre">attributes</span></code> are incompatible.</dd>
198<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
199<dd><code class="docutils literal"><span class="pre">attributes</span></code> specifies a key type or key size which does not match the attributes of <code class="docutils literal"><span class="pre">source</span> <span class="pre">key</span></code>.</dd>
200<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
201<dd><code class="docutils literal"><span class="pre">source_key</span></code> does not have the <a class="reference internal" href="usage.html#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> usage flag.</dd>
202<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
203<dd><code class="docutils literal"><span class="pre">source_key</span></code> does not have the <a class="reference internal" href="usage.html#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> usage flag and its lifetime does not allow copying it to the target’s lifetime.</dd>
204<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
205<dd></dd>
206<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_STORAGE" title="PSA_ERROR_INSUFFICIENT_STORAGE"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_STORAGE</span></code></a></dt>
207<dd></dd>
208<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
209<dd></dd>
210<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
211<dd></dd>
212<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
213<dd></dd>
214<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
215<dd></dd>
216<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
217<dd></dd>
218<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
219<dd></dd>
220<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
221<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
222</dl>
223<p class="rubric">Description</p>
224<p>Copy key material from one location to another.</p>
225<p>This function is primarily useful to copy a key from one location to another, as it populates a key using the material from another key which can have a different lifetime.</p>
226<p>This function can be used to share a key with a different party, subject to implementation-defined restrictions on key sharing.</p>
227<p>The policy on the source key must have the usage flag <a class="reference internal" href="usage.html#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> set. This flag is sufficient to permit the copy if the key has the lifetime <a class="reference internal" href="locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a> or <a class="reference internal" href="locations.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>. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags <a class="reference internal" href="usage.html#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> and <a class="reference internal" href="usage.html#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> in order to make a copy of the key outside the secure element.</p>
228<p>The resulting key can only be used in a way that conforms to both the policy of the original key and the policy specified in the <code class="docutils literal"><span class="pre">attributes</span></code> parameter:</p>
229<ul class="simple">
230<li>The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in <code class="docutils literal"><span class="pre">attributes</span></code>.</li>
231<li>If both allow the same algorithm or wildcard-based algorithm policy, the resulting key has the same algorithm policy.</li>
232<li>If either of the policies allows an algorithm and the other policy allows a wildcard-based algorithm policy that includes this algorithm, the resulting key allows the same algorithm.</li>
233<li>If the policies do not allow any algorithm in common, this function fails with the status <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a>.</li>
234</ul>
235<p>The effect of this function on implementation-defined attributes is implementation-defined.</p>
236</div>
237</div>
238<div class="section" id="key-destruction">
239<span id="id2"></span><h2>Key destruction</h2>
240<div class="section" id="psa_destroy_key">
241<span id="c.psa_destroy_key"></span><h3><code class="docutils literal"><span class="pre">psa_destroy_key</span></code> (function)</h3>
242<p>Destroy a key.</p>
243<pre class="literal-block">
244<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_destroy_key" title="psa_destroy_key">psa_destroy_key</a>(<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
245</pre>
246<p class="rubric">Parameters</p>
247<dl class="docutils">
248<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
249<dd>Identifier of the key to erase.
250If this is <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a>, do nothing and return <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>.</dd>
251</dl>
252<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
253<dl class="docutils">
254<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
255<dd><code class="docutils literal"><span class="pre">key</span></code> was a valid key identifier and the key material that it referred to has been erased.
256Alternatively, <code class="docutils literal"><span class="pre">key</span></code> is <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a>.</dd>
257<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
258<dd>The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.</dd>
259<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
260<dd><code class="docutils literal"><span class="pre">key</span></code> is not a valid handle nor <a class="reference internal" href="locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a>.</dd>
261<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
262<dd>There was an failure in communication with the cryptoprocessor. The key material might still be present in the cryptoprocessor.</dd>
263<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
264<dd>The storage operation failed. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.</dd>
265<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
266<dd>The storage is corrupted. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.</dd>
267<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
268<dd></dd>
269<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
270<dd>An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor might have been compromised.</dd>
271<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
272<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
273</dl>
274<p class="rubric">Description</p>
275<p>This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations must make a best effort to ensure that that the key material cannot be recovered.</p>
276<p>This function also erases any metadata such as policies and frees resources associated with the key.</p>
277<p>Destroying the key makes the key identifier invalid, and the key identifier must not be used again by the application.</p>
278<p>If a key is currently in use in a multi-part operation, then destroying the key will cause the multi-part operation to fail.</p>
279</div>
280<div class="section" id="psa_purge_key">
281<span id="c.psa_purge_key"></span><h3><code class="docutils literal"><span class="pre">psa_purge_key</span></code> (function)</h3>
282<p>Remove non-essential copies of key material from memory.</p>
283<pre class="literal-block">
284<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_purge_key" title="psa_purge_key">psa_purge_key</a>(<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
285</pre>
286<p class="rubric">Parameters</p>
287<dl class="docutils">
288<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
289<dd>Identifier of the key to purge.</dd>
290</dl>
291<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
292<dl class="docutils">
293<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
294<dd>The key material will have been removed from memory if it is not currently required.</dd>
295<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
296<dd></dd>
297<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
298<dd></dd>
299<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
300<dd></dd>
301<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
302<dd></dd>
303<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
304<dd></dd>
305<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
306<dd></dd>
307<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
308<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
309</dl>
310<p class="rubric">Description</p>
311<p>An implementation is permitted to make additional copies of key material
312For keys that have been created with the <a class="reference internal" href="usage.html#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> policy, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations.</p>
313<p>This function will remove these extra copies of the key material from memory.</p>
314<p>This function is not required to remove key material from memory in any of the following situations:</p>
315<ul class="simple">
316<li>The key is currently in use in a cryptographic operation.</li>
317<li>The key is volatile.</li>
318</ul>
319<p>See also <em><a class="reference internal" href="../../overview/implementation.html#key-material"><span class="std std-ref">Managing key material</span></a></em>.</p>
320</div>
321</div>
322<div class="section" id="key-export">
323<span id="id3"></span><h2>Key export</h2>
324<div class="section" id="psa_export_key">
325<span id="c.psa_export_key"></span><h3><code class="docutils literal"><span class="pre">psa_export_key</span></code> (function)</h3>
326<p>Export a key in binary format.</p>
327<pre class="literal-block">
328<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_export_key" title="psa_export_key">psa_export_key</a>(<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
329 uint8_t * data,
330 size_t data_size,
331 size_t * data_length);
332</pre>
333<p class="rubric">Parameters</p>
334<dl class="docutils">
335<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
336<dd>Identifier of the key to export.
337It must allow the usage <a class="reference internal" href="usage.html#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>, unless it is a public key.</dd>
338<dt> <code class="docutils literal"><span class="pre">data</span></code></dt>
339<dd>Buffer where the key data is to be written.</dd>
340<dt> <code class="docutils literal"><span class="pre">data_size</span></code></dt>
341<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">data</span></code> buffer in bytes.
342This must be appropriate for the key:</p>
343<ul class="last simple">
344<li>The required output size is <a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">bits</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">type</span></code> is the key type and <code class="docutils literal"><span class="pre">bits</span></code> is the key size in bits.</li>
345<li>For asymmetric keys, <a class="reference internal" href="#c.PSA_EXPORT_KEY_PAIR_MAX_SIZE" title="PSA_EXPORT_KEY_PAIR_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_KEY_PAIR_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported public key or key pair.</li>
346</ul>
347</dd>
348<dt> <code class="docutils literal"><span class="pre">data_length</span></code></dt>
349<dd>On success, the number of bytes that make up the key data.</dd>
350</dl>
351<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
352<dl class="docutils">
353<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
354<dd></dd>
355<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
356<dd></dd>
357<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
358<dd>The key does not have the <a class="reference internal" href="usage.html#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> flag.</dd>
359<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
360<dd></dd>
361<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
362<dd>The size of the <code class="docutils literal"><span class="pre">data</span></code> buffer is too small.
363<a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_EXPORT_KEY_PAIR_MAX_SIZE" title="PSA_EXPORT_KEY_PAIR_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_KEY_PAIR_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
364<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
365<dd></dd>
366<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
367<dd></dd>
368<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
369<dd></dd>
370<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
371<dd></dd>
372<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
373<dd></dd>
374<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
375<dd></dd>
376<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
377<dd></dd>
378<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
379<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
380</dl>
381<p class="rubric">Description</p>
382<p>The output of this function can be passed to <a class="reference internal" href="#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> to create an equivalent object.</p>
383<p>If the implementation of <a class="reference internal" href="#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> supports other formats beyond the format specified here, the output from <a class="reference internal" href="#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> must use the representation specified here, not the original representation.</p>
384<p>For standard key types, the output format is as follows:</p>
385<ul class="simple">
386<li>For symmetric keys, including MAC keys, the format is the raw bytes of the key.</li>
387<li>For DES, the key data consists of 8 bytes. The parity bits must be correct.</li>
388<li>For Triple-DES, the format is the concatenation of the two or three DES keys.</li>
389<li>For RSA key pairs, with key type <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>, the format is the non-encrypted DER encoding of the representation defined by PKCS#1 in <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html">RFC 8017</a> as <code class="docutils literal"><span class="pre">RSAPrivateKey</span></code>, version <code class="docutils literal"><span class="pre">0</span></code>.</li>
390<li>For elliptic curve key pairs, with key types for which <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_IS_ECC_KEY_PAIR" title="PSA_KEY_TYPE_IS_ECC_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_IS_ECC_KEY_PAIR()</span></code></a> is true, the format is a representation of the private value.<ul>
391<li>For Weierstrass curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>, <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a> and <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a>, the content of the <code class="docutils literal"><span class="pre">privateKey</span></code> field of the <code class="docutils literal"><span class="pre">ECPrivateKey</span></code> format defined by <a class="reference external" href="https://tools.ietf.org/html/rfc5915.html">RFC 5915</a>. This is a <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code>-byte string in big-endian order where <code class="docutils literal"><span class="pre">m</span></code> is the key size in bits.</li>
392<li>For curve family <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, the scalar value of the ‘private key’ in little-endian order as defined by <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-6">RFC 7748 §6</a>. This is a <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code>-byte string where <code class="docutils literal"><span class="pre">m</span></code> is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.</li>
393</ul>
394</li>
395<li>For Diffie-Hellman key exchange key pairs, with key types for which <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_IS_DH_KEY_PAIR" title="PSA_KEY_TYPE_IS_DH_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_IS_DH_KEY_PAIR()</span></code></a> is true, the format is the representation of the private key <code class="docutils literal"><span class="pre">x</span></code> as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.</li>
396<li>For public keys, with key types for which <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_IS_PUBLIC_KEY" title="PSA_KEY_TYPE_IS_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_IS_PUBLIC_KEY()</span></code></a> is true, the format is the same as for <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>.</li>
397</ul>
398<p>The policy on the key must have the usage flag <a class="reference internal" href="usage.html#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> set.</p>
399</div>
400<div class="section" id="psa_export_public_key">
401<span id="c.psa_export_public_key"></span><h3><code class="docutils literal"><span class="pre">psa_export_public_key</span></code> (function)</h3>
402<p>Export a public key or the public part of a key pair in binary format.</p>
403<pre class="literal-block">
404<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key">psa_export_public_key</a>(<a class="reference internal" href="attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
405 uint8_t * data,
406 size_t data_size,
407 size_t * data_length);
408</pre>
409<p class="rubric">Parameters</p>
410<dl class="docutils">
411<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
412<dd>Identifier of the key to export.</dd>
413<dt> <code class="docutils literal"><span class="pre">data</span></code></dt>
414<dd>Buffer where the key data is to be written.</dd>
415<dt> <code class="docutils literal"><span class="pre">data_size</span></code></dt>
416<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">data</span></code> buffer in bytes.
417This must be appropriate for the key:</p>
418<ul class="last simple">
419<li>The required output size is <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE" title="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">bits</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">type</span></code> is the key type and <code class="docutils literal"><span class="pre">bits</span></code> is the key size in bits.</li>
420<li><a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE" title="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported public key or public part of a key pair.</li>
421</ul>
422</dd>
423<dt> <code class="docutils literal"><span class="pre">data_length</span></code></dt>
424<dd>On success, the number of bytes that make up the key data.</dd>
425</dl>
426<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
427<dl class="docutils">
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
429<dd></dd>
430<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
431<dd></dd>
432<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
433<dd>The key is neither a public key nor a key pair.</dd>
434<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
435<dd></dd>
436<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
437<dd>The size of the <code class="docutils literal"><span class="pre">data</span></code> buffer is too small.
438<a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE" title="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE" title="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
439<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
440<dd></dd>
441<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
442<dd></dd>
443<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
444<dd></dd>
445<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
446<dd></dd>
447<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
448<dd></dd>
449<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
450<dd></dd>
451<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
452<dd></dd>
453<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
454<dd>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
455</dl>
456<p class="rubric">Description</p>
457<p>The output of this function can be passed to <a class="reference internal" href="#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> to create an object that is equivalent to the public key.</p>
458<p>If the implementation of <a class="reference internal" href="#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> supports other formats beyond the format specified here, the output from <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> must use the representation specified here, not the original representation.</p>
459<p>For standard key types, the output format is as follows:</p>
460<ul class="simple">
461<li>For RSA public keys, with key type <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_RSA_PUBLIC_KEY" title="PSA_KEY_TYPE_RSA_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_PUBLIC_KEY</span></code></a>, the DER encoding of the representation defined by <a class="reference external" href="https://tools.ietf.org/html/rfc3279.html#section-2.3.1">RFC 3279 §2.3.1</a> as <code class="docutils literal"><span class="pre">RSAPublicKey</span></code>.</li>
462<li>For elliptic curve key pairs, with key types for which <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY" title="PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY()</span></code></a> is true, the format depends on the key family:<ul>
463<li>For Weierstrass curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>, <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a> and <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a>, the uncompressed representation defined by <em>Standards for Efficient Cryptography</em>, <a class="reference external" href="https://www.secg.org/sec1-v2.pdf"><em>SEC 1: Elliptic Curve Cryptography</em></a> §2.3.3 as the content of an <code class="docutils literal"><span class="pre">ECPoint</span></code>. If <code class="docutils literal"><span class="pre">m</span></code> is the bit size associated with the curve, i.e. the bit size of <code class="docutils literal"><span class="pre">q</span></code> for a curve over <code class="docutils literal"><span class="pre">F_q</span></code>. The representation consists of:<ul>
464<li>The byte <code class="docutils literal"><span class="pre">0x04</span></code>;</li>
465<li><code class="docutils literal"><span class="pre">x_P</span></code> as a <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code>-byte string, big-endian;</li>
466<li><code class="docutils literal"><span class="pre">y_P</span></code> as a <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code>-byte string, big-endian.</li>
467</ul>
468</li>
469<li>For curve family <a class="reference internal" href="types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, the scalar value of the ‘public key’ in little-endian order as defined by <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-6">RFC 7748 §6</a>. This is a <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code>-byte string where <code class="docutils literal"><span class="pre">m</span></code> is the key size in bits.<ul>
470<li>This is 32 bytes for Curve25519, computed as <code class="docutils literal"><span class="pre">X25519(private_key,</span> <span class="pre">9)</span></code>.</li>
471<li>This is 56 bytes for Curve448, computed as <code class="docutils literal"><span class="pre">X448(private_key,</span> <span class="pre">5)</span></code>.</li>
472</ul>
473</li>
474</ul>
475</li>
476<li>For Diffie-Hellman key exchange public keys, with key types for which <a class="reference internal" href="types.html#c.PSA_KEY_TYPE_IS_DH_PUBLIC_KEY" title="PSA_KEY_TYPE_IS_DH_PUBLIC_KEY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_IS_DH_PUBLIC_KEY</span></code></a> is true, the format is the representation of the public key <code class="docutils literal"><span class="pre">y</span> <span class="pre">=</span> <span class="pre">g^x</span> <span class="pre">mod</span> <span class="pre">p</span></code> as a big-endian byte string. The length of the byte string is the length of the base prime <code class="docutils literal"><span class="pre">p</span></code> in bytes.</li>
477</ul>
478<p>Exporting a public key object or the public part of a key pair is always permitted, regardless of the key’s usage flags.</p>
479</div>
480<div class="section" id="PSA_EXPORT_KEY_OUTPUT_SIZE">
481<span id="c.PSA_EXPORT_KEY_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE</span></code> (macro)</h3>
482<p>Sufficient output buffer size for <a class="reference internal" href="#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>.</p>
483<pre class="literal-block">
484#define <a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE">PSA_EXPORT_KEY_OUTPUT_SIZE</a>(key_type, key_bits) \
485 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
486</pre>
487<p class="rubric">Parameters</p>
488<dl class="docutils">
489<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
490<dd>A supported key type.</dd>
491<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
492<dd>The size of the key in bits.</dd>
493</dl>
494<p class="rubric">Returns</p>
495<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#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 <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> will not fail with <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a>. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or <code class="docutils literal"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
496<p class="rubric">Description</p>
497<p>This macro returns a compile-time constant if its arguments are compile-time constants.</p>
498<div class="admonition warning">
499<p class="first admonition-title">Warning</p>
500<p class="last">This function can evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.</p>
501</div>
502<p>The following code illustrates how to allocate enough memory to export a key by querying the key type and size at runtime.</p>
503<pre class="literal-block">
504<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes = <a class="reference internal" href="attributes.html#c.PSA_KEY_ATTRIBUTES_INIT" title="PSA_KEY_ATTRIBUTES_INIT">PSA_KEY_ATTRIBUTES_INIT</a>;
505<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> status;
506status = <a class="reference internal" href="attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes">psa_get_key_attributes</a>(key, &amp;attributes);
507if (status != <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS">PSA_SUCCESS</a>)
508 handle_error(...);
509<a class="reference internal" href="attributes.html#c.psa_key_type_t" title="psa_key_type_t">psa_key_type_t</a> key_type = <a class="reference internal" href="types.html#c.psa_get_key_type" title="psa_get_key_type">psa_get_key_type</a>(&amp;attributes);
510size_t key_bits = <a class="reference internal" href="types.html#c.psa_get_key_bits" title="psa_get_key_bits">psa_get_key_bits</a>(&amp;attributes);
511size_t buffer_size = <a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE">PSA_EXPORT_KEY_OUTPUT_SIZE</a>(key_type, key_bits);
512<a class="reference internal" href="attributes.html#c.psa_reset_key_attributes" title="psa_reset_key_attributes">psa_reset_key_attributes</a>(&amp;attributes);
513uint8_t *buffer = malloc(buffer_size);
514if (buffer == NULL)
515 handle_error(...);
516size_t buffer_length;
517status = <a class="reference internal" href="#c.psa_export_key" title="psa_export_key">psa_export_key</a>(key, buffer, buffer_size, &amp;buffer_length);
518if (status != <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS">PSA_SUCCESS</a>)
519 handle_error(...);
520</pre>
521<p>See also <a class="reference internal" href="#c.PSA_EXPORT_KEY_PAIR_MAX_SIZE" title="PSA_EXPORT_KEY_PAIR_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_KEY_PAIR_MAX_SIZE</span></code></a> and <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE" title="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code></a>.</p>
522</div>
523<div class="section" id="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE">
524<span id="c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE</span></code> (macro)</h3>
525<p>Sufficient output buffer size for <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>.</p>
526<pre class="literal-block">
527#define <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE" title="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE</a>(key_type, key_bits) \
528 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
529</pre>
530<p class="rubric">Parameters</p>
531<dl class="docutils">
532<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
533<dd>A public key or key pair key type.</dd>
534<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
535<dd>The size of the key in bits.</dd>
536</dl>
537<p class="rubric">Returns</p>
538<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> will not fail with <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a>. If the parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or <code class="docutils literal"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
539<p>If the parameters are valid and supported, it is recommended that this macro returns the same result as <a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="types.html#c.PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR" title="PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_PUBLIC_KEY_OF_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">key_type</span></code><code class="docutils literal"><span class="pre">),</span> </code><code class="docutils literal"><span class="pre">key_bits</span></code><code class="docutils literal"><span class="pre">)</span></code>.</p>
540<p class="rubric">Description</p>
541<p>This macro returns a compile-time constant if its arguments are compile-time constants.</p>
542<div class="admonition warning">
543<p class="first admonition-title">Warning</p>
544<p class="last">This function can evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.</p>
545</div>
546<p>The following code illustrates how to allocate enough memory to export a public key by querying the key type and size at runtime.</p>
547<pre class="literal-block">
548<a class="reference internal" href="attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> attributes = <a class="reference internal" href="attributes.html#c.PSA_KEY_ATTRIBUTES_INIT" title="PSA_KEY_ATTRIBUTES_INIT">PSA_KEY_ATTRIBUTES_INIT</a>;
549<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> status;
550status = <a class="reference internal" href="attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes">psa_get_key_attributes</a>(key, &amp;attributes);
551if (status != <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS">PSA_SUCCESS</a>)
552 handle_error(...);
553<a class="reference internal" href="attributes.html#c.psa_key_type_t" title="psa_key_type_t">psa_key_type_t</a> key_type = <a class="reference internal" href="types.html#c.psa_get_key_type" title="psa_get_key_type">psa_get_key_type</a>(&amp;attributes);
554size_t key_bits = <a class="reference internal" href="types.html#c.psa_get_key_bits" title="psa_get_key_bits">psa_get_key_bits</a>(&amp;attributes);
555size_t buffer_size = <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE" title="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE</a>(key_type, key_bits);
556<a class="reference internal" href="attributes.html#c.psa_reset_key_attributes" title="psa_reset_key_attributes">psa_reset_key_attributes</a>(&amp;attributes);
557uint8_t *buffer = malloc(buffer_size);
558if (buffer == NULL)
559 handle_error(...);
560size_t buffer_length;
561status = <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key">psa_export_public_key</a>(key, buffer, buffer_size, &amp;buffer_length);
562if (status != <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS">PSA_SUCCESS</a>)
563 handle_error(...);
564</pre>
565<p>See also <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE" title="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code></a>.</p>
566</div>
567<div class="section" id="PSA_EXPORT_KEY_PAIR_MAX_SIZE">
568<span id="c.PSA_EXPORT_KEY_PAIR_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_PAIR_MAX_SIZE</span></code> (macro)</h3>
569<p>Sufficient buffer size for exporting any asymmetric key pair.</p>
570<pre class="literal-block">
571#define <a class="reference internal" href="#c.PSA_EXPORT_KEY_PAIR_MAX_SIZE" title="PSA_EXPORT_KEY_PAIR_MAX_SIZE">PSA_EXPORT_KEY_PAIR_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
572</pre>
573<p>This macro must expand to a compile-time constant integer.
574This value must be a sufficient buffer size when calling <a class="reference internal" href="#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 any asymmetric key pair that is supported by the implementation, regardless of the exact key type and key size.</p>
575<p>See also <a class="reference internal" href="#c.PSA_EXPORT_KEY_OUTPUT_SIZE" title="PSA_EXPORT_KEY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE()</span></code></a>.</p>
576</div>
577<div class="section" id="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE">
578<span id="c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code> (macro)</h3>
579<p>Sufficient buffer size for exporting any asymmetric public key.</p>
580<pre class="literal-block">
581#define <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_MAX_SIZE" title="PSA_EXPORT_PUBLIC_KEY_MAX_SIZE">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
582</pre>
583<p>This macro must expand to a compile-time constant integer.
584This value must be a sufficient buffer size when calling <a class="reference internal" href="#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 <a class="reference internal" href="#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a> to export any asymmetric public key that is supported by the implementation, regardless of the exact key type and key size.</p>
585<p>See also <a class="reference internal" href="#c.PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE" title="PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE()</span></code></a>.</p>
586</div>
587</div>
588</div>
589
590
591 </div>
592 </div>
593 </div>
594 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
595 <div class="sphinxsidebarwrapper">
596 <h3><a href="../../index.html">Table Of Contents</a></h3>
597 <ul>
598<li><a class="reference internal" href="#">Key management functions</a><ul>
599<li><a class="reference internal" href="#key-creation">Key creation</a><ul>
600<li><a class="reference internal" href="#psa_import_key"><code class="docutils literal"><span class="pre">psa_import_key</span></code> (function)</a></li>
601<li><a class="reference internal" href="#psa_generate_key"><code class="docutils literal"><span class="pre">psa_generate_key</span></code> (function)</a></li>
602<li><a class="reference internal" href="#psa_copy_key"><code class="docutils literal"><span class="pre">psa_copy_key</span></code> (function)</a></li>
603</ul>
604</li>
605<li><a class="reference internal" href="#key-destruction">Key destruction</a><ul>
606<li><a class="reference internal" href="#psa_destroy_key"><code class="docutils literal"><span class="pre">psa_destroy_key</span></code> (function)</a></li>
607<li><a class="reference internal" href="#psa_purge_key"><code class="docutils literal"><span class="pre">psa_purge_key</span></code> (function)</a></li>
608</ul>
609</li>
610<li><a class="reference internal" href="#key-export">Key export</a><ul>
611<li><a class="reference internal" href="#psa_export_key"><code class="docutils literal"><span class="pre">psa_export_key</span></code> (function)</a></li>
612<li><a class="reference internal" href="#psa_export_public_key"><code class="docutils literal"><span class="pre">psa_export_public_key</span></code> (function)</a></li>
613<li><a class="reference internal" href="#PSA_EXPORT_KEY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_OUTPUT_SIZE</span></code> (macro)</a></li>
614<li><a class="reference internal" href="#PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE</span></code> (macro)</a></li>
615<li><a class="reference internal" href="#PSA_EXPORT_KEY_PAIR_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_KEY_PAIR_MAX_SIZE</span></code> (macro)</a></li>
616<li><a class="reference internal" href="#PSA_EXPORT_PUBLIC_KEY_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_EXPORT_PUBLIC_KEY_MAX_SIZE</span></code> (macro)</a></li>
617</ul>
618</li>
619</ul>
620</li>
621</ul>
622<div class="relations">
623<h3>Related Topics</h3>
624<ul>
625 <li><a href="../../index.html">Documentation overview</a><ul>
626 <li><a href="index.html">Key management reference</a><ul>
627 <li>Previous: <a href="algorithms.html" title="previous chapter">Algorithms</a></li>
628 <li>Next: <a href="../ops/index.html" title="next chapter">Cryptographic operation reference</a></li>
629 </ul></li>
630 </ul></li>
631</ul>
632</div>
633 <div role="note" aria-label="source link">
634 <h3>This Page</h3>
635 <ul class="this-page-menu">
636 <li><a href="../../_sources/api/keys/management.rst.txt"
637 rel="nofollow">Show Source</a></li>
638 </ul>
639 </div>
640<div id="searchbox" style="display: none" role="search">
641 <h3>Quick search</h3>
642 <form class="search" action="../../search.html" method="get">
643 <div><input type="text" name="q" /></div>
644 <div><input type="submit" value="Go" /></div>
645 <input type="hidden" name="check_keywords" value="yes" />
646 <input type="hidden" name="area" value="default" />
647 </form>
648</div>
649<script type="text/javascript">$('#searchbox').show(0);</script>
650 </div>
651 </div>
652 <div class="clearer"></div>
653 </div>
654 <div class="footer">
655 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
656
657 |
658 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
659 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
660
661 |
662 <a href="../../_sources/api/keys/management.rst.txt"
663 rel="nofollow">Page source</a>
664 </div>
665
666
667
668
669 </body>
670</html>