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/implementation.html b/docs/html/overview/implementation.html
new file mode 100644
index 0000000..53eb1a9
--- /dev/null
+++ b/docs/html/overview/implementation.html
@@ -0,0 +1,367 @@
+
+<!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>Implementation considerations — 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="Usage considerations" href="usage.html" />
+ <link rel="prev" title="Library conventions" href="conventions.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="implementation-considerations">
+<span id="id1"></span><h1>Implementation considerations</h1>
+<div class="section" id="implementation-specific-aspects-of-the-interface">
+<h2>Implementation-specific aspects of the interface</h2>
+<div class="section" id="implementation-profile">
+<h3>Implementation profile</h3>
+<p>Implementations can implement a subset of the API and a subset of the available
+algorithms. The implemented subset is known as the implementation’s profile. The
+documentation for each implementation must describe the profile that it
+implements. This specification’s companion documents also define a number of
+standard profiles.</p>
+</div>
+<div class="section" id="implementation-specific-types">
+<span id="implementation-defined-type"></span><h3>Implementation-specific types</h3>
+<p>This specification defines a number of implementation-specific types, which
+represent objects whose content depends on the implementation. These are defined
+as C <code class="docutils literal"><span class="pre">typedef</span></code> types in this specification, with a comment
+<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
+definition. For some types the specification constrains the type, for example,
+by requiring that the type is a <code class="docutils literal"><span class="pre">struct</span></code>, or that it is convertible to and
+from an unsigned integer. In the implementation’s version of <strong>psa/crypto.h</strong>,
+these types need to be defined as complete C types so that objects of these
+types can be instantiated by application code.</p>
+<p>Applications that rely on the implementation specific definition of any of these
+types might not be portable to other implementations of this specification.</p>
+</div>
+<div class="section" id="implementation-specific-macros">
+<span id="implementation-specific-macro"></span><h3>Implementation-specific macros</h3>
+<p>Some macro constants and function-like macros are precisely defined by this
+specification. The use of an exact definition is essential if the definition can
+appear in more than one header file within a compilation.</p>
+<p>Other macros that are defined by this specification have a macro body that is
+implementation-specific. The description of an implementation-specific macro can
+optionally specify each of the following requirements:</p>
+<ul class="simple">
+<li>Input domains: the macro must be valid for arguments within the input domain.</li>
+<li>A return type: the macro result must be compatible with this type.</li>
+<li>Output range: the macro result must lie in the output range.</li>
+<li>Computed value: A precise mapping of valid input to output values.</li>
+</ul>
+<p>Each implementation-specific macro is in one of following categories:</p>
+<p id="specification-defined-value"><em>Specification-defined value</em></p>
+<blockquote>
+<div><p>The result type and computed value of the macro expression is defined by
+this specification, but the definition of the macro body is provided by the
+implementation.</p>
+<p>These macros are indicated in this specification using the comment
+<em><a class="reference internal" href="#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>.</p>
+<p>For function-like macros with specification-defined values:</p>
+<ul class="simple">
+<li>Example implementations are provided in an appendix to this specification.
+See <em><a class="reference internal" href="../appendix/specdef_values.html#appendix-specdef-values"><span class="std std-ref">Example macro implementations</span></a></em>.</li>
+<li>The expected computation for valid and supported input arguments will be
+defined as pseudo-code in a future version of this specification.</li>
+</ul>
+</div></blockquote>
+<p id="implementation-defined-value"><em>Implementation-defined value</em></p>
+<blockquote>
+<div><p>The value of the macro expression is implementation-defined.</p>
+<p>For some macros, the computed value is derived from the specification of one
+or more cryptographic algorithms. In these cases, the result must exactly
+match the value in those external specifications.</p>
+<p>These macros are indicated in this specification using the comment
+<em><a class="reference internal" href="#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>.</p>
+</div></blockquote>
+<p>Some of these macros compute a result based on an algorithm or key type.
+If an implementation defines vendor-specific algorithms or
+key types, then it must provide an implementation for such macros that takes all
+relevant algorithms and types into account. Conversely, an implementation that
+does not support a certain algorithm or key type can define such macros in a
+simpler way that does not take unsupported argument values into account.</p>
+<p>Some macros define the minimum sufficient output buffer size for certain
+functions. In some cases, an implementation is allowed to require a buffer size
+that is larger than the theoretical minimum. An implementation must define
+minimum-size macros in such a way that it guarantees that the buffer of the
+resulting size is sufficient for the output of the corresponding function. Refer
+to each macro’s documentation for the applicable requirements.</p>
+</div>
+</div>
+<div class="section" id="porting-to-a-platform">
+<h2>Porting to a platform</h2>
+<div class="section" id="platform-assumptions">
+<h3>Platform assumptions</h3>
+<p>This specification is designed for a C99 platform. The interface is defined in
+terms of C macros, functions and objects.</p>
+<p>The specification assumes 8-bit bytes, and “byte” and “octet” are used
+synonymously.</p>
+</div>
+<div class="section" id="platform-specific-types">
+<h3>Platform-specific types</h3>
+<p>The specification makes use of some types defined in C99. These types must be
+defined in the implementation version of <strong>psa/crypto.h</strong> or by a header
+included in this file. The following C99 types are used:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">uint8_t</span></code>, <code class="docutils literal"><span class="pre">uint16_t</span></code>, <code class="docutils literal"><span class="pre">uint32_t</span></code></dt>
+<dd>Unsigned integer types with 8, 16 and 32 value bits respectively.
+These types are defined by the C99 header <strong>stdint.h</strong>.</dd>
+</dl>
+</div>
+<div class="section" id="cryptographic-hardware-support">
+<h3>Cryptographic hardware support</h3>
+<p>Implementations are encouraged to make use of hardware accelerators where
+available. A future version of this specification will define a function
+interface that calls drivers for hardware accelerators and external
+cryptographic hardware.</p>
+</div>
+</div>
+<div class="section" id="security-requirements-and-recommendations">
+<h2>Security requirements and recommendations</h2>
+<div class="section" id="error-detection">
+<h3>Error detection</h3>
+<p>Implementations that provide isolation between the caller and the cryptography
+processing environment must validate parameters to ensure that the cryptography
+processing environment is protected from attacks caused by passing invalid
+parameters.</p>
+<p>Even implementations that do not provide isolation are recommended to detect bad
+parameters and fail-safe where possible.</p>
+</div>
+<div class="section" id="indirect-object-references">
+<h3>Indirect object references</h3>
+<p>Implementations can use different strategies for allocating key identifiers,
+and other types of indirect object reference.</p>
+<p>Implementations that provide isolation between the caller and the cryptography
+processing environment must consider the threats relating to abuse and misuse
+of key identifiers and other indirect resource references. For example,
+multi-part operations can be implemented as backend state to which the client
+only maintains an indirect reference in the application’s multi-part operation
+object.</p>
+<p>An implementation that supports multiple callers must implement strict isolation
+of API resources between different callers. For example, a client must not be
+able to obtain a reference to another client’s key by guessing the key
+identifier value. Isolation of key identifiers can be achieved in several ways.
+For example:</p>
+<ul class="simple">
+<li>There is a single identifier namespace for all clients, and the
+implementation verifies that the client is the owner of the identifier when
+looking up the key.</li>
+<li>Each client has an independent identifier namespace, and the implementation
+uses a client specific identifier-to-key mapping when looking up the key.</li>
+</ul>
+<p>After a volatile key identifier is destroyed, it is recommended that the
+implementation does not immediately reuse the same identifier value for a
+different key. This reduces the risk of an attack that is able to exploit a key
+identifier reuse vulnerability within an application.</p>
+</div>
+<div class="section" id="memory-cleanup">
+<span id="id2"></span><h3>Memory cleanup</h3>
+<p>Implementations must wipe all sensitive data from memory when it is no longer
+used. It is recommended that they wipe this sensitive data as soon as possible. All
+temporary data used during the execution of a function, such as stack buffers,
+must be wiped before the function returns. All data associated with an object,
+such as a multi-part operation, must be wiped, at the latest, when the object
+becomes inactive, for example, when a multi-part operation is aborted.</p>
+<p>The rationale for this non-functional requirement is to minimize impact if the
+system is compromised. If sensitive data is wiped immediately after use, only
+data that is currently in use can be leaked. It does not compromise past data.</p>
+</div>
+<div class="section" id="managing-key-material">
+<span id="key-material"></span><h3>Managing key material</h3>
+<p>In implementations that have limited volatile memory for keys, the
+implementation is permitted to store a <a class="reference internal" href="functionality.html#volatile-keys"><span class="std std-ref">volatile key</span></a> to a
+temporary location in non-volatile memory. The implementation must delete any
+such copies when the key is destroyed, and it is recommended that these copies
+are deleted as soon as the key is reloaded into volatile memory. An
+implementation that uses this method must clear any stored volatile key material
+on startup.</p>
+<p>Implementing the <a class="reference internal" href="#memory-cleanup"><span class="std std-ref">memory cleanup rule</span></a> for persistent keys
+can result in inefficiencies when the same persistent key is used sequentially
+in multiple cryptographic operations. The inefficiency stems from loading the
+key from non-volatile storage on each use of the key. The <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a>
+policy allows an application to request that the implementation does not cleanup
+non-essential copies of persistent key material, effectively suspending the
+cleanup rules for that key. The effects of this policy depend on the
+implementation and the key, for example:</p>
+<ul class="simple">
+<li>For volatile keys or keys in a secure element with no open/close mechanism,
+this is likely to have no effect.</li>
+<li>For persistent keys that are not in a secure element, this allows the
+implementation to keep the key in a memory cache outside of the memory used
+by ongoing operations.</li>
+<li>For keys in a secure element with an open/close mechanism, this is a hint to
+keep the key open in the secure element.</li>
+</ul>
+<p>The application can indicate when it has finished using the key by calling
+<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"><span class="pre">psa_purge_key()</span></code></a>, to request that the key material is cleaned from memory.</p>
+</div>
+<div class="section" id="safe-outputs-on-error">
+<h3>Safe outputs on error</h3>
+<p>Implementations must ensure that confidential data is not written to output
+parameters before validating that the disclosure of this confidential data is
+authorized. This requirement is particularly important for implementations where
+the caller can share memory with another security context, as described in the
+<a class="reference internal" href="conventions.html#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a> section.</p>
+<p>In most cases, the specification does not define the content of output
+parameters when an error occurs. It is recommended that implementations try to
+ensure that the content of output parameters is as safe as possible, in case an
+application flaw or a data leak causes it to be used. In particular, Arm
+recommends that implementations avoid placing partial output in output buffers
+when an action is interrupted. The meaning of “safe as possible” depends on the
+implementation, as different environments require different compromises between
+implementation complexity, overall robustness and performance. Some common
+strategies are to leave output parameters unchanged, in case of errors, or
+zeroing them out.</p>
+</div>
+<div class="section" id="attack-resistance">
+<h3>Attack resistance</h3>
+<p>Cryptographic code tends to manipulate high-value secrets, from which other
+secrets can be unlocked. As such, it is a high-value target for attacks. There
+is a vast body of literature on attack types, such as side channel attacks and
+glitch attacks. Typical side channels include timing, cache access patterns,
+branch-prediction access patterns, power consumption, radio emissions and more.</p>
+<p>This specification does not specify particular requirements for attack
+resistance. Implementers are encouraged to consider the attack resistance
+desired in each use case and design their implementation accordingly. Security
+standards for attack resistance for particular targets might be applicable in
+certain use cases.</p>
+</div>
+</div>
+<div class="section" id="other-implementation-considerations">
+<h2>Other implementation considerations</h2>
+<div class="section" id="philosophy-of-resource-management">
+<h3>Philosophy of resource management</h3>
+<p>The specification allows most functions to return
+<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"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a>. This gives implementations the freedom to
+manage memory as they please.</p>
+<p>Alternatively, the interface is also designed for conservative strategies of
+memory management. An implementation can avoid dynamic memory allocation
+altogether by obeying certain restrictions:</p>
+<ul class="simple">
+<li>Pre-allocate memory for a predefined number of keys, each with sufficient
+memory for all key types that can be stored.</li>
+<li>For multi-part operations, in an implementation without isolation, place all
+the data that needs to be carried over from one step to the next in the
+operation object. The application is then fully in control of how memory is
+allocated for the operation.</li>
+<li>In an implementation with isolation, pre-allocate memory for a predefined
+number of operations inside the cryptoprocessor.</li>
+</ul>
+</div>
+</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="#">Implementation considerations</a><ul>
+<li><a class="reference internal" href="#implementation-specific-aspects-of-the-interface">Implementation-specific aspects of the interface</a><ul>
+<li><a class="reference internal" href="#implementation-profile">Implementation profile</a></li>
+<li><a class="reference internal" href="#implementation-specific-types">Implementation-specific types</a></li>
+<li><a class="reference internal" href="#implementation-specific-macros">Implementation-specific macros</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#porting-to-a-platform">Porting to a platform</a><ul>
+<li><a class="reference internal" href="#platform-assumptions">Platform assumptions</a></li>
+<li><a class="reference internal" href="#platform-specific-types">Platform-specific types</a></li>
+<li><a class="reference internal" href="#cryptographic-hardware-support">Cryptographic hardware support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#security-requirements-and-recommendations">Security requirements and recommendations</a><ul>
+<li><a class="reference internal" href="#error-detection">Error detection</a></li>
+<li><a class="reference internal" href="#indirect-object-references">Indirect object references</a></li>
+<li><a class="reference internal" href="#memory-cleanup">Memory cleanup</a></li>
+<li><a class="reference internal" href="#managing-key-material">Managing key material</a></li>
+<li><a class="reference internal" href="#safe-outputs-on-error">Safe outputs on error</a></li>
+<li><a class="reference internal" href="#attack-resistance">Attack resistance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-implementation-considerations">Other implementation considerations</a><ul>
+<li><a class="reference internal" href="#philosophy-of-resource-management">Philosophy of resource management</a></li>
+</ul>
+</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="conventions.html" title="previous chapter">Library conventions</a></li>
+ <li>Next: <a href="usage.html" title="next chapter">Usage 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/implementation.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/implementation.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file