TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 6c723a2f46051a3543bb7856b41761e84f5a8a15 / . / docs / html / overview / conventions.html
blob: b294ef6d2e5870fbbb13368a13cd3db3fe005f84 [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>Library conventions &#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="Implementation considerations" href="implementation.html" />
27 <link rel="prev" title="Sample architectures" href="sample-arch.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="library-conventions">
43<h1>Library conventions</h1>
44<div class="section" id="error-handling">
45<h2>Error handling</h2>
46<div class="section" id="return-status">
47<h3>Return status</h3>
48<p>Almost all functions return a status indication of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>. This
49is an enumeration of integer values, with <code class="docutils literal"><span class="pre">0</span></code> (<a class="reference internal" href="../api/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>) indicating
50successful operation and other values indicating errors. The exceptions are
51functions which only access objects that are intended to be implemented as
52simple data structures. Such functions cannot fail and either return
53<code class="docutils literal"><span class="pre">void</span></code> or a data value.</p>
54<p>Unless specified otherwise, if multiple error conditions apply, an
55implementation is free to return any of the applicable error codes. The choice
56of error code is considered an implementation quality issue. Different
57implementations can make different choices, for example to favor code size over
58ease of debugging or vice versa.</p>
59<p>If the behavior is undefined, for example, if a function receives an invalid
60pointer as a parameter, this specification makes no guarantee that the function
61will return an error. Implementations are encouraged to return an error or halt
62the application in a manner that is appropriate for the platform if the
63undefined behavior condition can be detected. However, application developers need to be aware that undefined behavior conditions cannot be detected in general.</p>
64</div>
65<div class="section" id="behavior-on-error">
66<h3>Behavior on error</h3>
67<p>All function calls must be implemented atomically:</p>
68<ul class="simple">
69<li>When a function returns a type other than <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>, the requested
70action has been carried out.</li>
71<li>When a function returns the status <a class="reference internal" href="../api/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>, the requested action has
72been carried out.</li>
73<li>When a function returns another status of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>, no action
74has been carried out. The content of the output parameters is undefined, but
75otherwise the state of the system has not changed, except as described below.</li>
76</ul>
77<p>In general, functions that modify the system state, for example, creating or
78destroying a key, must leave the system state unchanged if they return an error
79code. There are specific conditions that can result in different behavior:</p>
80<ul class="simple">
81<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> indicates that a parameter was not in a
82valid state for the requested action. This parameter might have been modified
83by the call and is now in an undefined state. The only valid action on an
84object in an undefined state is to abort it with the appropriate
85<code class="docutils literal"><span class="pre">psa_abort_xxx()</span></code> function.</li>
86<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a> indicates that a key
87derivation object has reached its maximum capacity. The key derivation
88operation might have been modified by the call. Any further attempt to obtain
89output from the key derivation operation will return
90<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a>.</li>
91<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a> indicates that the
92communication between the application and the cryptoprocessor has broken
93down. In this case, the cryptoprocessor must either finish the requested
94action successfully, or interrupt the action and roll back the system to its
95original state. Because it is often impossible to report the outcome to the
96application after a communication failure, this specification does not
97provide a way for the application to determine whether the action was
98successful.</li>
99<li>The statuses <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a>
100and <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a> might indicate data corruption in the
101system state. When a function returns one of these statuses, the system state
102might have changed from its previous state before the function call, even
103though the function call failed.</li>
104<li>Some system states cannot be rolled back, for example, the internal state of
105the random number generator or the content of access logs.</li>
106</ul>
107<p>Unless otherwise documented, the content of output parameters is not defined
108when a function returns a status other than <a class="reference internal" href="../api/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>. It is recommended
109that implementations set output parameters to safe defaults to avoid leaking
110confidential data and limit risk, in case an application does not properly
111handle all errors.</p>
112</div>
113</div>
114<div class="section" id="parameter-conventions">
115<h2>Parameter conventions</h2>
116<div class="section" id="pointer-conventions">
117<h3>Pointer conventions</h3>
118<p>Unless explicitly stated in the documentation of a function, all pointers must
119be valid pointers to an object of the specified type.</p>
120<p>A parameter is considered a <strong>buffer</strong> if it points to an array of bytes. A
121buffer parameter always has the type <code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*</span></code> or <code class="docutils literal"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*</span></code>, and
122always has an associated parameter indicating the size of the array. Note that a
123parameter of type <code class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></code> is never considered a buffer.</p>
124<p>All parameters of pointer type must be valid non-null pointers, unless the
125pointer is to a buffer of length <code class="docutils literal"><span class="pre">0</span></code> or the function’s documentation
126explicitly describes the behavior when the pointer is null. Passing a null
127pointer as a function parameter in other cases is expected to abort the caller
128on implementations where this is the normal behavior for a null pointer
129dereference.</p>
130<p>Pointers to input parameters can be in read-only memory. Output parameters must
131be in writable memory. Output parameters that are not buffers must also be
132readable, and the implementation must be able to write to a non-buffer output
133parameter and read back the same value, as explained in the
134<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
135</div>
136<div class="section" id="input-buffer-sizes">
137<h3>Input buffer sizes</h3>
138<p>For input buffers, the parameter convention is:</p>
139<dl class="docutils">
140<dt><code class="docutils literal"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
141<dd>Pointer to the first byte of the data. The pointer
142can be invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
143<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt>
144<dd>Size of the buffer in bytes.</dd>
145</dl>
146<p>The interface never uses input-output buffers.</p>
147</div>
148<div class="section" id="output-buffer-sizes">
149<h3>Output buffer sizes</h3>
150<p>For output buffers, the parameter convention is:</p>
151<dl class="docutils">
152<dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
153<dd>Pointer to the first byte of the data. The pointer can be
154invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
155<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_size</span></code></dt>
156<dd>The size of the buffer in bytes.</dd>
157<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code></dt>
158<dd>On successful return, contains the length of the
159output in bytes.</dd>
160</dl>
161<p>The content of the data buffer and of <code class="docutils literal"><span class="pre">*foo_length</span></code> on errors is unspecified,
162unless explicitly mentioned in the function description. They might be unmodified
163or set to a safe default. On successful completion, the content of the buffer
164between the offsets <code class="docutils literal"><span class="pre">*foo_length</span></code> and <code class="docutils literal"><span class="pre">foo_size</span></code> is also unspecified.</p>
165<p>Functions return <a class="reference internal" href="../api/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 buffer size is
166insufficient to carry out the requested operation. The interface defines macros
167to calculate a sufficient buffer size for each operation that has an output
168buffer. These macros return compile-time constants if their arguments are
169compile-time constants, so they are suitable for static or stack allocation.
170Refer to an individual function’s documentation for the associated output size
171macro.</p>
172<p>Some functions always return exactly as much data as the size of the output
173buffer. In this case, the parameter convention changes to:</p>
174<dl class="docutils">
175<dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
176<dd>Pointer to the first byte of the output. The pointer can be
177invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
178<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt>
179<dd>The number of bytes to return in <code class="docutils literal"><span class="pre">foo</span></code> if
180successful.</dd>
181</dl>
182</div>
183<div class="section" id="overlap-between-parameters">
184<h3>Overlap between parameters</h3>
185<p>Output parameters that are not buffers must not overlap with any input buffer or
186with any other output parameter. Otherwise, the behavior is undefined.</p>
187<p>Output buffers can overlap with input buffers. In this event, the implementation
188must return the same result as if the buffers did not overlap. The
189implementation must behave as if it had copied all the inputs into temporary
190memory, as far as the result is concerned. However, it is possible that overlap
191between parameters will affect the performance of a function call. Overlap might
192also affect memory management security if the buffer is located in memory that
193the caller shares with another security context, as described in the
194<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
195</div>
196<div class="section" id="stability-of-parameters">
197<span id="id1"></span><h3>Stability of parameters</h3>
198<p>In some environments, it is possible for the content of a parameter to change
199while a function is executing. It might also be possible for the content of an
200output parameter to be read before the function terminates. This can happen if
201the application is multithreaded. In some implementations, memory can be shared
202between security contexts, for example, between tasks in a multitasking
203operating system, between a user land task and the kernel, or between the
204Non-secure world and the Secure world of a trusted execution environment.</p>
205<p>This section describes the assumptions that an implementation can make about
206function parameters, and the guarantees that the implementation must provide
207about how it accesses parameters.</p>
208<p>Parameters that are not buffers are assumed to be under the caller’s full
209control. In a shared memory environment, this means that the parameter must be
210in memory that is exclusively accessible by the application. In a multithreaded
211environment, this means that the parameter must not be modified during the
212execution, and the value of an output parameter is undetermined until the
213function returns. The implementation can read an input parameter that is not a
214buffer multiple times and expect to read the same data. The implementation can
215write to an output parameter that is not a buffer and expect to read back the
216value that it last wrote. The implementation has the same permissions on buffers
217that overlap with a buffer in the opposite direction.</p>
218<p>In an environment with multiple threads or with shared memory, the
219implementation carefully accesses non-overlapping buffer parameters in order to
220prevent any security risk resulting from the content of the buffer being
221modified or observed during the execution of the function. In an input buffer
222that does not overlap with an output buffer, the implementation reads each byte
223of the input once, at most. The implementation does not read from an output
224buffer that does not overlap with an input buffer. Additionally, the
225implementation does not write data to a non-overlapping output buffer if this
226data is potentially confidential and the implementation has not yet verified
227that outputting this data is authorized.</p>
228<p>Unless otherwise specified, the implementation must not keep a reference to any
229parameter once a function call has returned.</p>
230</div>
231</div>
232<div class="section" id="key-types-and-algorithms">
233<h2>Key types and algorithms</h2>
234<p>Types of cryptographic keys and cryptographic algorithms are encoded separately.
235Each is encoded by using an integral type: <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a> and
236<a class="reference internal" href="../api/keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p>
237<p>There is some overlap in the information conveyed by key types and algorithms.
238Both types contain enough information, so that the meaning of an algorithm type
239value does not depend on what type of key it is used with, and vice versa.
240However, the particular instance of an algorithm might depend on the key type. For
241example, the algorithm <a class="reference internal" href="../api/ops/aead.html#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GCM</span></code></a> can be instantiated as any AEAD algorithm
242using the GCM mode over a block cipher. The underlying block cipher is
243determined by the key type.</p>
244<p>Key types do not encode the key size. For example, AES-128, AES-192 and AES-256
245share a key type <a class="reference internal" href="../api/keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>.</p>
246<div class="section" id="structure-of-key-and-algorithm-types">
247<h3>Structure of key and algorithm types</h3>
248<p>Both types use a partial bitmask structure, which allows the analysis and
249building of values from parts. However, the interface defines constants, so that
250applications do not need to depend on the encoding, and an implementation might
251only care about the encoding for code size optimization.</p>
252<p>The encodings follows a few conventions:</p>
253<ul class="simple">
254<li>The highest bit is a vendor flag. Current and future versions of this
255specification will only define values where this bit is clear.
256Implementations that wish to define additional implementation-specific values
257must use values where this bit is set, to avoid conflicts with future
258versions of this specification.</li>
259<li>The next few highest bits indicate the corresponding algorithm category:
260hash, MAC, symmetric cipher, asymmetric encryption, and so on.</li>
261<li>The following bits identify a family of algorithms in a category-dependent
262manner.</li>
263<li>In some categories and algorithm families, the lowest-order bits indicate a
264variant in a systematic way. For example, algorithm families that are
265parametrized around a hash function encode the hash in the 8 lowest bits.</li>
266</ul>
267</div>
268</div>
269<div class="section" id="concurrent-calls">
270<span id="concurrency"></span><h2>Concurrent calls</h2>
271<p>In some environments, an application can make calls to the PSA crypto API in
272separate threads. In such an environment, concurrent calls are performed
273correctly, as if the calls were executed in sequence, provided that they obey
274the following constraints:</p>
275<ul class="simple">
276<li>There is no overlap between an output parameter of one call and an input or
277output parameter of another call. Overlap between input parameters is
278permitted.</li>
279<li>If a call destroys a key, then no other call must destroy or use that key.
280<em>Using</em>, in this context, includes all functions of multi-part operations
281which have used the key as an input in a previous function.</li>
282<li>Concurrent calls that use the same key are permitted.</li>
283<li>Concurrent calls must not use the same operation object.</li>
284</ul>
285<p>If any of these constraints are violated, the behavior is undefined.</p>
286<p>If the application modifies an input parameter while a function call is in
287progress, the behavior is undefined.</p>
288<p>Individual implementations can provide additional guarantees.</p>
289</div>
290</div>
291
292
293 </div>
294 </div>
295 </div>
296 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
297 <div class="sphinxsidebarwrapper">
298 <h3><a href="../index.html">Table Of Contents</a></h3>
299 <ul>
300<li><a class="reference internal" href="#">Library conventions</a><ul>
301<li><a class="reference internal" href="#error-handling">Error handling</a><ul>
302<li><a class="reference internal" href="#return-status">Return status</a></li>
303<li><a class="reference internal" href="#behavior-on-error">Behavior on error</a></li>
304</ul>
305</li>
306<li><a class="reference internal" href="#parameter-conventions">Parameter conventions</a><ul>
307<li><a class="reference internal" href="#pointer-conventions">Pointer conventions</a></li>
308<li><a class="reference internal" href="#input-buffer-sizes">Input buffer sizes</a></li>
309<li><a class="reference internal" href="#output-buffer-sizes">Output buffer sizes</a></li>
310<li><a class="reference internal" href="#overlap-between-parameters">Overlap between parameters</a></li>
311<li><a class="reference internal" href="#stability-of-parameters">Stability of parameters</a></li>
312</ul>
313</li>
314<li><a class="reference internal" href="#key-types-and-algorithms">Key types and algorithms</a><ul>
315<li><a class="reference internal" href="#structure-of-key-and-algorithm-types">Structure of key and algorithm types</a></li>
316</ul>
317</li>
318<li><a class="reference internal" href="#concurrent-calls">Concurrent calls</a></li>
319</ul>
320</li>
321</ul>
322<div class="relations">
323<h3>Related Topics</h3>
324<ul>
325 <li><a href="../index.html">Documentation overview</a><ul>
326 <li>Previous: <a href="sample-arch.html" title="previous chapter">Sample architectures</a></li>
327 <li>Next: <a href="implementation.html" title="next chapter">Implementation considerations</a></li>
328 </ul></li>
329</ul>
330</div>
331 <div role="note" aria-label="source link">
332 <h3>This Page</h3>
333 <ul class="this-page-menu">
334 <li><a href="../_sources/overview/conventions.rst.txt"
335 rel="nofollow">Show Source</a></li>
336 </ul>
337 </div>
338<div id="searchbox" style="display: none" role="search">
339 <h3>Quick search</h3>
340 <form class="search" action="../search.html" method="get">
341 <div><input type="text" name="q" /></div>
342 <div><input type="submit" value="Go" /></div>
343 <input type="hidden" name="check_keywords" value="yes" />
344 <input type="hidden" name="area" value="default" />
345 </form>
346</div>
347<script type="text/javascript">$('#searchbox').show(0);</script>
348 </div>
349 </div>
350 <div class="clearer"></div>
351 </div>
352 <div class="footer">
353 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
354
355 |
356 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
357 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
358
359 |
360 <a href="../_sources/overview/conventions.rst.txt"
361 rel="nofollow">Page source</a>
362 </div>
363
364
365
366
367 </body>
368</html>