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