TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c6b75f89526b234e1bc6a8a8f0c0e57624372954 / . / docs / 1.0.1 / html / overview / implementation.html
blob: 39f7205859387f3f462cc57236cce1a970bdc76b [file] [log] [blame]
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta charset="utf-8" />
<title>6. Implementation considerations &#8212; PSA Crypto API 1.0.1 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" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></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>
<script type="text/javascript" src="../_static/language_data.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 notranslate"><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 notranslate"><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 notranslate"><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><p>Input domains: the macro must be valid for arguments within the input domain.</p></li>
<li><p>A return type: the macro result must be compatible with this type.</p></li>
<li><p>Output range: the macro result must lie in the output range.</p></li>
<li><p>Computed value: A precise mapping of valid input to output values.</p></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><p>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>.</p></li>
<li><p>The expected computation for valid and supported input arguments will be
defined as pseudo-code in a future version of this specification.</p></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>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 notranslate"><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="simple">
<dt><code class="docutils literal notranslate"><span class="pre">uint8_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint16_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint32_t</span></code></dt><dd><p>Unsigned integer types with 8, 16 and 32 value bits respectively.
These types are defined by the C99 header <code class="file docutils literal notranslate"><span class="pre">stdint.h</span></code>.</p>
</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 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>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><p>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.</p></li>
<li><p>Each client has an independent identifier namespace, and the implementation
uses a client specific identifier-to-key mapping when looking up the key.</p></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="../api/keys/lifetimes.html#key-lifetimes"><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/policy.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a>
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><p>For volatile keys or keys in a secure element with no open/close mechanism,
this is likely to have no effect.</p></li>
<li><p>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.</p></li>
<li><p>For keys in a secure element with an open/close mechanism, this is a hint to
keep the key open in the secure element.</p></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 notranslate"><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 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>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 notranslate"><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><p>Pre-allocate memory for a predefined number of keys, each with sufficient
memory for all key types that can be stored.</p></li>
<li><p>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.</p></li>
<li><p>In an implementation with isolation, pre-allocate memory for a predefined
number of operations inside the cryptoprocessor.</p></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.0.1
<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/specdef_values.html">Example macro implementations</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 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
</body>
</html>