Add version 1.1.0 and make it the latest version
docs/1.1.0 obtained by running update_psa_crypto_api.sh with a directory
containing psa-crypto-api at tag psa-crypto-api-1.1.0, built inside a Docker
image built from its scripts/Dockerfile.
Update index.md and switch the "latest" version to be 1.1.0.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/1.1.0/html/overview/implementation.html b/docs/1.1.0/html/overview/implementation.html
new file mode 100644
index 0000000..61d40b1
--- /dev/null
+++ b/docs/1.1.0/html/overview/implementation.html
@@ -0,0 +1,376 @@
+
+<!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>6. Implementation considerations — 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="7. Usage considerations" href="usage.html" />
+ <link rel="prev" title="5. 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>6. Implementation considerations</h1>
+<div class="section" id="implementation-specific-aspects-of-the-interface">
+<h2>6.1. Implementation-specific aspects of the interface</h2>
+<div class="section" id="implementation-profile">
+<h3>6.1.1. 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>6.1.2. 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 <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code>,
+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>6.1.3. 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>
+<dl class="docutils" id="specification-defined-value">
+<dt><em>Specification-defined value</em></dt>
+<dd><p class="first">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="last simple">
+<li>Example implementations are provided in an appendix to this specification.
+See <a class="reference internal" href="../appendix/specdef_values.html#appendix-specdef-values"><span class="secref">Example macro implementations</span></a>.</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>
+</dd>
+</dl>
+<dl class="docutils" id="implementation-defined-value">
+<dt><em>Implementation-defined value</em></dt>
+<dd><p class="first">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 class="last">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>
+</dd>
+</dl>
+<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>6.2. Porting to a platform</h2>
+<div class="section" id="platform-assumptions">
+<h3>6.2.1. 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>6.2.2. 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 <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code> 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 <code class="file docutils literal"><span class="pre">stdint.h</span></code>.</dd>
+</dl>
+</div>
+<div class="section" id="cryptographic-hardware-support">
+<h3>6.2.3. 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>6.3. Security requirements and recommendations</h2>
+<div class="section" id="error-detection">
+<h3>6.3.1. Error detection</h3>
+<p>Implementations that provide <a class="reference internal" href="../about.html#term-isolation"><span class="term">isolation</span></a> 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>6.3.2. 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>6.3.3. 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>6.3.4. 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="../about.html#term-volatile-key"><span class="term">volatile key</span></a> to a
+temporary location in non-volatile memory. The implementation must delete any
+non-volatile 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 memory cleanup rule (see <a class="reference internal" href="#memory-cleanup"><span class="secref">Memory cleanup</span></a>) for a <a class="reference internal" href="../about.html#term-persistent-key"><span class="term">persistent key</span></a>
+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/policy.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>
+usage flag in a key 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>6.3.5. 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
+<a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a>.</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>6.3.6. 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>6.4. Other implementation considerations</h2>
+<div class="section" id="philosophy-of-resource-management">
+<h3>6.4.1. 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 with <a class="reference internal" href="../about.html#term-no-isolation"><span class="term">no isolation</span></a>, 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 <a class="reference internal" href="../about.html#term-isolation"><span class="term">isolation</span></a>, 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"><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"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">6. Implementation considerations</a><ul>
+<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>
+<li class="toctree-l3"><a class="reference internal" href="#implementation-profile">6.1.1. Implementation profile</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-types">6.1.2. Implementation-specific types</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#implementation-specific-macros">6.1.3. Implementation-specific macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#porting-to-a-platform">6.2. Porting to a platform</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#platform-assumptions">6.2.1. Platform assumptions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#platform-specific-types">6.2.2. Platform-specific types</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#cryptographic-hardware-support">6.2.3. Cryptographic hardware support</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#security-requirements-and-recommendations">6.3. Security requirements and recommendations</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#error-detection">6.3.1. Error detection</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#indirect-object-references">6.3.2. Indirect object references</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#memory-cleanup">6.3.3. Memory cleanup</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#managing-key-material">6.3.4. Managing key material</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#safe-outputs-on-error">6.3.5. Safe outputs on error</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#attack-resistance">6.3.6. Attack resistance</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#other-implementation-considerations">6.4. Other implementation considerations</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#philosophy-of-resource-management">6.4.1. Philosophy of resource management</a></li>
+</ul>
+</li>
+</ul>
+</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>
\ No newline at end of file