Update PSA API specification to 1.0.1
Generated according to the instructions in update_psa_crypto_api.sh
using the tag psa-crypto-api-1.0.1.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/html/overview/conventions.html b/docs/html/overview/conventions.html
index b294ef6..0d7a82f 100644
--- a/docs/html/overview/conventions.html
+++ b/docs/html/overview/conventions.html
@@ -5,26 +5,27 @@
<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>
+ <title>5. Library conventions — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Implementation considerations" href="implementation.html" />
- <link rel="prev" title="Sample architectures" href="sample-arch.html" />
+ <link rel="next" title="6. Implementation considerations" href="implementation.html" />
+ <link rel="prev" title="4. Sample architectures" href="sample-arch.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,11 +41,11 @@
<div class="body" role="main">
<div class="section" id="library-conventions">
-<h1>Library conventions</h1>
+<h1>5. Library conventions</h1>
<div class="section" id="error-handling">
-<h2>Error handling</h2>
+<h2>5.1. Error handling</h2>
<div class="section" id="return-status">
-<h3>Return status</h3>
+<h3>5.1.1. Return status</h3>
<p>Almost all functions return a status indication of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>. This
is an enumeration of integer values, with <code class="docutils literal"><span class="pre">0</span></code> (<a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>) indicating
successful operation and other values indicating errors. The exceptions are
@@ -63,7 +64,7 @@
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>
+<h3>5.1.2. Behavior on error</h3>
<p>All function calls must be implemented atomically:</p>
<ul class="simple">
<li>When a function returns a type other than <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>, the requested
@@ -112,9 +113,9 @@
</div>
</div>
<div class="section" id="parameter-conventions">
-<h2>Parameter conventions</h2>
+<h2>5.2. Parameter conventions</h2>
<div class="section" id="pointer-conventions">
-<h3>Pointer conventions</h3>
+<h3>5.2.1. Pointer conventions</h3>
<p>Unless explicitly stated in the documentation of a function, all pointers must
be valid pointers to an object of the specified type.</p>
<p>A parameter is considered a <strong>buffer</strong> if it points to an array of bytes. A
@@ -131,10 +132,10 @@
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>
+<a class="reference internal" href="#stability-of-parameters"><span class="secref">Stability of parameters</span></a> section.</p>
</div>
<div class="section" id="input-buffer-sizes">
-<h3>Input buffer sizes</h3>
+<h3>5.2.2. Input buffer sizes</h3>
<p>For input buffers, the parameter convention is:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
@@ -146,7 +147,7 @@
<p>The interface never uses input-output buffers.</p>
</div>
<div class="section" id="output-buffer-sizes">
-<h3>Output buffer sizes</h3>
+<h3>5.2.3. Output buffer sizes</h3>
<p>For output buffers, the parameter convention is:</p>
<dl class="docutils">
<dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
@@ -181,7 +182,7 @@
</dl>
</div>
<div class="section" id="overlap-between-parameters">
-<h3>Overlap between parameters</h3>
+<h3>5.2.4. Overlap between parameters</h3>
<p>Output parameters that are not buffers must not overlap with any input buffer or
with any other output parameter. Otherwise, the behavior is undefined.</p>
<p>Output buffers can overlap with input buffers. In this event, the implementation
@@ -191,10 +192,10 @@
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>
+<a class="reference internal" href="#stability-of-parameters"><span class="secref">Stability of parameters</span></a> section.</p>
</div>
<div class="section" id="stability-of-parameters">
-<span id="id1"></span><h3>Stability of parameters</h3>
+<span id="id1"></span><h3>5.2.5. Stability of parameters</h3>
<p>In some environments, it is possible for the content of a parameter to change
while a function is executing. It might also be possible for the content of an
output parameter to be read before the function terminates. This can happen if
@@ -230,10 +231,10 @@
</div>
</div>
<div class="section" id="key-types-and-algorithms">
-<h2>Key types and algorithms</h2>
+<h2>5.3. 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>
+Each is encoded by using an integral type: <a class="reference internal" href="../api/keys/types.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a> and
+<a class="reference internal" href="../api/ops/algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p>
<p>There is some overlap in the information conveyed by key types and algorithms.
Both types contain enough information, so that the meaning of an algorithm type
value does not depend on what type of key it is used with, and vice versa.
@@ -244,7 +245,7 @@
<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>
+<h3>5.3.1. 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
@@ -267,19 +268,23 @@
</div>
</div>
<div class="section" id="concurrent-calls">
-<span id="concurrency"></span><h2>Concurrent calls</h2>
+<span id="concurrency"></span><h2>5.4. 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>
+separate threads. In such an environment, <em>concurrent calls</em> are two or more
+calls to the API whose execution can overlap in time.</p>
+<p>Concurrent calls are performed correctly, as if the calls were executed in
+sequence, provided that they obey the following constraints:</p>
<ul class="simple">
<li>There is no overlap between an output parameter of one call and an input or
output parameter of another call. Overlap between input parameters is
permitted.</li>
-<li>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>A call to destroy a key must not overlap with a concurrent call to any of
+the following functions:<ul>
+<li>Any call where the same key identifier is a parameter to the call.</li>
+<li>Any call in a multi-part operation, where the same key identifier was
+used as a parameter to a previous step in the multi-part operation.</li>
+</ul>
+</li>
<li>Concurrent calls must not use the same operation object.</li>
</ul>
<p>If any of these constraints are violated, the behavior is undefined.</p>
@@ -294,47 +299,54 @@
</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>
+ <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><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>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></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>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">5. Library conventions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#error-handling">5.1. Error handling</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#return-status">5.1.1. Return status</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#behavior-on-error">5.1.2. Behavior on error</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#parameter-conventions">5.2. Parameter conventions</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#pointer-conventions">5.2.1. Pointer conventions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#input-buffer-sizes">5.2.2. Input buffer sizes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#output-buffer-sizes">5.2.3. Output buffer sizes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#overlap-between-parameters">5.2.4. Overlap between parameters</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#stability-of-parameters">5.2.5. Stability of parameters</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#key-types-and-algorithms">5.3. Key types and algorithms</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#structure-of-key-and-algorithm-types">5.3.1. Structure of key and algorithm types</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#concurrent-calls">5.4. Concurrent calls</a></li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -350,15 +362,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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>
diff --git a/docs/html/overview/functionality.html b/docs/html/overview/functionality.html
index 5f9d447..daaba7a 100644
--- a/docs/html/overview/functionality.html
+++ b/docs/html/overview/functionality.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Functionality overview — PSA Crypto API 1.0.0 documentation</title>
+ <title>3. Functionality overview — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Sample architectures" href="sample-arch.html" />
- <link rel="prev" title="Design goals" href="goals.html" />
+ <link rel="next" title="4. Sample architectures" href="sample-arch.html" />
+ <link rel="prev" title="2. Design goals" href="goals.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,20 +41,21 @@
<div class="body" role="main">
<div class="section" id="functionality-overview">
-<span id="id1"></span><h1>Functionality overview</h1>
+<span id="id1"></span><h1>3. Functionality overview</h1>
<p>This section provides a high-level overview of the functionality provided by the
-interface defined in this specification. Refer to the <a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">API definition</span></a> for a detailed description.</p>
+interface defined in this specification. Refer to the
+<a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">API definition</span></a> for a detailed description.</p>
<p><a class="reference internal" href="../appendix/history.html#future"><span class="std std-ref">Future additions</span></a> describes features that might be included in future versions of this
specification.</p>
<p>Due to the modularity of the interface, almost every part of the library is
optional. The only mandatory function is <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</p>
<div class="section" id="library-management">
-<h2>Library management</h2>
+<h2>3.1. Library management</h2>
<p>Applications must call <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a> to initialize the library before
using any other function.</p>
</div>
<div class="section" id="key-management">
-<h2>Key management</h2>
+<h2>3.2. Key management</h2>
<p>Applications always access keys indirectly via an identifier, and can perform
operations using a key without accessing the key material. This allows keys to
be <em>non-extractable</em>, where an application can use a key but is not permitted to
@@ -62,107 +64,53 @@
<p>Each key has a set of attributes that describe the key and the policy for using
the key. A <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object contains all of the attributes, which
is used when creating a key and when querying key attributes.</p>
-<p>Each key has a <em>lifetime</em> that determines when the key material is destroyed.
-There are two types of lifetimes: <a class="reference internal" href="#volatile-keys"><span class="std std-ref">volatile</span></a> and
-<a class="reference internal" href="#persistent-keys"><span class="std std-ref">persistent</span></a>.</p>
-<div class="section" id="volatile-keys">
-<span id="id2"></span><h3>Volatile keys</h3>
-<p>A <em>volatile</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>
-or until the application terminates, which conceptually destroys all of its
-volatile keys.</p>
-<p>Conceptually, a volatile key is stored in RAM. Volatile keys have the
-lifetime <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>.</p>
-<p>To create a volatile key:</p>
-<ol class="arabic simple">
-<li>Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the required type, size, policy
-and other key attributes.</li>
-<li>Create the key with <a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>,
-<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>. If successful, these
-functions output a transient <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a>.</li>
-</ol>
-<p>To destroy a volatile key, call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier.</p>
-</div>
-<div class="section" id="persistent-keys">
-<span id="id3"></span><h3>Persistent keys</h3>
-<p>A <em>persistent</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>
-or until it is wiped by the reset or destruction of the device.</p>
-<p>Each persistent key has a permanent key identifier, which acts as a name for the key.
-Within an application, the key identifier corresponds to a single key. The
-application specifies the key identifier when the key is created and when
-using the key.</p>
-<p>Persistent keys can be stored in different storage areas; this is indicated
-through different lifetime values. This specification defines a single lifetime
-value <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a> which corresponds to a default storage
-area. Implementations can define alternative lifetime values corresponding to
-different storage areas with different retention policies, or to secure elements
-with different security characteristics.</p>
-<p>To create a persistent key:</p>
-<ol class="arabic">
-<li><p class="first">Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the key’s type, size, policy
-and other attributes.</p>
-</li>
-<li><p class="first">In the attributes object, set the desired lifetime and persistent identifier
-for the key.</p>
-</li>
-<li><p class="first">Create the key with one of the <em>key creation functions</em>:</p>
+<p>The key attributes include:</p>
+<ul class="simple">
+<li>A <a class="reference internal" href="../api/keys/types.html#key-types"><span class="std std-ref">type</span></a> and size that describe the key material.</li>
+<li>The key <a class="reference internal" href="#key-ids"><span class="std std-ref">identifier</span></a> that the application uses to refer to the key.</li>
+<li>A <a class="reference internal" href="#key-life"><span class="std std-ref">lifetime</span></a> that determines when the key material is destroyed, and where it is stored.</li>
+<li>A <a class="reference internal" href="#key-usage-policies"><span class="std std-ref">policy</span></a> that determines how the key can be used.</li>
+</ul>
+<p>Keys are created using one of the <em>key creation functions</em>:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a></li>
<li><a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a></li>
<li><a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a></li>
<li><a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a></li>
</ul>
-<p>If successful, these functions output the <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a>
-that was specified by the application in step 2.</p>
-</li>
-</ol>
-<p>To access an existing persistent key: use the key identifier in any API that
-requires a key.</p>
-<p>To remove cached copies of key material for persistent keys created with 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: call <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> with the key identifier.</p>
-<p>To destroy a persistent key: call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier.
-Destroying a persistent key permanently removes it from memory and storage.</p>
-<p>The key lifetime and identifier are set when the key is created and cannot be
-changed without destroying the key first. If the original key permits copying,
-then the application can specify a different lifetime for the copy of the key.</p>
-</div>
-<div class="section" id="key-identifiers">
-<span id="key-ids"></span><h3>Key identifiers</h3>
-<p>Key identifiers are integral values that act as permanent names for persistent
-keys, or as transient references to volatile keys. Key identifiers use the
-<a class="reference internal" href="../api/keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_id_t</span></code></a> type, and the range of identifier values is divided as follows:</p>
-<dl class="docutils">
-<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"> <span class="pre">=</span> <span class="pre">0</span></code></dt>
-<dd>Reserved as an invalid key identifier.</dd>
-<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a></dt>
-<dd>Applications can freely choose persistent key identifiers in this range.</dd>
-<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code></a></dt>
-<dd>Implementations can define additional persistent key identifiers in this
-range, and must allocate any volatile key identifiers from this range.</dd>
-</dl>
-<p>Key identifiers outside these ranges are reserved for future use.</p>
-<p>Key identifiers are output from a successful call to one of
-the key creation functions. For persistent keys, this is the same identifier
-as the one specified in the key attributes used to create the key.
-The key identifier remains valid until it is invalidated by passing it to
-<a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>. A volatile key identifier must not be used after it has been
-invalidated.</p>
-<p>Valid key identifiers must have distinct values within the same application. If
-the implementation provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key
-identifiers are local to each application. That is, the same key identifier in two
-applications corresponds to two different keys.</p>
-<p>If an invalid key identifier is provided as a parameter in any function, the
-function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a>; except for the special case of
-calling <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="docutils literal"><span class="pre">psa_destroy_key</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"><span class="pre">)</span></code>, which has no effect and always
-returns <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>.</p>
-<p>There must be a matching call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> for each successful call
-to a create a volatile key.</p>
+<p>These output the key identifier, that is used to access the key in all other parts of the API.</p>
+<p>All of the key attributes are set when the key is created and cannot be changed
+without destroying the key first. If the original key permits copying, then the
+application can specify a different lifetime or restricted policy for the
+copy of the key.</p>
<p>A call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> destroys the key material, and will cause any active
operations that are using the key to fail. Therefore an application must not
destroy a key while an operation using that key is in progress, unless the
application is prepared to handle a failure of the operation.</p>
+<div class="section" id="key-identifiers">
+<span id="key-ids"></span><h3>3.2.1. Key identifiers</h3>
+<p>Key identifiers are integral values that act as permanent names for persistent keys, or as transient references to volatile keys. Key identifiers are defined by the application for persistent keys, and by the implementation for volatile keys and for built-in keys.</p>
+<p>Key identifiers are output from a successful call to one of the key creation functions.</p>
+<p>Valid key identifiers must have distinct values within the same application. If
+the implementation provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key
+identifiers are local to each application. That is, the same key identifier in two
+applications corresponds to two different keys.</p>
+<p>See <a class="reference internal" href="../api/keys/ids.html#key-identifiers"><span class="secref">Key identifiers</span></a>.</p>
+</div>
+<div class="section" id="key-lifetimes">
+<span id="key-life"></span><h3>3.2.2. Key lifetimes</h3>
+<p>The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.</p>
+<p>There are two main types of lifetimes: <em>volatile</em> and <em>persistent</em>.</p>
+<p>Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Volatile key identifiers are allocated by the implementation when the key is created. Volatile keys can be explicitly destroyed with a call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>.</p>
+<p>Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset. The key identifier for a persistent key is set by the application when creating the key, and remains valid throughout the lifetime of the key, even if the application instance that created the key terminates.</p>
+<p>See <a class="reference internal" href="../api/keys/lifetimes.html#key-lifetimes"><span class="secref">Key lifetimes</span></a>.</p>
+</div>
+<div class="section" id="key-policies">
+<span id="key-usage-policies"></span><h3>3.2.3. Key policies</h3>
+<p>All keys have an associated policy that regulates which operations are permitted on the key. Each key policy is a set of usage flags and a specific algorithm that is permitted with the key. See <a class="reference internal" href="../api/keys/policy.html#key-policy"><span class="secref">Key policies</span></a>.</p>
</div>
<div class="section" id="recommendations-of-minimum-standards-for-key-management">
-<h3>Recommendations of minimum standards for key management</h3>
+<h3>3.2.4. Recommendations of minimum standards for key management</h3>
<p>Most implementations provide the following functions:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>. The exceptions are implementations that only give access
@@ -181,38 +129,8 @@
</ul>
</div>
</div>
-<div class="section" id="usage-policies">
-<h2>Usage policies</h2>
-<p>All keys have an associated policy that regulates which operations are permitted
-on the key. Each key policy is a set of usage flags and a specific algorithm
-that is permitted with the key. The policy is part of the key attributes that
-are managed by a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object.</p>
-<p>The usage flags are encoded in a bitmask, which has the type
-<a class="reference internal" href="../api/keys/attributes.html#c.psa_key_usage_t" title="psa_key_usage_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_usage_t</span></code></a>. Four kinds of usage flag can be specified:</p>
-<ul class="simple">
-<li>The extractable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a> determines whether the key
-material can be extracted.</li>
-<li>The copyable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> determines whether the key material
-can be copied into a new key, which can have a different lifetime or a more
-restrictive policy.</li>
-<li>The cacheable flag <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> determines whether the
-implementation is permitted to retain non-essential copies of the
-key material in RAM. This policy only applies to persistent keys. See also
-<em><a class="reference internal" href="implementation.html#key-material"><span class="std std-ref">Managing key material</span></a></em>.</li>
-<li>The other usage flags, for example, <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> and <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>,
-determine whether the corresponding operation is permitted on the key.</li>
-</ul>
-<p>In addition to the usage bitmask, a policy specifies which algorithm is
-permitted with the key. This specification only defines policies that restrict
-keys to a single algorithm, which is consistent with both common practice and
-security good practice.</p>
-<p>A highly constrained implementation might not be able to support all the policies
-that can be expressed through this interface. If an implementation cannot create
-a key with the required policy, it must return an appropriate error code when
-the key is created.</p>
-</div>
<div class="section" id="symmetric-cryptography">
-<h2>Symmetric cryptography</h2>
+<h2>3.3. Symmetric cryptography</h2>
<p>This specification defines interfaces for the following types of symmetric
cryptographic operation:</p>
<ul class="simple">
@@ -228,16 +146,16 @@
<li>A series of functions that permit <em>multi-part operations</em>.</li>
</ul>
<div class="section" id="single-part-functions">
-<h3>Single-part Functions</h3>
+<h3>3.3.1. Single-part Functions</h3>
<p>Single-part functions are APIs that implement the cryptographic operation in a
single function call. This is the easiest API to use when all of the inputs and
outputs fit into the application memory.</p>
<p>Some use cases involve messages that are too large to be assembled in memory, or
require non-default configuration of the algorithm. These use cases require the
-use of a <em><a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a></em>.</p>
+use of a <a class="reference internal" href="#multi-part-operations"><span class="secref">multi-part operation</span></a>.</p>
</div>
<div class="section" id="multi-part-operations">
-<span id="id4"></span><h3>Multi-part operations</h3>
+<span id="id2"></span><h3>3.3.2. Multi-part operations</h3>
<p>Multi-part operations are APIs which split a single cryptographic operation into
a sequence of separate steps. This enables fine control over the configuration
of the cryptographic operation, and allows the message data to be processed in
@@ -328,7 +246,7 @@
functions, and any requirements about their usage and ordering.</p>
</div>
<div class="section" id="message-digests-hashes">
-<h3>Message digests (Hashes)</h3>
+<h3>3.3.3. Message digests (Hashes)</h3>
<p>The single-part hash functions are:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> to calculate the hash of a message.</li>
@@ -357,7 +275,7 @@
<p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_abort()</span></code></a>.</p>
</div>
<div class="section" id="message-authentication-codes-macs">
-<h3>Message authentication codes (MACs)</h3>
+<h3>3.3.4. Message authentication codes (MACs)</h3>
<p>The single-part MAC functions are:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/ops/macs.html#c.psa_mac_compute" title="psa_mac_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_compute()</span></code></a> to calculate the MAC of a message.</li>
@@ -381,13 +299,13 @@
<p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</p>
</div>
<div class="section" id="encryption-and-decryption">
-<h3>Encryption and decryption</h3>
+<h3>3.3.5. Encryption and decryption</h3>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The unauthenticated cipher API is provided to implement legacy protocols and
for use cases where the data integrity and authenticity is guaranteed by
non-cryptographic means. It is recommended that newer protocols use
-<em><a class="reference internal" href="#func-aead"><span class="std std-ref">Authenticated encryption (AEAD)</span></a></em>.</p>
+<a class="reference internal" href="#func-aead"><span class="secref">Authenticated encryption (AEAD)</span></a>.</p>
</div>
<p>The single-part functions for encrypting or decrypting a message using an
unauthenticated symmetric cipher are:</p>
@@ -423,7 +341,7 @@
<p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
</div>
<div class="section" id="authenticated-encryption-aead">
-<span id="func-aead"></span><h3>Authenticated encryption (AEAD)</h3>
+<span id="func-aead"></span><h3>3.3.6. Authenticated encryption (AEAD)</h3>
<p>The single-part AEAD functions are:</p>
<ul class="simple">
<li><a class="reference internal" href="../api/ops/aead.html#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a> to encrypt a message using an authenticated symmetric
@@ -431,7 +349,7 @@
<li><a class="reference internal" href="../api/ops/aead.html#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> to decrypt a message using an authenticated symmetric
cipher.</li>
</ul>
-<p>These functions follow the interface recommended by <a class="reference external" href="https://tools.ietf.org/html/rfc5116.html">RFC 5116</a>.</p>
+<p>These functions follow the interface recommended by <span><em>An Interface and Algorithms for Authenticated Encryption</em> <a class="reference internal" href="../about.html#citation-rfc5116"><span class="cite">[RFC5116]</span></a></span>.</p>
<p>The encryption function requires a nonce to be provided. To generate a random
nonce, either call <a class="reference internal" href="../api/ops/rng.html#c.psa_generate_random" title="psa_generate_random"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_random()</span></code></a> or use the AEAD multi-part API.</p>
<p>The <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
@@ -478,7 +396,7 @@
these lengths before providing input.</p>
</div>
<div class="section" id="key-derivation">
-<span id="id5"></span><h3>Key derivation</h3>
+<span id="id3"></span><h3>3.3.7. Key derivation</h3>
<p>A key derivation encodes a deterministic method to generate a finite stream of
bytes. This data stream is computed by the cryptoprocessor and extracted in
chunks. If two key derivation operations are constructed with the same
@@ -528,12 +446,12 @@
will not be used for different purposes.</p>
</div>
<div class="section" id="example-of-the-symmetric-cryptography-api">
-<h3>Example of the symmetric cryptography API</h3>
+<h3>3.3.8. Example of the symmetric cryptography API</h3>
<p>Here is an example of a use case where a master key is used to generate both a
message encryption key and an IV for the encryption, and the derived key and IV
are then used to encrypt a message.</p>
<ol class="arabic simple">
-<li>Derive the message encryption material from the master key.<ol class="arabic">
+<li>Derive the message encryption material from the master key.<ol class="loweralpha">
<li>Initialize a <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a> object to zero or to
<a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</li>
<li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_setup" title="psa_key_derivation_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_setup()</span></code></a> with <a class="reference internal" href="../api/ops/kdf.html#c.PSA_ALG_HKDF" title="PSA_ALG_HKDF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_HKDF</span></code></a> as the algorithm.</li>
@@ -550,7 +468,7 @@
memory.</li>
</ol>
</li>
-<li>Encrypt the message with the derived material.<ol class="arabic">
+<li>Encrypt the message with the derived material.<ol class="loweralpha">
<li>Initialize a <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero or to
<a class="reference internal" href="../api/ops/ciphers.html#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</li>
<li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> with the derived message encryption key.</li>
@@ -564,16 +482,16 @@
</div>
</div>
<div class="section" id="asymmetric-cryptography">
-<h2>Asymmetric cryptography</h2>
+<h2>3.4. Asymmetric cryptography</h2>
<p>This specification defines functions for asymmetric cryptography, including
asymmetric encryption, asymmetric signature, and two-way key agreement.</p>
<div class="section" id="asymmetric-encryption">
-<h3>Asymmetric encryption</h3>
+<h3>3.4.1. Asymmetric encryption</h3>
<p>Asymmetric encryption is provided through the functions
<a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_encrypt()</span></code></a> and <a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_decrypt()</span></code></a>.</p>
</div>
<div class="section" id="hash-and-sign">
-<h3>Hash-and-sign</h3>
+<h3>3.4.2. Hash-and-sign</h3>
<p>The signature and verification functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and
<a class="reference internal" href="../api/ops/sign.html#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> take a message as one of their inputs and perform a
hash-and-sign algorithm.</p>
@@ -581,28 +499,28 @@
one of their inputs. This is useful for signing pre-computed hashes, or for
implementing hash-and-sign using a <a class="reference internal" href="../api/ops/hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a>
before signing the resulting hash. To determine which
-hash algorithm to use, call the macro <a class="reference internal" href="../api/keys/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the
+hash algorithm to use, call the macro <a class="reference internal" href="../api/ops/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the
corresponding signature algorithm.</p>
<p>Some hash-and-sign algorithms add padding to the message hash before completing
the signing operation. The format of the padding that is used depends on the
algorithm used to construct the signature.</p>
</div>
<div class="section" id="key-agreement">
-<h3>Key agreement</h3>
+<h3>3.4.3. Key agreement</h3>
<p>This specification defines two functions for a Diffie-Hellman-style key
agreement where each party combines its own private key with the peer’s public
key.</p>
-<p>The recommended approach is to use a <a class="reference internal" href="#key-derivation"><span class="std std-ref">key derivation
-operation</span></a> with the <a class="reference internal" href="../api/ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>
-input function, which calculates a shared secret for the key derivation
-function.</p>
+<p>The recommended approach is to use a
+<a class="reference internal" href="#key-derivation"><span class="std std-ref">key derivation operation</span></a> with the
+<a class="reference internal" href="../api/ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> input function, which calculates a shared
+secret for the key derivation function.</p>
<p>Where an application needs direct access to the shared secret, it can call
<a class="reference internal" href="../api/ops/ka.html#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a> instead. Note that in general the shared secret is not
directly suitable for use as a key because it is biased.</p>
</div>
</div>
<div class="section" id="randomness-and-key-generation">
-<h2>Randomness and key generation</h2>
+<h2>3.5. Randomness and key generation</h2>
<p>We strongly recommended that implementations include a random generator,
consisting of a cryptographically secure pseudo-random generator (CSPRNG), which
is adequately seeded with a cryptographic-quality hardware entropy source,
@@ -623,56 +541,62 @@
</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="#">Functionality overview</a><ul>
-<li><a class="reference internal" href="#library-management">Library management</a></li>
-<li><a class="reference internal" href="#key-management">Key management</a><ul>
-<li><a class="reference internal" href="#volatile-keys">Volatile keys</a></li>
-<li><a class="reference internal" href="#persistent-keys">Persistent keys</a></li>
-<li><a class="reference internal" href="#key-identifiers">Key identifiers</a></li>
-<li><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">Recommendations of minimum standards for key management</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#usage-policies">Usage policies</a></li>
-<li><a class="reference internal" href="#symmetric-cryptography">Symmetric cryptography</a><ul>
-<li><a class="reference internal" href="#single-part-functions">Single-part Functions</a></li>
-<li><a class="reference internal" href="#multi-part-operations">Multi-part operations</a></li>
-<li><a class="reference internal" href="#message-digests-hashes">Message digests (Hashes)</a></li>
-<li><a class="reference internal" href="#message-authentication-codes-macs">Message authentication codes (MACs)</a></li>
-<li><a class="reference internal" href="#encryption-and-decryption">Encryption and decryption</a></li>
-<li><a class="reference internal" href="#authenticated-encryption-aead">Authenticated encryption (AEAD)</a></li>
-<li><a class="reference internal" href="#key-derivation">Key derivation</a></li>
-<li><a class="reference internal" href="#example-of-the-symmetric-cryptography-api">Example of the symmetric cryptography API</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#asymmetric-cryptography">Asymmetric cryptography</a><ul>
-<li><a class="reference internal" href="#asymmetric-encryption">Asymmetric encryption</a></li>
-<li><a class="reference internal" href="#hash-and-sign">Hash-and-sign</a></li>
-<li><a class="reference internal" href="#key-agreement">Key agreement</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#randomness-and-key-generation">Randomness and key generation</a></li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <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><a href="../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="goals.html" title="previous chapter">Design goals</a></li>
- <li>Next: <a href="sample-arch.html" title="next chapter">Sample architectures</a></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../_sources/overview/functionality.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<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 current"><a class="current reference internal" href="#">3. Functionality overview</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#library-management">3.1. Library management</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#key-management">3.2. Key management</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#key-identifiers">3.2.1. Key identifiers</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#key-lifetimes">3.2.2. Key lifetimes</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#key-policies">3.2.3. Key policies</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">3.2.4. Recommendations of minimum standards for key management</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#symmetric-cryptography">3.3. Symmetric cryptography</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#single-part-functions">3.3.1. Single-part Functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#multi-part-operations">3.3.2. Multi-part operations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#message-digests-hashes">3.3.3. Message digests (Hashes)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#message-authentication-codes-macs">3.3.4. Message authentication codes (MACs)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#encryption-and-decryption">3.3.5. Encryption and decryption</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#authenticated-encryption-aead">3.3.6. Authenticated encryption (AEAD)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#key-derivation">3.3.7. Key derivation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#example-of-the-symmetric-cryptography-api">3.3.8. Example of the symmetric cryptography API</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#asymmetric-cryptography">3.4. Asymmetric cryptography</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption">3.4.1. Asymmetric encryption</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#hash-and-sign">3.4.2. Hash-and-sign</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#key-agreement">3.4.3. Key agreement</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="#randomness-and-key-generation">3.5. Randomness and key generation</a></li>
+</ul>
+</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"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -688,15 +612,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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/functionality.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/overview/goals.html b/docs/html/overview/goals.html
index 028cf5e..0185da7 100644
--- a/docs/html/overview/goals.html
+++ b/docs/html/overview/goals.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Design goals — PSA Crypto API 1.0.0 documentation</title>
+ <title>2. Design goals — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Functionality overview" href="functionality.html" />
- <link rel="prev" title="Introduction" href="intro.html" />
+ <link rel="next" title="3. Functionality overview" href="functionality.html" />
+ <link rel="prev" title="1. Introduction" href="intro.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,9 +41,9 @@
<div class="body" role="main">
<div class="section" id="design-goals">
-<span id="id1"></span><h1>Design goals</h1>
+<span id="id1"></span><h1>2. Design goals</h1>
<div class="section" id="suitable-for-constrained-devices">
-<h2>Suitable for constrained devices</h2>
+<h2>2.1. Suitable for constrained devices</h2>
<p>The interface is suitable for a vast range of devices: from special-purpose
cryptographic processors that process data with a built-in key, to constrained
devices running custom application code, such as microcontrollers, and
@@ -70,7 +71,7 @@
free to choose which memory area to use for internal data.</p>
</div>
<div class="section" id="a-keystore-interface">
-<h2>A keystore interface</h2>
+<h2>2.2. A keystore interface</h2>
<p>The specification allows cryptographic operations to be performed on a key to
which the application does not have direct access. Except where required for
interchange, applications access all keys indirectly, by an identifier. The key
@@ -79,7 +80,7 @@
defined when the key is created.</p>
</div>
<div class="section" id="optional-isolation">
-<span id="isolation"></span><h2>Optional isolation</h2>
+<span id="isolation"></span><h2>2.3. Optional isolation</h2>
<p>Implementations can isolate the cryptoprocessor from the calling application,
and can further isolate multiple calling applications. The interface allows the
implementation to be separated between a frontend and a backend. In an isolated
@@ -122,7 +123,7 @@
</ul>
</div>
<div class="section" id="choice-of-algorithms">
-<h2>Choice of algorithms</h2>
+<h2>2.4. Choice of algorithms</h2>
<p>The specification defines a low-level cryptographic interface, where the caller
explicitly chooses which algorithm and which security parameters they use. This
is necessary to implement protocols that are inescapable in various use cases.
@@ -149,7 +150,7 @@
hash algorithm.</p>
</div>
<div class="section" id="ease-of-use">
-<h2>Ease of use</h2>
+<h2>2.5. Ease of use</h2>
<p>The interface is designed to be as user-friendly as possible, given the
aforementioned constraints on suitability for various types of devices and on
the freedom to choose algorithms.</p>
@@ -162,39 +163,39 @@
constraints.</p>
</div>
<div class="section" id="example-use-cases">
-<h2>Example use cases</h2>
+<h2>2.6. Example use cases</h2>
<p>This section lists some of the use cases that were considered during the design
of this API. This list is not exhaustive, nor are all implementations required to
support all use cases.</p>
<div class="section" id="network-security-tls">
-<h3>Network Security (TLS)</h3>
+<h3>2.6.1. Network Security (TLS)</h3>
<p>The API provides all of the cryptographic primitives needed to establish TLS
connections.</p>
</div>
<div class="section" id="secure-storage">
-<h3>Secure Storage</h3>
+<h3>2.6.2. Secure Storage</h3>
<p>The API provides all primitives related to storage encryption, block or
file-based, with master encryption keys stored inside a key store.</p>
</div>
<div class="section" id="network-credentials">
-<h3>Network Credentials</h3>
+<h3>2.6.3. Network Credentials</h3>
<p>The API provides network credential management inside a key store, for example,
for X.509-based authentication or pre-shared keys on enterprise networks.</p>
</div>
<div class="section" id="device-pairing">
-<h3>Device Pairing</h3>
+<h3>2.6.4. Device Pairing</h3>
<p>The API provides support for key agreement protocols that are often used for
secure pairing of devices over wireless channels. For example, the pairing of an
NFC token or a Bluetooth device might use key agreement protocols upon
first use.</p>
</div>
<div class="section" id="secure-boot">
-<h3>Secure Boot</h3>
+<h3>2.6.5. Secure Boot</h3>
<p>The API provides primitives for use during firmware integrity and authenticity
validation, during a secure or trusted boot process.</p>
</div>
<div class="section" id="attestation">
-<h3>Attestation</h3>
+<h3>2.6.6. Attestation</h3>
<p>The API provides primitives used in attestation activities. Attestation is the
ability for a device to sign an array of bytes with a device private key and
return the result to the caller. There are several use cases; ranging from attestation
@@ -203,7 +204,7 @@
algorithms commonly used for attestation.</p>
</div>
<div class="section" id="factory-provisioning">
-<h3>Factory Provisioning</h3>
+<h3>2.6.7. Factory Provisioning</h3>
<p>Most IoT devices receive a unique identity during the factory provisioning
process, or once they have been deployed to the field. This API provides the APIs necessary for
populating a device with keys that represent that identity.</p>
@@ -216,44 +217,51 @@
</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="#">Design goals</a><ul>
-<li><a class="reference internal" href="#suitable-for-constrained-devices">Suitable for constrained devices</a></li>
-<li><a class="reference internal" href="#a-keystore-interface">A keystore interface</a></li>
-<li><a class="reference internal" href="#optional-isolation">Optional isolation</a></li>
-<li><a class="reference internal" href="#choice-of-algorithms">Choice of algorithms</a></li>
-<li><a class="reference internal" href="#ease-of-use">Ease of use</a></li>
-<li><a class="reference internal" href="#example-use-cases">Example use cases</a><ul>
-<li><a class="reference internal" href="#network-security-tls">Network Security (TLS)</a></li>
-<li><a class="reference internal" href="#secure-storage">Secure Storage</a></li>
-<li><a class="reference internal" href="#network-credentials">Network Credentials</a></li>
-<li><a class="reference internal" href="#device-pairing">Device Pairing</a></li>
-<li><a class="reference internal" href="#secure-boot">Secure Boot</a></li>
-<li><a class="reference internal" href="#attestation">Attestation</a></li>
-<li><a class="reference internal" href="#factory-provisioning">Factory Provisioning</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <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><a href="../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="intro.html" title="previous chapter">Introduction</a></li>
- <li>Next: <a href="functionality.html" title="next chapter">Functionality overview</a></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../_sources/overview/goals.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">2. Design goals</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#suitable-for-constrained-devices">2.1. Suitable for constrained devices</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#a-keystore-interface">2.2. A keystore interface</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#optional-isolation">2.3. Optional isolation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#choice-of-algorithms">2.4. Choice of algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#ease-of-use">2.5. Ease of use</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#example-use-cases">2.6. Example use cases</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#network-security-tls">2.6.1. Network Security (TLS)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#secure-storage">2.6.2. Secure Storage</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#network-credentials">2.6.3. Network Credentials</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#device-pairing">2.6.4. Device Pairing</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#secure-boot">2.6.5. Secure Boot</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#attestation">2.6.6. Attestation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#factory-provisioning">2.6.7. Factory Provisioning</a></li>
+</ul>
+</li>
+</ul>
+</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"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -269,15 +277,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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/goals.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/overview/implementation.html b/docs/html/overview/implementation.html
index 53eb1a9..dd8e2f3 100644
--- a/docs/html/overview/implementation.html
+++ b/docs/html/overview/implementation.html
@@ -5,26 +5,27 @@
<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>
+ <title>6. Implementation considerations — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Usage considerations" href="usage.html" />
- <link rel="prev" title="Library conventions" href="conventions.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" />
@@ -40,11 +41,11 @@
<div class="body" role="main">
<div class="section" id="implementation-considerations">
-<span id="id1"></span><h1>Implementation considerations</h1>
+<span id="id1"></span><h1>6. Implementation considerations</h1>
<div class="section" id="implementation-specific-aspects-of-the-interface">
-<h2>Implementation-specific aspects of the interface</h2>
+<h2>6.1. Implementation-specific aspects of the interface</h2>
<div class="section" id="implementation-profile">
-<h3>Implementation profile</h3>
+<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
@@ -52,21 +53,21 @@
standard profiles.</p>
</div>
<div class="section" id="implementation-specific-types">
-<span id="implementation-defined-type"></span><h3>Implementation-specific types</h3>
+<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 <strong>psa/crypto.h</strong>,
+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>Implementation-specific macros</h3>
+<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>
@@ -90,7 +91,7 @@
<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>
+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>
@@ -119,27 +120,27 @@
</div>
</div>
<div class="section" id="porting-to-a-platform">
-<h2>Porting to a platform</h2>
+<h2>6.2. Porting to a platform</h2>
<div class="section" id="platform-assumptions">
-<h3>Platform assumptions</h3>
+<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>Platform-specific types</h3>
+<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 <strong>psa/crypto.h</strong> or by a header
+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 <strong>stdint.h</strong>.</dd>
+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>Cryptographic hardware support</h3>
+<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
@@ -147,9 +148,9 @@
</div>
</div>
<div class="section" id="security-requirements-and-recommendations">
-<h2>Security requirements and recommendations</h2>
+<h2>6.3. Security requirements and recommendations</h2>
<div class="section" id="error-detection">
-<h3>Error detection</h3>
+<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
@@ -158,7 +159,7 @@
parameters and fail-safe where possible.</p>
</div>
<div class="section" id="indirect-object-references">
-<h3>Indirect object references</h3>
+<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
@@ -185,7 +186,7 @@
identifier reuse vulnerability within an application.</p>
</div>
<div class="section" id="memory-cleanup">
-<span id="id2"></span><h3>Memory cleanup</h3>
+<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,
@@ -197,9 +198,9 @@
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>
+<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="functionality.html#volatile-keys"><span class="std std-ref">volatile key</span></a> to a
+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
@@ -208,8 +209,8 @@
<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
+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>
@@ -226,7 +227,7 @@
<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>
+<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
@@ -244,7 +245,7 @@
zeroing them out.</p>
</div>
<div class="section" id="attack-resistance">
-<h3>Attack resistance</h3>
+<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
@@ -258,9 +259,9 @@
</div>
</div>
<div class="section" id="other-implementation-considerations">
-<h2>Other implementation considerations</h2>
+<h2>6.4. Other implementation considerations</h2>
<div class="section" id="philosophy-of-resource-management">
-<h3>Philosophy of resource management</h3>
+<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>
@@ -286,54 +287,61 @@
</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>
+ <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><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>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></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>
+<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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -349,15 +357,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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>
diff --git a/docs/html/overview/intro.html b/docs/html/overview/intro.html
index dd5a664..e7e6c14 100644
--- a/docs/html/overview/intro.html
+++ b/docs/html/overview/intro.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Introduction — PSA Crypto API 1.0.0 documentation</title>
+ <title>1. Introduction — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Design goals" href="goals.html" />
- <link rel="prev" title="PSA Cryptography API 1.0" href="../index.html" />
+ <link rel="next" title="2. Design goals" href="goals.html" />
+ <link rel="prev" title="About this document" href="../about.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,7 +41,7 @@
<div class="body" role="main">
<div class="section" id="introduction">
-<h1>Introduction</h1>
+<h1>1. Introduction</h1>
<p>Arm’s Platform Security Architecture (PSA) is a holistic set of threat models,
security analyses, hardware and firmware architecture specifications, an
open source firmware reference implementation, and an independent evaluation
@@ -48,8 +49,8 @@
industry best practice, that allows security to be consistently designed in, at
both a hardware and firmware level.</p>
<p>The PSA Cryptographic API (Crypto API) described in this document is an
-important PSA component that provides an interface to cryptographic operations
-on resource-constrained devices. The interface is user-friendly, while still
+important PSA component that provides a portable interface to cryptographic operations
+on a wide range of hardware. The interface is user-friendly, while still
providing access to the low-level primitives used in modern cryptography. It
does not require that the user has access to the key material. Instead, it uses
opaque key identifiers.</p>
@@ -78,22 +79,34 @@
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
- <div class="sphinxsidebarwrapper"><div class="relations">
-<h3>Related Topics</h3>
+ <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><a href="../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="../index.html" title="previous chapter">PSA Cryptography API 1.0</a></li>
- <li>Next: <a href="goals.html" title="next chapter">Design goals</a></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../_sources/overview/intro.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1 current"><a class="current reference internal" href="#">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"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../appendix/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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -109,15 +122,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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/intro.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/overview/sample-arch.html b/docs/html/overview/sample-arch.html
index 855382d..679aec7 100644
--- a/docs/html/overview/sample-arch.html
+++ b/docs/html/overview/sample-arch.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Sample architectures — PSA Crypto API 1.0.0 documentation</title>
+ <title>4. Sample architectures — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Library conventions" href="conventions.html" />
- <link rel="prev" title="Functionality overview" href="functionality.html" />
+ <link rel="next" title="5. Library conventions" href="conventions.html" />
+ <link rel="prev" title="3. Functionality overview" href="functionality.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,12 +41,12 @@
<div class="body" role="main">
<div class="section" id="sample-architectures">
-<span id="architectures"></span><h1>Sample architectures</h1>
+<span id="architectures"></span><h1>4. Sample architectures</h1>
<p>This section describes some example architectures that can be used for
implementations of the interface described in this specification. This list is
not exhaustive and the section is entirely non-normative.</p>
<div class="section" id="single-partition-architecture">
-<h2>Single-partition architecture</h2>
+<h2>4.1. Single-partition architecture</h2>
<p>In the single-partition architecture, there is no security boundary inside the system. The
application code can access all the system memory, including the memory used by
the cryptographic services described in this specification. Thus, the
@@ -65,7 +66,7 @@
high-security partition with other platform security services.</p>
</div>
<div class="section" id="cryptographic-token-and-single-application-processor">
-<span id="isolated-cryptoprocessor"></span><h2>Cryptographic token and single-application processor</h2>
+<span id="isolated-cryptoprocessor"></span><h2>4.2. Cryptographic token and single-application processor</h2>
<p>This system is composed of two partitions: one is a cryptoprocessor and the
other partition runs an application. There is a security boundary between the
two partitions, so that the application cannot access the cryptoprocessor,
@@ -84,8 +85,8 @@
cryptoprocessor. Non-volatile keys are stored inside the cryptoprocessor.</p>
</div>
<div class="section" id="cryptoprocessor-with-no-key-storage">
-<h2>Cryptoprocessor with no key storage</h2>
-<p>As in the <em><a class="reference internal" href="#isolated-cryptoprocessor"><span class="std std-ref">Cryptographic token and single-application processor</span></a></em> architecture, this system
+<h2>4.3. Cryptoprocessor with no key storage</h2>
+<p>As in the <a class="reference internal" href="#isolated-cryptoprocessor"><span class="secref">Cryptographic token and single-application processor</span></a> architecture, this system
is also composed of two partitions separated by a security boundary and also
provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">cryptoprocessor isolation</span></a>.
However, unlike the previous architecture, in this system, the cryptoprocessor
@@ -106,7 +107,7 @@
</ul>
</div>
<div class="section" id="multi-client-cryptoprocessor">
-<h2>Multi-client cryptoprocessor</h2>
+<h2>4.4. Multi-client cryptoprocessor</h2>
<p>This is an expanded variant of the <a class="reference internal" href="#isolated-cryptoprocessor"><span class="std std-ref">cryptographic token plus application
architecture</span></a>. In this
variant, the cryptoprocessor serves multiple applications that are mutually
@@ -118,7 +119,7 @@
another client.</p>
</div>
<div class="section" id="multi-cryptoprocessor-architecture">
-<h2>Multi-cryptoprocessor architecture</h2>
+<h2>4.5. Multi-cryptoprocessor architecture</h2>
<p>This system includes multiple cryptoprocessors. There are several reasons to
have multiple cryptoprocessors:</p>
<ul class="simple">
@@ -151,34 +152,41 @@
</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="#">Sample architectures</a><ul>
-<li><a class="reference internal" href="#single-partition-architecture">Single-partition architecture</a></li>
-<li><a class="reference internal" href="#cryptographic-token-and-single-application-processor">Cryptographic token and single-application processor</a></li>
-<li><a class="reference internal" href="#cryptoprocessor-with-no-key-storage">Cryptoprocessor with no key storage</a></li>
-<li><a class="reference internal" href="#multi-client-cryptoprocessor">Multi-client cryptoprocessor</a></li>
-<li><a class="reference internal" href="#multi-cryptoprocessor-architecture">Multi-cryptoprocessor architecture</a></li>
+ <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 current"><a class="current reference internal" href="#">4. Sample architectures</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#single-partition-architecture">4.1. Single-partition architecture</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#cryptographic-token-and-single-application-processor">4.2. Cryptographic token and single-application processor</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#cryptoprocessor-with-no-key-storage">4.3. Cryptoprocessor with no key storage</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#multi-client-cryptoprocessor">4.4. Multi-client cryptoprocessor</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#multi-cryptoprocessor-architecture">4.5. Multi-cryptoprocessor architecture</a></li>
</ul>
</li>
+<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
</ul>
-<div class="relations">
-<h3>Related Topics</h3>
<ul>
- <li><a href="../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="functionality.html" title="previous chapter">Functionality overview</a></li>
- <li>Next: <a href="conventions.html" title="next chapter">Library conventions</a></li>
- </ul></li>
+<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>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../_sources/overview/sample-arch.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<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">
@@ -194,15 +202,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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/sample-arch.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/overview/usage.html b/docs/html/overview/usage.html
index 306bcee..ab13482 100644
--- a/docs/html/overview/usage.html
+++ b/docs/html/overview/usage.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Usage considerations — PSA Crypto API 1.0.0 documentation</title>
+ <title>7. Usage considerations — 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">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ 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="Library management reference" href="../api/library/index.html" />
- <link rel="prev" title="Implementation considerations" href="implementation.html" />
+ <link rel="next" title="8. Library management reference" href="../api/library/index.html" />
+ <link rel="prev" title="6. Implementation considerations" href="implementation.html" />
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
@@ -40,11 +41,11 @@
<div class="body" role="main">
<div class="section" id="usage-considerations">
-<span id="id1"></span><h1>Usage considerations</h1>
+<span id="id1"></span><h1>7. Usage considerations</h1>
<div class="section" id="security-recommendations">
-<h2>Security recommendations</h2>
+<h2>7.1. Security recommendations</h2>
<div class="section" id="always-check-for-errors">
-<h3>Always check for errors</h3>
+<h3>7.1.1. Always check for errors</h3>
<p>Most functions in this API can return errors. All functions that can fail have
the return 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>. A few functions cannot fail, and thus, return
<code class="docutils literal"><span class="pre">void</span></code> or some other type.</p>
@@ -71,7 +72,7 @@
</ul>
</div>
<div class="section" id="shared-memory-and-concurrency">
-<h3>Shared memory and concurrency</h3>
+<h3>7.1.2. Shared memory and concurrency</h3>
<p>Some environments allow applications to be multithreaded, while others do not.
In some environments, applications can share memory with a different security
context. In environments with multithreaded applications or shared memory,
@@ -86,10 +87,10 @@
section.</p>
<p>If an application shares memory with another security context, it can pass
shared memory blocks as input buffers or output buffers, but not as non-buffer
-parameters. For more details, refer to the <em><a class="reference internal" href="conventions.html#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+parameters. For more details, refer to the <a class="reference internal" href="conventions.html#stability-of-parameters"><span class="secref">Stability of parameters</span></a> section.</p>
</div>
<div class="section" id="cleaning-up-after-use">
-<h3>Cleaning up after use</h3>
+<h3>7.1.3. Cleaning up after use</h3>
<p>To minimize impact if the system is compromised, it is recommended that
applications wipe all sensitive data from memory when it is no longer used. That
way, only data that is currently in use can be leaked, and past data is not
@@ -109,35 +110,42 @@
</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="#">Usage considerations</a><ul>
-<li><a class="reference internal" href="#security-recommendations">Security recommendations</a><ul>
-<li><a class="reference internal" href="#always-check-for-errors">Always check for errors</a></li>
-<li><a class="reference internal" href="#shared-memory-and-concurrency">Shared memory and concurrency</a></li>
-<li><a class="reference internal" href="#cleaning-up-after-use">Cleaning up after use</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <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><a href="../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="implementation.html" title="previous chapter">Implementation considerations</a></li>
- <li>Next: <a href="../api/library/index.html" title="next chapter">Library management reference</a></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../_sources/overview/usage.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<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"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">7. Usage considerations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="#security-recommendations">7.1. Security recommendations</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#always-check-for-errors">7.1.1. Always check for errors</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#shared-memory-and-concurrency">7.1.2. Shared memory and concurrency</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#cleaning-up-after-use">7.1.3. Cleaning up after use</a></li>
+</ul>
+</li>
+</ul>
+</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>Quick search</h3>
<form class="search" action="../search.html" method="get">
@@ -153,15 +161,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-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/usage.rst.txt"
- rel="nofollow">Page source</a>
</div>