TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 882f7c72267ee598fd4f7c0d34b2c70760c76d8c / . / docs / 1.1.0 / html / overview / implementation.html
blob: 61d40b138d12e7c0eccda8ac04cf9d90c3151ad6 [file] [log] [blame]
Gilles Peskine882f7c72022-04-07 13:44:55 +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>6. Implementation considerations &#8212; PSA Crypto API 1.1.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.1.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: false,
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="author" title="About these documents" href="../about.html" />
25 <link rel="index" title="Index" href="../genindex.html" />
26 <link rel="search" title="Search" href="../search.html" />
27 <link rel="next" title="7. Usage considerations" href="usage.html" />
28 <link rel="prev" title="5. Library conventions" href="conventions.html" />
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="implementation-considerations">
44<span id="id1"></span><h1>6. Implementation considerations</h1>
45<div class="section" id="implementation-specific-aspects-of-the-interface">
46<h2>6.1. Implementation-specific aspects of the interface</h2>
47<div class="section" id="implementation-profile">
48<h3>6.1.1. Implementation profile</h3>
49<p>Implementations can implement a subset of the API and a subset of the available
50algorithms. The implemented subset is known as the implementation’s profile. The
51documentation for each implementation must describe the profile that it
52implements. This specification’s companion documents also define a number of
53standard profiles.</p>
54</div>
55<div class="section" id="implementation-specific-types">
56<span id="implementation-defined-type"></span><h3>6.1.2. Implementation-specific types</h3>
57<p>This specification defines a number of implementation-specific types, which
58represent objects whose content depends on the implementation. These are defined
59as C <code class="docutils literal"><span class="pre">typedef</span></code> types in this specification, with a comment
60<em><a class="reference internal" href="#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> in place of the underlying type
61definition. For some types the specification constrains the type, for example,
62by requiring that the type is a <code class="docutils literal"><span class="pre">struct</span></code>, or that it is convertible to and
63from an unsigned integer. In the implementation’s version of <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code>,
64these types need to be defined as complete C types so that objects of these
65types can be instantiated by application code.</p>
66<p>Applications that rely on the implementation specific definition of any of these
67types might not be portable to other implementations of this specification.</p>
68</div>
69<div class="section" id="implementation-specific-macros">
70<span id="implementation-specific-macro"></span><h3>6.1.3. Implementation-specific macros</h3>
71<p>Some macro constants and function-like macros are precisely defined by this
72specification. The use of an exact definition is essential if the definition can
73appear in more than one header file within a compilation.</p>
74<p>Other macros that are defined by this specification have a macro body that is
75implementation-specific. The description of an implementation-specific macro can
76optionally specify each of the following requirements:</p>
77<ul class="simple">
78<li>Input domains: the macro must be valid for arguments within the input domain.</li>
79<li>A return type: the macro result must be compatible with this type.</li>
80<li>Output range: the macro result must lie in the output range.</li>
81<li>Computed value: A precise mapping of valid input to output values.</li>
82</ul>
83<p>Each implementation-specific macro is in one of following categories:</p>
84<dl class="docutils" id="specification-defined-value">
85<dt><em>Specification-defined value</em></dt>
86<dd><p class="first">The result type and computed value of the macro expression is defined by
87this specification, but the definition of the macro body is provided by the
88implementation.</p>
89<p>These macros are indicated in this specification using the comment
90<em><a class="reference internal" href="#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>.</p>
91<p>For function-like macros with specification-defined values:</p>
92<ul class="last simple">
93<li>Example implementations are provided in an appendix to this specification.
94See <a class="reference internal" href="../appendix/specdef_values.html#appendix-specdef-values"><span class="secref">Example macro implementations</span></a>.</li>
95<li>The expected computation for valid and supported input arguments will be
96defined as pseudo-code in a future version of this specification.</li>
97</ul>
98</dd>
99</dl>
100<dl class="docutils" id="implementation-defined-value">
101<dt><em>Implementation-defined value</em></dt>
102<dd><p class="first">The value of the macro expression is implementation-defined.</p>
103<p>For some macros, the computed value is derived from the specification of one
104or more cryptographic algorithms. In these cases, the result must exactly
105match the value in those external specifications.</p>
106<p class="last">These macros are indicated in this specification using the comment
107<em><a class="reference internal" href="#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>.</p>
108</dd>
109</dl>
110<p>Some of these macros compute a result based on an algorithm or key type.
111If an implementation defines vendor-specific algorithms or
112key types, then it must provide an implementation for such macros that takes all
113relevant algorithms and types into account. Conversely, an implementation that
114does not support a certain algorithm or key type can define such macros in a
115simpler way that does not take unsupported argument values into account.</p>
116<p>Some macros define the minimum sufficient output buffer size for certain
117functions. In some cases, an implementation is allowed to require a buffer size
118that is larger than the theoretical minimum. An implementation must define
119minimum-size macros in such a way that it guarantees that the buffer of the
120resulting size is sufficient for the output of the corresponding function. Refer
121to each macro’s documentation for the applicable requirements.</p>
122</div>
123</div>
124<div class="section" id="porting-to-a-platform">
125<h2>6.2. Porting to a platform</h2>
126<div class="section" id="platform-assumptions">
127<h3>6.2.1. Platform assumptions</h3>
128<p>This specification is designed for a C99 platform. The interface is defined in
129terms of C macros, functions and objects.</p>
130<p>The specification assumes 8-bit bytes, and “byte” and “octet” are used
131synonymously.</p>
132</div>
133<div class="section" id="platform-specific-types">
134<h3>6.2.2. Platform-specific types</h3>
135<p>The specification makes use of some types defined in C99. These types must be
136defined in the implementation version of <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code> or by a header
137included in this file. The following C99 types are used:</p>
138<dl class="docutils">
139<dt><code class="docutils literal"><span class="pre">uint8_t</span></code>, <code class="docutils literal"><span class="pre">uint16_t</span></code>, <code class="docutils literal"><span class="pre">uint32_t</span></code></dt>
140<dd>Unsigned integer types with 8, 16 and 32 value bits respectively.
141These types are defined by the C99 header <code class="file docutils literal"><span class="pre">stdint.h</span></code>.</dd>
142</dl>
143</div>
144<div class="section" id="cryptographic-hardware-support">
145<h3>6.2.3. Cryptographic hardware support</h3>
146<p>Implementations are encouraged to make use of hardware accelerators where
147available. A future version of this specification will define a function
148interface that calls drivers for hardware accelerators and external
149cryptographic hardware.</p>
150</div>
151</div>
152<div class="section" id="security-requirements-and-recommendations">
153<h2>6.3. Security requirements and recommendations</h2>
154<div class="section" id="error-detection">
155<h3>6.3.1. Error detection</h3>
156<p>Implementations that provide <a class="reference internal" href="../about.html#term-isolation"><span class="term">isolation</span></a> between the caller and the cryptography
157processing environment must validate parameters to ensure that the cryptography
158processing environment is protected from attacks caused by passing invalid
159parameters.</p>
160<p>Even implementations that do not provide isolation are recommended to detect bad
161parameters and fail-safe where possible.</p>
162</div>
163<div class="section" id="indirect-object-references">
164<h3>6.3.2. Indirect object references</h3>
165<p>Implementations can use different strategies for allocating key identifiers,
166and other types of indirect object reference.</p>
167<p>Implementations that provide isolation between the caller and the cryptography
168processing environment must consider the threats relating to abuse and misuse
169of key identifiers and other indirect resource references. For example,
170multi-part operations can be implemented as backend state to which the client
171only maintains an indirect reference in the application’s multi-part operation
172object.</p>
173<p>An implementation that supports multiple callers must implement strict isolation
174of API resources between different callers. For example, a client must not be
175able to obtain a reference to another client’s key by guessing the key
176identifier value. Isolation of key identifiers can be achieved in several ways.
177For example:</p>
178<ul class="simple">
179<li>There is a single identifier namespace for all clients, and the
180implementation verifies that the client is the owner of the identifier when
181looking up the key.</li>
182<li>Each client has an independent identifier namespace, and the implementation
183uses a client specific identifier-to-key mapping when looking up the key.</li>
184</ul>
185<p>After a volatile key identifier is destroyed, it is recommended that the
186implementation does not immediately reuse the same identifier value for a
187different key. This reduces the risk of an attack that is able to exploit a key
188identifier reuse vulnerability within an application.</p>
189</div>
190<div class="section" id="memory-cleanup">
191<span id="id2"></span><h3>6.3.3. Memory cleanup</h3>
192<p>Implementations must wipe all sensitive data from memory when it is no longer
193used. It is recommended that they wipe this sensitive data as soon as possible. All
194temporary data used during the execution of a function, such as stack buffers,
195must be wiped before the function returns. All data associated with an object,
196such as a multi-part operation, must be wiped, at the latest, when the object
197becomes inactive, for example, when a multi-part operation is aborted.</p>
198<p>The rationale for this non-functional requirement is to minimize impact if the
199system is compromised. If sensitive data is wiped immediately after use, only
200data that is currently in use can be leaked. It does not compromise past data.</p>
201</div>
202<div class="section" id="managing-key-material">
203<span id="key-material"></span><h3>6.3.4. Managing key material</h3>
204<p>In implementations that have limited volatile memory for keys, the
205implementation is permitted to store a <a class="reference internal" href="../about.html#term-volatile-key"><span class="term">volatile key</span></a> to a
206temporary location in non-volatile memory. The implementation must delete any
207non-volatile copies when the key is destroyed, and it is recommended that these copies
208are deleted as soon as the key is reloaded into volatile memory. An
209implementation that uses this method must clear any stored volatile key material
210on startup.</p>
211<p>Implementing the memory cleanup rule (see <a class="reference internal" href="#memory-cleanup"><span class="secref">Memory cleanup</span></a>) for a <a class="reference internal" href="../about.html#term-persistent-key"><span class="term">persistent key</span></a>
212can result in inefficiencies when the same persistent key is used sequentially
213in multiple cryptographic operations. The inefficiency stems from loading the
214key from non-volatile storage on each use of the key. The <a class="reference internal" href="../api/keys/policy.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>
215usage flag in a key policy allows an application to request that the implementation does not cleanup
216non-essential copies of persistent key material, effectively suspending the
217cleanup rules for that key. The effects of this policy depend on the
218implementation and the key, for example:</p>
219<ul class="simple">
220<li>For volatile keys or keys in a secure element with no open/close mechanism,
221this is likely to have no effect.</li>
222<li>For persistent keys that are not in a secure element, this allows the
223implementation to keep the key in a memory cache outside of the memory used
224by ongoing operations.</li>
225<li>For keys in a secure element with an open/close mechanism, this is a hint to
226keep the key open in the secure element.</li>
227</ul>
228<p>The application can indicate when it has finished using the key by calling
229<a class="reference internal" href="../api/keys/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>, to request that the key material is cleaned from memory.</p>
230</div>
231<div class="section" id="safe-outputs-on-error">
232<h3>6.3.5. Safe outputs on error</h3>
233<p>Implementations must ensure that confidential data is not written to output
234parameters before validating that the disclosure of this confidential data is
235authorized. This requirement is particularly important for implementations where
236the caller can share memory with another security context, as described in
237<a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</p>
238<p>In most cases, the specification does not define the content of output
239parameters when an error occurs. It is recommended that implementations try to
240ensure that the content of output parameters is as safe as possible, in case an
241application flaw or a data leak causes it to be used. In particular, Arm
242recommends that implementations avoid placing partial output in output buffers
243when an action is interrupted. The meaning of “safe as possible” depends on the
244implementation, as different environments require different compromises between
245implementation complexity, overall robustness and performance. Some common
246strategies are to leave output parameters unchanged, in case of errors, or
247zeroing them out.</p>
248</div>
249<div class="section" id="attack-resistance">
250<h3>6.3.6. Attack resistance</h3>
251<p>Cryptographic code tends to manipulate high-value secrets, from which other
252secrets can be unlocked. As such, it is a high-value target for attacks. There
253is a vast body of literature on attack types, such as side channel attacks and
254glitch attacks. Typical side channels include timing, cache access patterns,
255branch-prediction access patterns, power consumption, radio emissions and more.</p>
256<p>This specification does not specify particular requirements for attack
257resistance. Implementers are encouraged to consider the attack resistance
258desired in each use case and design their implementation accordingly. Security
259standards for attack resistance for particular targets might be applicable in
260certain use cases.</p>
261</div>
262</div>
263<div class="section" id="other-implementation-considerations">
264<h2>6.4. Other implementation considerations</h2>
265<div class="section" id="philosophy-of-resource-management">
266<h3>6.4.1. Philosophy of resource management</h3>
267<p>The specification allows most functions to return
268<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a>. This gives implementations the freedom to
269manage memory as they please.</p>
270<p>Alternatively, the interface is also designed for conservative strategies of
271memory management. An implementation can avoid dynamic memory allocation
272altogether by obeying certain restrictions:</p>
273<ul class="simple">
274<li>Pre-allocate memory for a predefined number of keys, each with sufficient
275memory for all key types that can be stored.</li>
276<li>For multi-part operations, in an implementation with <a class="reference internal" href="../about.html#term-no-isolation"><span class="term">no isolation</span></a>, place all
277the data that needs to be carried over from one step to the next in the
278operation object. The application is then fully in control of how memory is
279allocated for the operation.</li>
280<li>In an implementation with <a class="reference internal" href="../about.html#term-isolation"><span class="term">isolation</span></a>, pre-allocate memory for a predefined
281number of operations inside the cryptoprocessor.</li>
282</ul>
283</div>
284</div>
285</div>
286
287
288 </div>
289 </div>
290 </div>
291 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
292 <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
293IHI 0086<br/>
294Non-confidential<br/>
295Version 1.1.0
296<span style="color: red; font-weight: bold;"></span>
297<ul>
298<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
299</ul>
300<ul class="current">
301<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
302<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
303<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
304<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
305<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
306<li class="toctree-l1 current"><a class="current reference internal" href="#">6. Implementation considerations</a><ul>
307<li class="toctree-l2"><a class="reference internal" href="#implementation-specific-aspects-of-the-interface">6.1. Implementation-specific aspects of the interface</a><ul>
308<li class="toctree-l3"><a class="reference internal" href="#implementation-profile">6.1.1. Implementation profile</a></li>
309<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-types">6.1.2. Implementation-specific types</a></li>
310<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-macros">6.1.3. Implementation-specific macros</a></li>
311</ul>
312</li>
313<li class="toctree-l2"><a class="reference internal" href="#porting-to-a-platform">6.2. Porting to a platform</a><ul>
314<li class="toctree-l3"><a class="reference internal" href="#platform-assumptions">6.2.1. Platform assumptions</a></li>
315<li class="toctree-l3"><a class="reference internal" href="#platform-specific-types">6.2.2. Platform-specific types</a></li>
316<li class="toctree-l3"><a class="reference internal" href="#cryptographic-hardware-support">6.2.3. Cryptographic hardware support</a></li>
317</ul>
318</li>
319<li class="toctree-l2"><a class="reference internal" href="#security-requirements-and-recommendations">6.3. Security requirements and recommendations</a><ul>
320<li class="toctree-l3"><a class="reference internal" href="#error-detection">6.3.1. Error detection</a></li>
321<li class="toctree-l3"><a class="reference internal" href="#indirect-object-references">6.3.2. Indirect object references</a></li>
322<li class="toctree-l3"><a class="reference internal" href="#memory-cleanup">6.3.3. Memory cleanup</a></li>
323<li class="toctree-l3"><a class="reference internal" href="#managing-key-material">6.3.4. Managing key material</a></li>
324<li class="toctree-l3"><a class="reference internal" href="#safe-outputs-on-error">6.3.5. Safe outputs on error</a></li>
325<li class="toctree-l3"><a class="reference internal" href="#attack-resistance">6.3.6. Attack resistance</a></li>
326</ul>
327</li>
328<li class="toctree-l2"><a class="reference internal" href="#other-implementation-considerations">6.4. Other implementation considerations</a><ul>
329<li class="toctree-l3"><a class="reference internal" href="#philosophy-of-resource-management">6.4.1. Philosophy of resource management</a></li>
330</ul>
331</li>
332</ul>
333</li>
334<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
335<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
336<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
337<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
338</ul>
339<ul>
340<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
341<li class="toctree-l1"><a class="reference internal" href="../appendix/encodings.html">Algorithm and key type encoding</a></li>
342<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
343<li class="toctree-l1"><a class="reference internal" href="../appendix/sra.html">Security Risk Assessment</a></li>
344<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
345</ul>
346<ul>
347<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
348</ul>
349<div id="searchbox" style="display: none" role="search">
350 <h3>Quick search</h3>
351 <form class="search" action="../search.html" method="get">
352 <div><input type="text" name="q" /></div>
353 <div><input type="submit" value="Go" /></div>
354 <input type="hidden" name="check_keywords" value="yes" />
355 <input type="hidden" name="area" value="default" />
356 </form>
357</div>
358<script type="text/javascript">$('#searchbox').show(0);</script>
359 </div>
360 </div>
361 <div class="clearer"></div>
362 </div>
363 <div class="footer">
364 &copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
365
366 |
367 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
368 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
369
370 </div>
371
372
373
374
375 </body>
376</html>