| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>5. Library conventions — PSA Crypto API 1.1.0 documentation</title> |
| <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" /> |
| <link rel="stylesheet" href="../_static/pygments.css" type="text/css" /> |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: '../', |
| VERSION: '1.1.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: false, |
| SOURCELINK_SUFFIX: '.txt' |
| }; |
| </script> |
| <script type="text/javascript" src="../_static/jquery.js"></script> |
| <script type="text/javascript" src="../_static/underscore.js"></script> |
| <script type="text/javascript" src="../_static/doctools.js"></script> |
| <link rel="author" title="About these documents" href="../about.html" /> |
| <link rel="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="6. Implementation considerations" href="implementation.html" /> |
| <link rel="prev" title="4. Sample architectures" href="sample-arch.html" /> |
| |
| <link rel="stylesheet" href="../_static/custom.css" type="text/css" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> |
| |
| </head> |
| <body> |
| |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="library-conventions"> |
| <span id="id1"></span><h1>5. Library conventions</h1> |
| <div class="section" id="header-files"> |
| <h2>5.1. Header files</h2> |
| <p>The header file for the PSA Cryptography API has the name <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code>. All of the API elements that are provided by an implementation must be visible to an application program that includes this header file.</p> |
| <div class="highlight-none"><div class="highlight"><pre><span></span>#include "psa/crypto.h" |
| </pre></div> |
| </div> |
| <p>Implementations must provide their own version of the <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code> header file. Implementations can provide a subset of the API defined in this specification and a subset of the available algorithms. <a class="reference internal" href="../appendix/example_header.html#appendix-example-header"><span class="secref">Example header file</span></a> provides an incomplete, example header file which includes all of the API elements. See also <a class="reference internal" href="implementation.html#implementation-considerations"><span class="secref">Implementation considerations</span></a>.</p> |
| <p>This API uses some of the common status codes that are defined by <span><em>Arm® Platform Security Architecture Firmware Framework</em> <a class="reference internal" href="../about.html#citation-ff-m"><span class="cite">[FF-M]</span></a></span> as part of the <code class="file docutils literal"><span class="pre">psa/error.h</span></code> header file. Applications are not required to explicitly include the <code class="file docutils literal"><span class="pre">psa/error.h</span></code> header file when using these status codes with the PSA Crypto API. See <a class="reference internal" href="../api/library/status.html#status-codes"><span class="secref">PSA status codes</span></a>.</p> |
| </div> |
| <div class="section" id="api-conventions"> |
| <span id="id2"></span><h2>5.2. API conventions</h2> |
| <p>The interface in this specification is defined in terms of C macros, data types, and functions.</p> |
| <div class="section" id="identifier-names"> |
| <h3>5.2.1. Identifier names</h3> |
| <p>All of the identifiers defined in this API begin with the prefix <code class="docutils literal"><span class="pre">psa_</span></code>, for types and functions, or <code class="docutils literal"><span class="pre">PSA_</span></code> for macros.</p> |
| <p>Future versions of this specification will use the same prefix for additional API elements. It is recommended that applications and implementations do not use this prefix for their own identifiers, to avoid a potential conflict with a future version of the PSA Crypto API.</p> |
| </div> |
| <div class="section" id="basic-types"> |
| <h3>5.2.2. Basic types</h3> |
| <p>This specification makes use of standard C data types, including the fixed-width integer types from the ISO C99 specification update <a class="reference internal" href="../about.html#citation-c99"><span class="cite">[C99]</span></a>. The following standard C types are used:</p> |
| <table border="1" class="colwidths-auto docutils align-left"> |
| <tbody valign="top"> |
| <tr class="row-odd"><td><code class="docutils literal"><span class="pre">int32_t</span></code></td> |
| <td>a 32-bit signed integer</td> |
| </tr> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">uint8_t</span></code></td> |
| <td>an 8-bit unsigned integer</td> |
| </tr> |
| <tr class="row-odd"><td><code class="docutils literal"><span class="pre">uint16_t</span></code></td> |
| <td>a 16-bit unsigned integer</td> |
| </tr> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">uint32_t</span></code></td> |
| <td>a 32-bit unsigned integer</td> |
| </tr> |
| <tr class="row-odd"><td><code class="docutils literal"><span class="pre">uint64_t</span></code></td> |
| <td>a 64-bit unsigned integer</td> |
| </tr> |
| <tr class="row-even"><td><code class="docutils literal"><span class="pre">size_t</span></code></td> |
| <td>an unsigned integer large enough to hold the size of an object in memory</td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| <div class="section" id="data-types"> |
| <h3>5.2.3. Data types</h3> |
| <p>Integral types are defined for specific API elements to provide clarity in the interface definition, and to improve code readability. For example, <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"><span class="pre">psa_algorithm_t</span></code></a> and <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>.</p> |
| <p>Structure types are declared using <code class="docutils literal"><span class="pre">typedef</span></code> instead of a <code class="docutils literal"><span class="pre">struct</span></code> tag, also to improve code readability.</p> |
| <p>Fully-defined types must be declared exactly as defined in this specification. Types that are not fully defined in this specification must be defined by an implementation. See <a class="reference internal" href="implementation.html#implementation-defined-type"><span class="secref">Implementation-specific types</span></a>.</p> |
| </div> |
| <div class="section" id="constants"> |
| <h3>5.2.4. Constants</h3> |
| <p>Constant values are defined using C macros. Constants defined in this specification have names that are all upper-case.</p> |
| <p>A constant macro evaluates to a compile-time constant expression.</p> |
| </div> |
| <div class="section" id="function-like-macros"> |
| <h3>5.2.5. Function-like macros</h3> |
| <p>Function-like macros are C macros that take parameters, providing supporting functionality in the API. Function-like macros defined in this specification have names that are all upper-case.</p> |
| <p>Function-like macros are permitted to evaluate each argument multiple times or zero times. Providing arguments that have side effects will result in <a class="reference internal" href="../about.html#term-implementation-defined"><span class="scterm">IMPLEMENTATION DEFINED</span></a> behavior, and is non-portable.</p> |
| <p>If all of the arguments to a function-like macro are compile-time constant expressions, the then result evaluates to a compile-time constant expression.</p> |
| <p>If an argument to a function-like macro has an invalid value (for example, a value outside the domain of the function-like macro), then the result is <a class="reference internal" href="../about.html#term-implementation-defined"><span class="scterm">IMPLEMENTATION DEFINED</span></a>.</p> |
| </div> |
| <div class="section" id="functions"> |
| <h3>5.2.6. Functions</h3> |
| <p>Functions defined in this specification have names that are all lower-case.</p> |
| <p>An implementation is permitted to declare any API function with <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> linkage, instead of the default <code class="docutils literal"><span class="pre">extern</span></code> linkage.</p> |
| <p>An implementation is permitted to also define a function-like macro with the same name as a function in this specification. If an implementation defines a function-like macro for a function from this specification, then:</p> |
| <ul class="simple"> |
| <li>The implementation must also provide a definition of the function. This enables an application to take the address of a function defined in this specification.</li> |
| <li>The function-like macro must expand to code that evaluates each of its arguments exactly once, as if the call was made to a C function. This enables an application to safely use arbitrary expressions as arguments to a function defined in this specification.</li> |
| </ul> |
| <p>If a non-pointer argument to a function has an invalid value (for example, a value outside the domain of the function), then the function will normally return an error, as specified in the function definition. See also <a class="reference internal" href="#error-handling"><span class="secref">Error handling</span></a>.</p> |
| <p>If a pointer argument to a function has an invalid value (for example, a pointer outside the address space of the program, or a null pointer), the result is <a class="reference internal" href="../about.html#term-implementation-defined"><span class="scterm">IMPLEMENTATION DEFINED</span></a>. See also <a class="reference internal" href="#pointer-conventions"><span class="secref">Pointer conventions</span></a>.</p> |
| </div> |
| </div> |
| <div class="section" id="error-handling"> |
| <span id="id3"></span><h2>5.3. Error handling</h2> |
| <div class="section" id="return-status"> |
| <h3>5.3.1. Return status</h3> |
| <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 |
| is 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 |
| successful operation and other values indicating errors. The exceptions are |
| functions which only access objects that are intended to be implemented as |
| simple data structures. Such functions cannot fail and either return |
| <code class="docutils literal"><span class="pre">void</span></code> or a data value.</p> |
| <p>Unless specified otherwise, if multiple error conditions apply, an |
| implementation is free to return any of the applicable error codes. The choice |
| of error code is considered an implementation quality issue. Different |
| implementations can make different choices, for example to favor code size over |
| ease of debugging or vice versa.</p> |
| <p>If the behavior is undefined, for example, if a function receives an invalid |
| pointer as a parameter, this specification makes no guarantee that the function |
| will return an error. Implementations are encouraged to return an error or halt |
| the application in a manner that is appropriate for the platform if the |
| undefined behavior condition can be detected. However, application developers need to be aware that undefined behavior conditions cannot be detected in general.</p> |
| </div> |
| <div class="section" id="behavior-on-error"> |
| <h3>5.3.2. Behavior on error</h3> |
| <p>All function calls must be implemented atomically:</p> |
| <ul class="simple"> |
| <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 |
| action has been carried out.</li> |
| <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 |
| been carried out.</li> |
| <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 |
| has been carried out. The content of the output parameters is undefined, but |
| otherwise the state of the system has not changed, except as described below.</li> |
| </ul> |
| <p>In general, functions that modify the system state, for example, creating or |
| destroying a key, must leave the system state unchanged if they return an error |
| code. There are specific conditions that can result in different behavior:</p> |
| <ul class="simple"> |
| <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 |
| valid state for the requested action. This parameter might have been modified |
| by the call and is now in an undefined state. The only valid action on an |
| object in an undefined state is to abort it with the appropriate |
| <code class="docutils literal"><span class="pre">psa_abort_xxx()</span></code> function.</li> |
| <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 |
| derivation object has reached its maximum capacity. The key derivation |
| operation might have been modified by the call. Any further attempt to obtain |
| output from the key derivation operation will return |
| <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> |
| <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 |
| communication between the application and the cryptoprocessor has broken |
| down. In this case, the cryptoprocessor must either finish the requested |
| action successfully, or interrupt the action and roll back the system to its |
| original state. Because it is often impossible to report the outcome to the |
| application after a communication failure, this specification does not |
| provide a way for the application to determine whether the action was |
| successful.</li> |
| <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> |
| and <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 |
| system state. When a function returns one of these statuses, the system state |
| might have changed from its previous state before the function call, even |
| though the function call failed.</li> |
| <li>Some system states cannot be rolled back, for example, the internal state of |
| the random number generator or the content of access logs.</li> |
| </ul> |
| <p>Unless otherwise documented, the content of output parameters is not defined |
| when 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 |
| that implementations set output parameters to safe defaults to avoid leaking |
| confidential data and limit risk, in case an application does not properly |
| handle all errors.</p> |
| </div> |
| </div> |
| <div class="section" id="parameter-conventions"> |
| <h2>5.4. Parameter conventions</h2> |
| <div class="section" id="pointer-conventions"> |
| <span id="id4"></span><h3>5.4.1. Pointer conventions</h3> |
| <p>Unless explicitly stated in the documentation of a function, all pointers must |
| be valid pointers to an object of the specified type.</p> |
| <p>A parameter is considered a <strong>buffer</strong> if it points to an array of bytes. A |
| buffer 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 |
| always has an associated parameter indicating the size of the array. Note that a |
| parameter of type <code class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></code> is never considered a buffer.</p> |
| <p>All parameters of pointer type must be valid non-null pointers, unless the |
| pointer is to a buffer of length <code class="docutils literal"><span class="pre">0</span></code> or the function’s documentation |
| explicitly describes the behavior when the pointer is null. Passing a null |
| pointer as a function parameter in other cases is expected to abort the caller |
| on implementations where this is the normal behavior for a null pointer |
| dereference.</p> |
| <p>Pointers to input parameters can be in read-only memory. Output parameters must |
| be in writable memory. Output parameters that are not buffers must also be |
| readable, and the implementation must be able to write to a non-buffer output |
| parameter and read back the same value, as explained in |
| <a class="reference internal" href="#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</p> |
| </div> |
| <div class="section" id="input-buffer-sizes"> |
| <h3>5.4.2. Input buffer sizes</h3> |
| <p>For input buffers, the parameter convention is:</p> |
| <dl class="docutils"> |
| <dt><code class="docutils literal"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt> |
| <dd>Pointer to the first byte of the data. The pointer |
| can be invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd> |
| <dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt> |
| <dd>Size of the buffer in bytes.</dd> |
| </dl> |
| <p>The interface never uses input-output buffers.</p> |
| </div> |
| <div class="section" id="output-buffer-sizes"> |
| <span id="output-buffers"></span><h3>5.4.3. Output buffer sizes</h3> |
| <p>For output buffers, the parameter convention is:</p> |
| <dl class="docutils"> |
| <dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt> |
| <dd>Pointer to the first byte of the data. The pointer can be |
| invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd> |
| <dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_size</span></code></dt> |
| <dd>The size of the buffer in bytes.</dd> |
| <dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code></dt> |
| <dd>On successful return, contains the length of the |
| output in bytes.</dd> |
| </dl> |
| <p>The content of the data buffer and of <code class="docutils literal"><span class="pre">*foo_length</span></code> on errors is unspecified, |
| unless explicitly mentioned in the function description. They might be unmodified |
| or set to a safe default. On successful completion, the content of the buffer |
| between 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> |
| <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 |
| insufficient to carry out the requested operation. The interface defines macros |
| to calculate a sufficient buffer size for each operation that has an output |
| buffer. These macros return compile-time constants if their arguments are |
| compile-time constants, so they are suitable for static or stack allocation. |
| Refer to an individual function’s documentation for the associated output size |
| macro.</p> |
| <p>Some functions always return exactly as much data as the size of the output |
| buffer. In this case, the parameter convention changes to:</p> |
| <dl class="docutils"> |
| <dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt> |
| <dd>Pointer to the first byte of the output. The pointer can be |
| invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd> |
| <dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt> |
| <dd>The number of bytes to return in <code class="docutils literal"><span class="pre">foo</span></code> if |
| successful.</dd> |
| </dl> |
| </div> |
| <div class="section" id="overlap-between-parameters"> |
| <span id="buffer-overlap"></span><h3>5.4.4. Overlap between parameters</h3> |
| <p>Output parameters that are not buffers must not overlap with any input buffer or |
| with any other output parameter. Otherwise, the behavior is undefined.</p> |
| <p>Output buffers can overlap with input buffers. In this event, the implementation |
| must return the same result as if the buffers did not overlap. The |
| implementation must behave as if it had copied all the inputs into temporary |
| memory, as far as the result is concerned. However, it is possible that overlap |
| between parameters will affect the performance of a function call. Overlap might |
| also affect memory management security if the buffer is located in memory that |
| the caller shares with another security context, as described in |
| <a class="reference internal" href="#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</p> |
| </div> |
| <div class="section" id="stability-of-parameters"> |
| <span id="id5"></span><h3>5.4.5. Stability of parameters</h3> |
| <p>In some environments, it is possible for the content of a parameter to change |
| while a function is executing. It might also be possible for the content of an |
| output parameter to be read before the function terminates. This can happen if |
| the application is multithreaded. In some implementations, memory can be shared |
| between security contexts, for example, between tasks in a multitasking |
| operating system, between a user land task and the kernel, or between the |
| Non-secure world and the Secure world of a trusted execution environment.</p> |
| <p>This section describes the assumptions that an implementation can make about |
| function parameters, and the guarantees that the implementation must provide |
| about how it accesses parameters.</p> |
| <p>Parameters that are not buffers are assumed to be under the caller’s full |
| control. In a shared memory environment, this means that the parameter must be |
| in memory that is exclusively accessible by the application. In a multithreaded |
| environment, this means that the parameter must not be modified during the |
| execution, and the value of an output parameter is undetermined until the |
| function returns. The implementation can read an input parameter that is not a |
| buffer multiple times and expect to read the same data. The implementation can |
| write to an output parameter that is not a buffer and expect to read back the |
| value that it last wrote. The implementation has the same permissions on buffers |
| that overlap with a buffer in the opposite direction.</p> |
| <p>In an environment with multiple threads or with shared memory, the |
| implementation carefully accesses non-overlapping buffer parameters in order to |
| prevent any security risk resulting from the content of the buffer being |
| modified or observed during the execution of the function. In an input buffer |
| that does not overlap with an output buffer, the implementation reads each byte |
| of the input once, at most. The implementation does not read from an output |
| buffer that does not overlap with an input buffer. Additionally, the |
| implementation does not write data to a non-overlapping output buffer if this |
| data is potentially confidential and the implementation has not yet verified |
| that outputting this data is authorized.</p> |
| <p>Unless otherwise specified, the implementation must not keep a reference to any |
| parameter once a function call has returned.</p> |
| </div> |
| </div> |
| <div class="section" id="key-types-and-algorithms"> |
| <h2>5.5. Key types and algorithms</h2> |
| <p>Types of cryptographic keys and cryptographic algorithms are encoded separately. |
| Each 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"><span class="pre">psa_key_type_t</span></code></a> and |
| <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"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p> |
| <p>There is some overlap in the information conveyed by key types and algorithms. |
| Both types contain enough information, so that the meaning of an algorithm type |
| value does not depend on what type of key it is used with, and vice versa. |
| However, the particular instance of an algorithm might depend on the key type. For |
| example, 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 |
| using the GCM mode over a block cipher. The underlying block cipher is |
| determined by the key type.</p> |
| <p>Key types do not encode the key size. For example, AES-128, AES-192 and AES-256 |
| share 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> |
| <div class="section" id="structure-of-key-types-and-algorithms"> |
| <h3>5.5.1. Structure of key types and algorithms</h3> |
| <p>Both types use a partial bitmask structure, which allows the analysis and |
| building of values from parts. However, the interface defines constants, so that |
| applications do not need to depend on the encoding, and an implementation might |
| only care about the encoding for code size optimization.</p> |
| <p>The encodings follows a few conventions:</p> |
| <ul class="simple"> |
| <li>The highest bit is a vendor flag. Current and future versions of this |
| specification will only define values where this bit is clear. |
| Implementations that wish to define additional implementation-specific values |
| must use values where this bit is set, to avoid conflicts with future |
| versions of this specification.</li> |
| <li>The next few highest bits indicate the algorithm or key category: |
| hash, MAC, symmetric cipher, asymmetric encryption, and so on.</li> |
| <li>The following bits identify a family of algorithms or keys in a category-dependent |
| manner.</li> |
| <li>In some categories and algorithm families, the lowest-order bits indicate a |
| variant in a systematic way. For example, algorithm families that are |
| parametrized around a hash function encode the hash in the 8 lowest bits.</li> |
| </ul> |
| <p>The <a class="reference internal" href="../appendix/encodings.html#appendix-encodings"><span class="secref">Algorithm and key type encoding</span></a> appendix provides a full definition of the encoding of key types and algorithm identifiers.</p> |
| </div> |
| </div> |
| <div class="section" id="concurrent-calls"> |
| <span id="concurrency"></span><h2>5.6. Concurrent calls</h2> |
| <p>In some environments, an application can make calls to the PSA crypto API in |
| separate threads. In such an environment, <em>concurrent calls</em> are two or more |
| calls to the API whose execution can overlap in time.</p> |
| <p>Concurrent calls are performed correctly, as if the calls were executed in |
| sequence, provided that they obey the following constraints:</p> |
| <ul class="simple"> |
| <li>There is no overlap between an output parameter of one call and an input or |
| output parameter of another call. Overlap between input parameters is |
| permitted.</li> |
| <li>A call to destroy a key must not overlap with a concurrent call to any of |
| the following functions:<ul> |
| <li>Any call where the same key identifier is a parameter to the call.</li> |
| <li>Any call in a multi-part operation, where the same key identifier was |
| used as a parameter to a previous step in the multi-part operation.</li> |
| </ul> |
| </li> |
| <li>Concurrent calls must not use the same operation object.</li> |
| </ul> |
| <p>If any of these constraints are violated, the behavior is undefined.</p> |
| <p>If the application modifies an input parameter while a function call is in |
| progress, the behavior is undefined.</p> |
| <p>Individual implementations can provide additional guarantees.</p> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3> |
| IHI 0086<br/> |
| Non-confidential<br/> |
| Version 1.1.0 |
| <span style="color: red; font-weight: bold;"></span> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li> |
| </ul> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li> |
| <li class="toctree-l1 current"><a class="current reference internal" href="#">5. Library conventions</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#header-files">5.1. Header files</a></li> |
| <li class="toctree-l2"><a class="reference internal" href="#api-conventions">5.2. API conventions</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#identifier-names">5.2.1. Identifier names</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#basic-types">5.2.2. Basic types</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#data-types">5.2.3. Data types</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#constants">5.2.4. Constants</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#function-like-macros">5.2.5. Function-like macros</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#functions">5.2.6. Functions</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#error-handling">5.3. Error handling</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#return-status">5.3.1. Return status</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#behavior-on-error">5.3.2. Behavior on error</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#parameter-conventions">5.4. Parameter conventions</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#pointer-conventions">5.4.1. Pointer conventions</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#input-buffer-sizes">5.4.2. Input buffer sizes</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#output-buffer-sizes">5.4.3. Output buffer sizes</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#overlap-between-parameters">5.4.4. Overlap between parameters</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#stability-of-parameters">5.4.5. Stability of parameters</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#key-types-and-algorithms">5.5. Key types and algorithms</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#structure-of-key-types-and-algorithms">5.5.1. Structure of key types and algorithms</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#concurrent-calls">5.6. Concurrent calls</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../appendix/encodings.html">Algorithm and key type encoding</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../appendix/sra.html">Security Risk Assessment</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li> |
| </ul> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <form class="search" action="../search.html" method="get"> |
| <div><input type="text" name="q" /></div> |
| <div><input type="submit" value="Go" /></div> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| © 2018-2022, Arm Limited or its affiliates. All rights reserved. |
| |
| | |
| Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a> |
| & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a> |
| |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |