Update PSA API specification to 1.0.0
Generated from the PSA Crypto API Dockerfile at tag psa-crypto-api-1.0.0
diff --git a/docs/html/overview/conventions.html b/docs/html/overview/conventions.html
new file mode 100644
index 0000000..b294ef6
--- /dev/null
+++ b/docs/html/overview/conventions.html
@@ -0,0 +1,368 @@
+
+<!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>Library conventions — PSA Crypto API 1.0.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.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ 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="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Implementation considerations" href="implementation.html" />
+ <link rel="prev" title="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">
+<h1>Library conventions</h1>
+<div class="section" id="error-handling">
+<h2>Error handling</h2>
+<div class="section" id="return-status">
+<h3>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>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>Parameter conventions</h2>
+<div class="section" id="pointer-conventions">
+<h3>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 the
+<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+</div>
+<div class="section" id="input-buffer-sizes">
+<h3>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">
+<h3>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">
+<h3>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 the
+<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+</div>
+<div class="section" id="stability-of-parameters">
+<span id="id1"></span><h3>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>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/attributes.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a> and
+<a class="reference internal" href="../api/keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p>
+<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-and-algorithm-types">
+<h3>Structure of key and algorithm types</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 corresponding algorithm category:
+hash, MAC, symmetric cipher, asymmetric encryption, and so on.</li>
+<li>The following bits identify a family of algorithms 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>
+</div>
+</div>
+<div class="section" id="concurrent-calls">
+<span id="concurrency"></span><h2>Concurrent calls</h2>
+<p>In some environments, an application can make calls to the PSA crypto API in
+separate threads. In such an environment, 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>If a call destroys a key, then no other call must destroy or use that key.
+<em>Using</em>, in this context, includes all functions of multi-part operations
+which have used the key as an input in a previous function.</li>
+<li>Concurrent calls that use the same key are permitted.</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">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Library conventions</a><ul>
+<li><a class="reference internal" href="#error-handling">Error handling</a><ul>
+<li><a class="reference internal" href="#return-status">Return status</a></li>
+<li><a class="reference internal" href="#behavior-on-error">Behavior on error</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#parameter-conventions">Parameter conventions</a><ul>
+<li><a class="reference internal" href="#pointer-conventions">Pointer conventions</a></li>
+<li><a class="reference internal" href="#input-buffer-sizes">Input buffer sizes</a></li>
+<li><a class="reference internal" href="#output-buffer-sizes">Output buffer sizes</a></li>
+<li><a class="reference internal" href="#overlap-between-parameters">Overlap between parameters</a></li>
+<li><a class="reference internal" href="#stability-of-parameters">Stability of parameters</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#key-types-and-algorithms">Key types and algorithms</a><ul>
+<li><a class="reference internal" href="#structure-of-key-and-algorithm-types">Structure of key and algorithm types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#concurrent-calls">Concurrent calls</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="sample-arch.html" title="previous chapter">Sample architectures</a></li>
+ <li>Next: <a href="implementation.html" title="next chapter">Implementation considerations</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/conventions.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<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">
+ © 2019-2020, 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>
+
+ |
+ <a href="../_sources/overview/conventions.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file