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