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