Rebuild PSA API spec with Sphinx 2.1.2
Generated according to the instructions in update_psa_crypto_api.sh,
using a modified docker image with Sphinx updated to 2.1.2, and the tag
psa-crypto-api-1.0.1.
This fixes user-visible warnings in html/api/keys/management.html.
Signed-off-by: Bence Szépkúti <bence.szepkuti@arm.com>
diff --git a/docs/html/overview/conventions.html b/docs/html/overview/conventions.html
index 0d7a82f..76beba2 100644
--- a/docs/html/overview/conventions.html
+++ b/docs/html/overview/conventions.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="library-conventions">
@@ -46,12 +39,12 @@
<h2>5.1. Error handling</h2>
<div class="section" id="return-status">
<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
+<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 notranslate"><span class="pre">psa_status_t</span></code></a>. This
+is an enumeration of integer values, with <code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_SUCCESS</span></code></a>) indicating
successful operation and other values indicating errors. The exceptions are
functions which only access objects that are intended to be implemented as
simple data structures. Such functions cannot fail and either return
-<code class="docutils literal"><span class="pre">void</span></code> or a data value.</p>
+<code class="docutils literal notranslate"><span class="pre">void</span></code> or a data value.</p>
<p>Unless specified otherwise, if multiple error conditions apply, an
implementation is free to return any of the applicable error codes. The choice
of error code is considered an implementation quality issue. Different
@@ -67,46 +60,46 @@
<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
-action has been carried out.</li>
-<li>When a function returns the status <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>, the requested action has
-been carried out.</li>
-<li>When a function returns another status of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>, no action
+<li><p>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 notranslate"><span class="pre">psa_status_t</span></code></a>, the requested
+action has been carried out.</p></li>
+<li><p>When a function returns the status <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a>, the requested action has
+been carried out.</p></li>
+<li><p>When a function returns another status of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_status_t</span></code></a>, no action
has been carried out. The content of the output parameters is undefined, but
-otherwise the state of the system has not changed, except as described below.</li>
+otherwise the state of the system has not changed, except as described below.</p></li>
</ul>
<p>In general, functions that modify the system state, for example, creating or
destroying a key, must leave the system state unchanged if they return an error
code. There are specific conditions that can result in different behavior:</p>
<ul class="simple">
-<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> indicates that a parameter was not in a
+<li><p>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> indicates that a parameter was not in a
valid state for the requested action. This parameter might have been modified
by the call and is now in an undefined state. The only valid action on an
object in an undefined state is to abort it with the appropriate
-<code class="docutils literal"><span class="pre">psa_abort_xxx()</span></code> function.</li>
-<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a> indicates that a key
+<code class="docutils literal notranslate"><span class="pre">psa_abort_xxx()</span></code> function.</p></li>
+<li><p>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a> indicates that a key
derivation object has reached its maximum capacity. The key derivation
operation might have been modified by the call. Any further attempt to obtain
output from the key derivation operation will return
-<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a>.</li>
-<li>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a> indicates that the
+<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a>.</p></li>
+<li><p>The status <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a> indicates that the
communication between the application and the cryptoprocessor has broken
down. In this case, the cryptoprocessor must either finish the requested
action successfully, or interrupt the action and roll back the system to its
original state. Because it is often impossible to report the outcome to the
application after a communication failure, this specification does not
provide a way for the application to determine whether the action was
-successful.</li>
-<li>The statuses <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a>
-and <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a> might indicate data corruption in the
+successful.</p></li>
+<li><p>The statuses <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a>, <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a>
+and <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a> might indicate data corruption in the
system state. When a function returns one of these statuses, the system state
might have changed from its previous state before the function call, even
-though the function call failed.</li>
-<li>Some system states cannot be rolled back, for example, the internal state of
-the random number generator or the content of access logs.</li>
+though the function call failed.</p></li>
+<li><p>Some system states cannot be rolled back, for example, the internal state of
+the random number generator or the content of access logs.</p></li>
</ul>
<p>Unless otherwise documented, the content of output parameters is not defined
-when a function returns a status other than <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>. It is recommended
+when a function returns a status other than <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a>. It is recommended
that implementations set output parameters to safe defaults to avoid leaking
confidential data and limit risk, in case an application does not properly
handle all errors.</p>
@@ -119,11 +112,11 @@
<p>Unless explicitly stated in the documentation of a function, all pointers must
be valid pointers to an object of the specified type.</p>
<p>A parameter is considered a <strong>buffer</strong> if it points to an array of bytes. A
-buffer parameter always has the type <code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*</span></code> or <code class="docutils literal"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*</span></code>, and
+buffer parameter always has the type <code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*</span></code> or <code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*</span></code>, and
always has an associated parameter indicating the size of the array. Note that a
-parameter of type <code class="docutils literal"><span class="pre">void</span> <span class="pre">*</span></code> is never considered a buffer.</p>
+parameter of type <code class="docutils literal notranslate"><span class="pre">void</span> <span class="pre">*</span></code> is never considered a buffer.</p>
<p>All parameters of pointer type must be valid non-null pointers, unless the
-pointer is to a buffer of length <code class="docutils literal"><span class="pre">0</span></code> or the function’s documentation
+pointer is to a buffer of length <code class="docutils literal notranslate"><span class="pre">0</span></code> or the function’s documentation
explicitly describes the behavior when the pointer is null. Passing a null
pointer as a function parameter in other cases is expected to abort the caller
on implementations where this is the normal behavior for a null pointer
@@ -137,33 +130,33 @@
<div class="section" id="input-buffer-sizes">
<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>
-<dd>Pointer to the first byte of the data. The pointer
-can be invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
-<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt>
-<dd>Size of the buffer in bytes.</dd>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">const</span> <span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt><dd><p>Pointer to the first byte of the data. The pointer
+can be invalid if the buffer size is <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt><dd><p>Size of the buffer in bytes.</p>
+</dd>
</dl>
<p>The interface never uses input-output buffers.</p>
</div>
<div class="section" id="output-buffer-sizes">
<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>
-<dd>Pointer to the first byte of the data. The pointer can be
-invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
-<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_size</span></code></dt>
-<dd>The size of the buffer in bytes.</dd>
-<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code></dt>
-<dd>On successful return, contains the length of the
-output in bytes.</dd>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt><dd><p>Pointer to the first byte of the data. The pointer can be
+invalid if the buffer size is <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_size</span></code></dt><dd><p>The size of the buffer in bytes.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">*foo_length</span></code></dt><dd><p>On successful return, contains the length of the
+output in bytes.</p>
+</dd>
</dl>
-<p>The content of the data buffer and of <code class="docutils literal"><span class="pre">*foo_length</span></code> on errors is unspecified,
+<p>The content of the data buffer and of <code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> on errors is unspecified,
unless explicitly mentioned in the function description. They might be unmodified
or set to a safe default. On successful completion, the content of the buffer
-between the offsets <code class="docutils literal"><span class="pre">*foo_length</span></code> and <code class="docutils literal"><span class="pre">foo_size</span></code> is also unspecified.</p>
-<p>Functions return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a> if the buffer size is
+between the offsets <code class="docutils literal notranslate"><span class="pre">*foo_length</span></code> and <code class="docutils literal notranslate"><span class="pre">foo_size</span></code> is also unspecified.</p>
+<p>Functions return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a> if the buffer size is
insufficient to carry out the requested operation. The interface defines macros
to calculate a sufficient buffer size for each operation that has an output
buffer. These macros return compile-time constants if their arguments are
@@ -172,13 +165,13 @@
macro.</p>
<p>Some functions always return exactly as much data as the size of the output
buffer. In this case, the parameter convention changes to:</p>
-<dl class="docutils">
-<dt><code class="docutils literal"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt>
-<dd>Pointer to the first byte of the output. The pointer can be
-invalid if the buffer size is <code class="docutils literal"><span class="pre">0</span></code>.</dd>
-<dt><code class="docutils literal"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt>
-<dd>The number of bytes to return in <code class="docutils literal"><span class="pre">foo</span></code> if
-successful.</dd>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">uint8_t</span> <span class="pre">*foo</span></code></dt><dd><p>Pointer to the first byte of the output. The pointer can be
+invalid if the buffer size is <code class="docutils literal notranslate"><span class="pre">0</span></code>.</p>
+</dd>
+<dt><code class="docutils literal notranslate"><span class="pre">size_t</span> <span class="pre">foo_length</span></code></dt><dd><p>The number of bytes to return in <code class="docutils literal notranslate"><span class="pre">foo</span></code> if
+successful.</p>
+</dd>
</dl>
</div>
<div class="section" id="overlap-between-parameters">
@@ -233,17 +226,17 @@
<div class="section" id="key-types-and-algorithms">
<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/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>
+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 notranslate"><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 notranslate"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p>
<p>There is some overlap in the information conveyed by key types and algorithms.
Both types contain enough information, so that the meaning of an algorithm type
value does not depend on what type of key it is used with, and vice versa.
However, the particular instance of an algorithm might depend on the key type. For
-example, the algorithm <a class="reference internal" href="../api/ops/aead.html#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GCM</span></code></a> can be instantiated as any AEAD algorithm
+example, the algorithm <a class="reference internal" href="../api/ops/aead.html#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_GCM</span></code></a> can be instantiated as any AEAD algorithm
using the GCM mode over a block cipher. The underlying block cipher is
determined by the key type.</p>
<p>Key types do not encode the key size. For example, AES-128, AES-192 and AES-256
-share a key type <a class="reference internal" href="../api/keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>.</p>
+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 notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>.</p>
<div class="section" id="structure-of-key-and-algorithm-types">
<h3>5.3.1. Structure of key and algorithm types</h3>
<p>Both types use a partial bitmask structure, which allows the analysis and
@@ -252,18 +245,18 @@
only care about the encoding for code size optimization.</p>
<p>The encodings follows a few conventions:</p>
<ul class="simple">
-<li>The highest bit is a vendor flag. Current and future versions of this
+<li><p>The highest bit is a vendor flag. Current and future versions of this
specification will only define values where this bit is clear.
Implementations that wish to define additional implementation-specific values
must use values where this bit is set, to avoid conflicts with future
-versions of this specification.</li>
-<li>The next few highest bits indicate the corresponding algorithm category:
-hash, MAC, symmetric cipher, asymmetric encryption, and so on.</li>
-<li>The following bits identify a family of algorithms in a category-dependent
-manner.</li>
-<li>In some categories and algorithm families, the lowest-order bits indicate a
+versions of this specification.</p></li>
+<li><p>The next few highest bits indicate the corresponding algorithm category:
+hash, MAC, symmetric cipher, asymmetric encryption, and so on.</p></li>
+<li><p>The following bits identify a family of algorithms in a category-dependent
+manner.</p></li>
+<li><p>In some categories and algorithm families, the lowest-order bits indicate a
variant in a systematic way. For example, algorithm families that are
-parametrized around a hash function encode the hash in the 8 lowest bits.</li>
+parametrized around a hash function encode the hash in the 8 lowest bits.</p></li>
</ul>
</div>
</div>
@@ -275,17 +268,18 @@
<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
+<li><p>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>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>
+permitted.</p></li>
+<li><p>A call to destroy a key must not overlap with a concurrent call to any of
+the following functions:</p>
+<ul>
+<li><p>Any call where the same key identifier is a parameter to the call.</p></li>
+<li><p>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.</p></li>
</ul>
</li>
-<li>Concurrent calls must not use the same operation object.</li>
+<li><p>Concurrent calls must not use the same operation object.</p></li>
</ul>
<p>If any of these constraints are violated, the behavior is undefined.</p>
<p>If the application modifies an input parameter while a function call is in
@@ -296,6 +290,7 @@
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -348,13 +343,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -365,8 +360,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/functionality.html b/docs/html/overview/functionality.html
index daaba7a..e8c7462 100644
--- a/docs/html/overview/functionality.html
+++ b/docs/html/overview/functionality.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="functionality-overview">
@@ -48,10 +41,10 @@
<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>
+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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>.</p>
<div class="section" id="library-management">
<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
+<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 notranslate"><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">
@@ -62,28 +55,28 @@
obtain the key material. Non-extractable keys are bound to the device, can be
rate-limited and can have their usage restricted by policies.</p>
<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
+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 notranslate"><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>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>
+<li><p>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.</p></li>
+<li><p>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.</p></li>
+<li><p>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.</p></li>
+<li><p>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.</p></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>
+<li><p><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 notranslate"><span class="pre">psa_import_key()</span></code></a></p></li>
+<li><p><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 notranslate"><span class="pre">psa_generate_key()</span></code></a></p></li>
+<li><p><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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a></p></li>
+<li><p><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 notranslate"><span class="pre">psa_copy_key()</span></code></a></p></li>
</ul>
<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
+<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 notranslate"><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>
@@ -101,7 +94,7 @@
<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>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 notranslate"><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>
@@ -113,19 +106,19 @@
<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
+<li><p><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 notranslate"><span class="pre">psa_import_key()</span></code></a>. The exceptions are implementations that only give access
to a key or keys that are provisioned by proprietary means, and do not allow
-the main application to use its own cryptographic material.</li>
-<li><a class="reference internal" href="../api/keys/attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_get_key_attributes()</span></code></a> and the <code class="docutils literal"><span class="pre">psa_get_key_xxx()</span></code> accessor functions.
+the main application to use its own cryptographic material.</p></li>
+<li><p><a class="reference internal" href="../api/keys/attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_get_key_attributes()</span></code></a> and the <code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx()</span></code> accessor functions.
They are easy to implement, and it is difficult to write applications and to
-diagnose issues without being able to check the metadata.</li>
-<li><a class="reference internal" href="../api/keys/management.html#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>. This function is usually provided if the
+diagnose issues without being able to check the metadata.</p></li>
+<li><p><a class="reference internal" href="../api/keys/management.html#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_export_public_key()</span></code></a>. This function is usually provided if the
implementation supports any asymmetric algorithm, since public-key
cryptography often requires the delivery of a public key that is associated
-with a protected private key.</li>
-<li><a class="reference internal" href="../api/keys/management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a>. However, highly constrained implementations that are
+with a protected private key.</p></li>
+<li><p><a class="reference internal" href="../api/keys/management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_export_key()</span></code></a>. However, highly constrained implementations that are
designed to work only with short-term keys, or only with long-term
-non-extractable keys, do not need to provide this function.</li>
+non-extractable keys, do not need to provide this function.</p></li>
</ul>
</div>
</div>
@@ -134,16 +127,16 @@
<p>This specification defines interfaces for the following types of symmetric
cryptographic operation:</p>
<ul class="simple">
-<li>Message digests, commonly known as hash functions.</li>
-<li>Message authentication codes (MAC).</li>
-<li>Symmetric ciphers.</li>
-<li>Authenticated encryption with associated data (AEAD).</li>
+<li><p>Message digests, commonly known as hash functions.</p></li>
+<li><p>Message authentication codes (MAC).</p></li>
+<li><p>Symmetric ciphers.</p></li>
+<li><p>Authenticated encryption with associated data (AEAD).</p></li>
</ul>
<p>For each type of symmetric cryptographic operation, the API includes:</p>
<ul class="simple">
-<li>A pair of <em>single-part</em> functions. For example, compute and verify, or
-encrypt and decrypt.</li>
-<li>A series of functions that permit <em>multi-part operations</em>.</li>
+<li><p>A pair of <em>single-part</em> functions. For example, compute and verify, or
+encrypt and decrypt.</p></li>
+<li><p>A series of functions that permit <em>multi-part operations</em>.</p></li>
</ul>
<div class="section" id="single-part-functions">
<h3>3.3.1. Single-part Functions</h3>
@@ -162,49 +155,48 @@
fragments instead of all at once. For example, the following situations require
the use of a multi-part operation:</p>
<ul class="simple">
-<li>Processing messages that cannot be assembled in memory.</li>
-<li>Using a deterministic IV for unauthenticated encryption.</li>
-<li>Providing the IV separately for unauthenticated encryption or decryption.</li>
-<li>Separating the AEAD authentication tag from the cipher text.</li>
+<li><p>Processing messages that cannot be assembled in memory.</p></li>
+<li><p>Using a deterministic IV for unauthenticated encryption.</p></li>
+<li><p>Providing the IV separately for unauthenticated encryption or decryption.</p></li>
+<li><p>Separating the AEAD authentication tag from the cipher text.</p></li>
</ul>
<p>Each multi-part operation defines a specific object type to maintain the state
of the operation. These types are implementation-defined. All multi-part
operations follow the same pattern of use:</p>
<ol class="arabic">
-<li><p class="first"><strong>Allocate:</strong> Allocate memory for an operation object of the appropriate
-type. The application can use any allocation strategy: stack, heap, static, etc.</p>
-</li>
-<li><p class="first"><strong>Initialize:</strong> Initialize or assign the operation object by one of the
+<li><p><strong>Allocate:</strong> Allocate memory for an operation object of the appropriate
+type. The application can use any allocation strategy: stack, heap, static, etc.</p></li>
+<li><p><strong>Initialize:</strong> Initialize or assign the operation object by one of the
following methods:</p>
<blockquote>
<div><ul class="simple">
-<li>Set it to logical zero. This is automatic for static and global
+<li><p>Set it to logical zero. This is automatic for static and global
variables. Explicit initialization must use the associated
-<code class="docutils literal"><span class="pre">PSA_xxx_INIT</span></code> macro as the type is implementation-defined.</li>
-<li>Set it to all-bits zero. This is automatic if the object was
-allocated with <code class="docutils literal"><span class="pre">calloc()</span></code>.</li>
-<li>Assign the value of the associated macro <code class="docutils literal"><span class="pre">PSA_xxx_INIT</span></code>.</li>
-<li>Assign the result of calling the associated function
-<code class="docutils literal"><span class="pre">psa_xxx_init()</span></code>.</li>
+<code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code> macro as the type is implementation-defined.</p></li>
+<li><p>Set it to all-bits zero. This is automatic if the object was
+allocated with <code class="docutils literal notranslate"><span class="pre">calloc()</span></code>.</p></li>
+<li><p>Assign the value of the associated macro <code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code>.</p></li>
+<li><p>Assign the result of calling the associated function
+<code class="docutils literal notranslate"><span class="pre">psa_xxx_init()</span></code>.</p></li>
</ul>
</div></blockquote>
<p>The resulting object is now <em>inactive</em>.</p>
<p>It is an error to initialize an operation object that is in <em>active</em> or
<em>error</em> states. This can leak memory or other resources.</p>
</li>
-<li><p class="first"><strong>Setup:</strong> Start a new multi-part operation on an <em>inactive</em> operation
+<li><p><strong>Setup:</strong> Start a new multi-part operation on an <em>inactive</em> operation
object. Each operation object will define one or more setup functions to
start a specific operation.</p>
<p>On success, a setup function will put an operation object into an <em>active</em>
state. On failure, the operation object will remain <em>inactive</em>.</p>
</li>
-<li><p class="first"><strong>Update:</strong> Update an <em>active</em> operation object. The update function can
+<li><p><strong>Update:</strong> Update an <em>active</em> operation object. The update function can
provide additional parameters, supply data for processing or generate
outputs.</p>
<p>On success, the operation object remains <em>active</em>. On failure, the
operation object will enter an <em>error</em> state.</p>
</li>
-<li><p class="first"><strong>Finish:</strong> To end the operation, call the applicable finishing function.
+<li><p><strong>Finish:</strong> To end the operation, call the applicable finishing function.
This will take any final inputs, produce any final outputs, and then
release any resources associated with the operation.</p>
<p>On success, the operation object returns to the <em>inactive</em> state. On
@@ -212,21 +204,21 @@
</li>
</ol>
<p>An operation can be aborted at any stage during its use by calling the
-associated <code class="docutils literal"><span class="pre">psa_xxx_abort()</span></code> function. This will release any resources
+associated <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort()</span></code> function. This will release any resources
associated with the operation and return the operation object to the <em>inactive</em>
state.</p>
<p>Any error that occurs to an operation while it is in an <em>active</em> state will
result in the operation entering an <em>error</em> state. The application must call the
-associated <code class="docutils literal"><span class="pre">psa_xxx_abort()</span></code> function to release the operation resources and
+associated <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort()</span></code> function to release the operation resources and
return the object to the <em>inactive</em> state.</p>
<p>Once an operation object is returned to the <em>inactive</em> state, it can be reused
by calling one of the applicable setup functions again.</p>
<p>If a multi-part operation object is not initialized before use, the behavior is
undefined.</p>
<p>If a multi-part operation function determines that the operation object is not in
-any valid state, it can return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a>.</p>
+any valid state, it can return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a>.</p>
<p>If a multi-part operation function is called with an operation object in the
-wrong state, the function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> and the operation
+wrong state, the function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> and the operation
object will enter the <em>error</em> state.</p>
<p>It is safe to move a multi-part operation object to a different memory location,
for example, using a bitwise copy, and then to use the object in the new
@@ -235,11 +227,11 @@
managed by a garbage collector. However, this does not permit the following
behaviors:</p>
<ul class="simple">
-<li>Moving the object while a function is being called on the object. This is
-not safe. See also <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>.</li>
-<li>Working with both the original and the copied operation objects. This
+<li><p>Moving the object while a function is being called on the object. This is
+not safe. See also <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>.</p></li>
+<li><p>Working with both the original and the copied operation objects. This
requires cloning the operation, which is only available for hash operations
-using <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_clone()</span></code></a>.</li>
+using <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_clone()</span></code></a>.</p></li>
</ul>
<p>Each type of multi-part operation can have multiple <em>active</em> states.
Documentation for the specific operation describes the configuration and update
@@ -249,60 +241,62 @@
<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>
-<li><a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compare()</span></code></a> to compare the hash of a message with a reference value.</li>
+<li><p><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 notranslate"><span class="pre">psa_hash_compute()</span></code></a> to calculate the hash of a message.</p></li>
+<li><p><a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_compare()</span></code></a> to compare the hash of a message with a reference value.</p></li>
</ul>
-<p>The <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
+<p>The <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
allows messages to be processed in fragments:</p>
<ol class="arabic simple">
-<li>Initialize the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> object to zero, or by assigning the
-value of the associated macro <a class="reference internal" href="../api/ops/hashes.html#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</li>
-<li>Call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_setup()</span></code></a> to specify the required hash algorithm, call
-<a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_clone()</span></code></a> to duplicate the state of <em>active</em> <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a>
-object, or call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_resume()</span></code></a> to restart a hash operation with the
-output from a previously suspended hash operation.</li>
-<li>Call the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_update()</span></code></a> function on successive chunks of the message.</li>
-<li>At the end of the message, call the required finishing function:<ul>
-<li>To suspend the hash operation and extract a hash suspend state,
-call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_suspend()</span></code></a>. The output state can subsequently be used
-to resume the hash operation.</li>
-<li>To calculate the digest of a message, call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_finish()</span></code></a>.</li>
-<li>To verify the digest of a message against a reference value, call
-<a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_verify()</span></code></a>.</li>
+<li><p>Initialize the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a> object to zero, or by assigning the
+value of the associated macro <a class="reference internal" href="../api/ops/hashes.html#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_setup()</span></code></a> to specify the required hash algorithm, call
+<a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_clone()</span></code></a> to duplicate the state of <em>active</em> <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_hash_operation_t</span></code></a>
+object, or call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_resume()</span></code></a> to restart a hash operation with the
+output from a previously suspended hash operation.</p></li>
+<li><p>Call the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_update()</span></code></a> function on successive chunks of the message.</p></li>
+<li><p>At the end of the message, call the required finishing function:</p>
+<ul class="simple">
+<li><p>To suspend the hash operation and extract a hash suspend state,
+call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_suspend()</span></code></a>. The output state can subsequently be used
+to resume the hash operation.</p></li>
+<li><p>To calculate the digest of a message, call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_finish()</span></code></a>.</p></li>
+<li><p>To verify the digest of a message against a reference value, call
+<a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_hash_verify()</span></code></a>.</p></li>
</ul>
</li>
</ol>
-<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>
+<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 notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
</div>
<div class="section" id="message-authentication-codes-macs">
<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>
-<li><a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a> to compare the MAC of a message with a reference value.</li>
+<li><p><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 notranslate"><span class="pre">psa_mac_compute()</span></code></a> to calculate the MAC of a message.</p></li>
+<li><p><a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_verify()</span></code></a> to compare the MAC of a message with a reference value.</p></li>
</ul>
-<p>The <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
+<p>The <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_mac_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
allows messages to be processed in fragments:</p>
<ol class="arabic simple">
-<li>Initialize the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> object to zero, or by assigning the
-value of the associated macro <a class="reference internal" href="../api/ops/macs.html#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</li>
-<li>Call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> or <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> to specify the
-algorithm and key.</li>
-<li>Call the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a> function on successive chunks of the message.</li>
-<li>At the end of the message, call the required finishing function:<ul>
-<li>To calculate the MAC of the message, call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a>.</li>
-<li>To verify the MAC of the message against a reference value, call
-<a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a>.</li>
+<li><p>Initialize the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_mac_operation_t</span></code></a> object to zero, or by assigning the
+value of the associated macro <a class="reference internal" href="../api/ops/macs.html#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_sign_setup()</span></code></a> or <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_verify_setup()</span></code></a> to specify the
+algorithm and key.</p></li>
+<li><p>Call the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_update()</span></code></a> function on successive chunks of the message.</p></li>
+<li><p>At the end of the message, call the required finishing function:</p>
+<ul class="simple">
+<li><p>To calculate the MAC of the message, call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_sign_finish()</span></code></a>.</p></li>
+<li><p>To verify the MAC of the message against a reference value, call
+<a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_mac_verify_finish()</span></code></a>.</p></li>
</ul>
</li>
</ol>
-<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>
+<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 notranslate"><span class="pre">psa_mac_abort()</span></code></a>.</p>
</div>
<div class="section" id="encryption-and-decryption">
<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
+<p class="admonition-title">Note</p>
+<p>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
<a class="reference internal" href="#func-aead"><span class="secref">Authenticated encryption (AEAD)</span></a>.</p>
@@ -310,89 +304,92 @@
<p>The single-part functions for encrypting or decrypting a message using an
unauthenticated symmetric cipher are:</p>
<ul class="simple">
-<li><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> to encrypt a message using an unauthenticated symmetric
+<li><p><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_encrypt()</span></code></a> to encrypt a message using an unauthenticated symmetric
cipher. The encryption function generates a random IV. Use the multi-part API
to provide a deterministic IV: this is not secure in general, but
-can be secure in some conditions that depend on the algorithm.</li>
-<li><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a> to decrypt a message using an unauthenticated symmetric
-cipher.</li>
+can be secure in some conditions that depend on the algorithm.</p></li>
+<li><p><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_decrypt()</span></code></a> to decrypt a message using an unauthenticated symmetric
+cipher.</p></li>
</ul>
-<p>The <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> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
+<p>The <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 notranslate"><span class="pre">psa_cipher_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
permits alternative initialization parameters and allows messages to be
processed in fragments:</p>
<ol class="arabic simple">
-<li>Initialize the <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 by assigning the
-value of the associated macro <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> or <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> to specify the
-algorithm and key.</li>
-<li>Provide additional parameters:<ul>
-<li>When encrypting data, generate or set an initialization vector (IV),
+<li><p>Initialize the <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 notranslate"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero, or by assigning the
+value of the associated macro <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 notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>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 notranslate"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> to specify the
+algorithm and key.</p></li>
+<li><p>Provide additional parameters:</p>
+<ul class="simple">
+<li><p>When encrypting data, generate or set an initialization vector (IV),
nonce, or similar initial value such as an initial counter value. To
generate a random IV, which is recommended in most protocols, call
-<a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a>. To set the IV, call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>.</li>
-<li>When decrypting, set the IV or nonce. To set the IV, call
-<a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>.</li>
+<a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_generate_iv()</span></code></a>. To set the IV, call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a>.</p></li>
+<li><p>When decrypting, set the IV or nonce. To set the IV, call
+<a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a>.</p></li>
</ul>
</li>
-<li>Call the <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> function on successive chunks of the message.</li>
-<li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a> to complete the operation and return any final
-output.</li>
+<li><p>Call the <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_update()</span></code></a> function on successive chunks of the message.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_finish()</span></code></a> to complete the operation and return any final
+output.</p></li>
</ol>
-<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>
+<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 notranslate"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
</div>
<div class="section" id="authenticated-encryption-aead">
<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
-cipher.</li>
-<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>
+<li><p><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 notranslate"><span class="pre">psa_aead_encrypt()</span></code></a> to encrypt a message using an authenticated symmetric
+cipher.</p></li>
+<li><p><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 notranslate"><span class="pre">psa_aead_decrypt()</span></code></a> to decrypt a message using an authenticated symmetric
+cipher.</p></li>
</ul>
<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>
+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 notranslate"><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 notranslate"><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>
permits alternative initialization parameters and allows messages to be
processed in fragments:</p>
<ol class="arabic simple">
-<li>Initialize 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> object to zero, or by assigning the
-value of the associated macro <a class="reference internal" href="../api/ops/aead.html#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</li>
-<li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the
-algorithm and key.</li>
-<li>Provide additional parameters:<ul>
-<li>If the algorithm requires it, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the
-length of the non-encrypted and encrypted inputs to the operation.</li>
-<li>When encrypting, call either <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or
-<a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce.</li>
-<li>When decrypting, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to set the nonce.</li>
+<li><p>Initialize 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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a> object to zero, or by assigning the
+value of the associated macro <a class="reference internal" href="../api/ops/aead.html#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the
+algorithm and key.</p></li>
+<li><p>Provide additional parameters:</p>
+<ul class="simple">
+<li><p>If the algorithm requires it, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the
+length of the non-encrypted and encrypted inputs to the operation.</p></li>
+<li><p>When encrypting, call either <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> or
+<a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce.</p></li>
+<li><p>When decrypting, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a> to set the nonce.</p></li>
</ul>
</li>
-<li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> zero or more times with fragments of the
-non-encrypted additional data.</li>
-<li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> zero or more times with fragments of the plaintext
-or ciphertext to encrypt or decrypt.</li>
-<li>At the end of the message, call the required finishing function:<ul>
-<li>To complete an encryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> to compute
-and return authentication tag.</li>
-<li>To complete a decryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> to
-compute the authentication tag and verify it against a reference value.</li>
+<li><p>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> zero or more times with fragments of the
+non-encrypted additional data.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_update()</span></code></a> zero or more times with fragments of the plaintext
+or ciphertext to encrypt or decrypt.</p></li>
+<li><p>At the end of the message, call the required finishing function:</p>
+<ul class="simple">
+<li><p>To complete an encryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_finish()</span></code></a> to compute
+and return authentication tag.</p></li>
+<li><p>To complete a decryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_verify()</span></code></a> to
+compute the authentication tag and verify it against a reference value.</p></li>
</ul>
</li>
</ol>
-<p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p>
+<p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
<p>Having a multi-part interface to authenticated encryption raises specific issues.</p>
<p>Multi-part authenticated decryption produces partial results that are not
authenticated. Applications must not use or expose partial results of
-authenticated decryption until <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> has returned a success
+authenticated decryption until <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_verify()</span></code></a> has returned a success
status and must destroy all partial results without revealing them if
-<a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> returns a failure status. Revealing partial results, either directly or indirectly through the application’s behavior, can compromise the
+<a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_verify()</span></code></a> returns a failure status. Revealing partial results, either directly or indirectly through the application’s behavior, can compromise the
confidentiality of all inputs that are encrypted with the same key.</p>
<p>For encryption, some common algorithms cannot be processed in a streaming
fashion. For SIV mode, the whole plaintext must be known before the encryption
can start; the multi-part AEAD API is not meant to be usable with SIV mode. For
CCM mode, the length of the plaintext must be known before the encryption can
-start; the application can call the function <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to provide
+start; the application can call the function <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to provide
these lengths before providing input.</p>
</div>
<div class="section" id="key-derivation">
@@ -403,11 +400,11 @@
parameters, then they produce the same output.</p>
<p>A key derivation consists of two phases:</p>
<ol class="arabic simple">
-<li>Input collection. This is sometimes known as <em>extraction</em>: the operation
+<li><p>Input collection. This is sometimes known as <em>extraction</em>: the operation
“extracts” information from the inputs to generate a pseudorandom
-intermediate secret value.</li>
-<li>Output generation. This is sometimes known as <em>expansion</em>: the operation
-“expands” the intermediate secret value to the desired output length.</li>
+intermediate secret value.</p></li>
+<li><p>Output generation. This is sometimes known as <em>expansion</em>: the operation
+“expands” the intermediate secret value to the desired output length.</p></li>
</ol>
<p>The specification defines a <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
API for key derivation that allows for multiple key and non-key outputs to be
@@ -416,30 +413,30 @@
state of the key derivation is not visible to the caller, and if an output of
the derivation is a non-exportable key, then this key cannot be recovered
outside the isolation boundary.</p>
-<p>Applications use the <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> type to create key
+<p>Applications use the <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 notranslate"><span class="pre">psa_key_derivation_operation_t</span></code></a> type to create key
derivation operations. The operation object is used as follows:</p>
<ol class="arabic simple">
-<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> to select a key derivation algorithm.</li>
-<li>Call the functions <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> and
-<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a>, or <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> to
+<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>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 notranslate"><span class="pre">psa_key_derivation_setup()</span></code></a> to select a key derivation algorithm.</p></li>
+<li><p>Call the functions <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> and
+<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_input_key()</span></code></a>, or <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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> to
provide the inputs to the key derivation algorithm. Many key derivation
-algorithms take multiple inputs; the <code class="docutils literal"><span class="pre">step</span></code> parameter to these functions
+algorithms take multiple inputs; the <code class="docutils literal notranslate"><span class="pre">step</span></code> parameter to these functions
indicates which input is being provided. The documentation for each key
derivation algorithm describes the expected inputs for that algorithm and
-in what order to pass them.</li>
-<li>Optionally, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_set_capacity" title="psa_key_derivation_set_capacity"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_set_capacity()</span></code></a> to set a limit on the
-amount of data that can be output from the key derivation operation.</li>
-<li>Call <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> to create a derived key, or
-<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to export the derived data. These
+in what order to pass them.</p></li>
+<li><p>Optionally, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_set_capacity" title="psa_key_derivation_set_capacity"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_set_capacity()</span></code></a> to set a limit on the
+amount of data that can be output from the key derivation operation.</p></li>
+<li><p>Call <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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create a derived key, or
+<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to export the derived data. These
functions can be called multiple times to read successive output from the key
-derivation, until the stream is exhausted when its capacity has been reached.</li>
-<li>Key derivation does not finish in the same way as other multi-part
-operations. Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation
-operation memory when the object is no longer required.</li>
+derivation, until the stream is exhausted when its capacity has been reached.</p></li>
+<li><p>Key derivation does not finish in the same way as other multi-part
+operations. Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation
+operation memory when the object is no longer required.</p></li>
</ol>
-<p>To recover from an error, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key
+<p>To recover from an error, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key
derivation operation memory.</p>
<p>A key derivation operation cannot be rewound. Once a part of the stream has been
output, it cannot be output again. This ensures that the same part of the output
@@ -451,33 +448,35 @@
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="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>
-<li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> with the step
-<a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> and the master key.</li>
-<li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> with the step
-<a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> and a public value that uniquely
-identifies the message.</li>
-<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 derived message
-encryption key’s attributes.</li>
-<li>Call <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> to create the derived message key.</li>
-<li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to generate the derived IV.</li>
-<li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation operation
-memory.</li>
+<li><p>Derive the message encryption material from the master key.</p>
+<ol class="loweralpha simple">
+<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_ALG_HKDF</span></code></a> as the algorithm.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_input_key()</span></code></a> with the step
+<a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> and the master key.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> with the step
+<a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> and a public value that uniquely
+identifies the message.</p></li>
+<li><p>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 notranslate"><span class="pre">psa_key_attributes_t</span></code></a> object with the derived message
+encryption key’s attributes.</p></li>
+<li><p>Call <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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create the derived message key.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to generate the derived IV.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation operation
+memory.</p></li>
</ol>
</li>
-<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>
-<li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a> using the derived IV retrieved above.</li>
-<li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> one or more times to encrypt the message.</li>
-<li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a> at the end of the message.</li>
+<li><p>Encrypt the message with the derived material.</p>
+<ol class="loweralpha simple">
+<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</p></li>
+<li><p>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 notranslate"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> with the derived message encryption key.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a> using the derived IV retrieved above.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_update()</span></code></a> one or more times to encrypt the message.</p></li>
+<li><p>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_finish()</span></code></a> at the end of the message.</p></li>
</ol>
</li>
-<li>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> to clear the generated key.</li>
+<li><p>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 notranslate"><span class="pre">psa_destroy_key()</span></code></a> to clear the generated key.</p></li>
</ol>
</div>
</div>
@@ -488,18 +487,18 @@
<div class="section" id="asymmetric-encryption">
<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>
+<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 notranslate"><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 notranslate"><span class="pre">psa_asymmetric_decrypt()</span></code></a>.</p>
</div>
<div class="section" id="hash-and-sign">
<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
+<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 notranslate"><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 notranslate"><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>
-<p>The functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="../api/ops/sign.html#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> take a message hash as
+<p>The functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="../api/ops/sign.html#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_verify_hash()</span></code></a> take a message hash as
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/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
+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 notranslate"><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
@@ -512,10 +511,10 @@
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
+<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 notranslate"><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
+<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 notranslate"><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>
@@ -529,15 +528,16 @@
implement any algorithm that requires randomness internally, and they do not
provide a key generation functionality. For example, a special-purpose component
for signature verification can omit this.</p>
-<p>It is recommended that applications use <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/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> to generate
+<p>It is recommended that applications use <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 notranslate"><span class="pre">psa_generate_key()</span></code></a>,
+<a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_generate_iv()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> to generate
suitably-formatted random data, as applicable. In addition, the API includes a
-function <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> to generate and extract arbitrary random data.</p>
+function <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 notranslate"><span class="pre">psa_generate_random()</span></code></a> to generate and extract arbitrary random data.</p>
</div>
</div>
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -598,13 +598,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -615,8 +615,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/goals.html b/docs/html/overview/goals.html
index 0185da7..02bd580 100644
--- a/docs/html/overview/goals.html
+++ b/docs/html/overview/goals.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="design-goals">
@@ -50,10 +43,10 @@
multi-application devices, such as servers. Consequentially, the interface is
scalable and modular.</p>
<ul class="simple">
-<li><em>Scalable</em>: devices only need to implement the functionality that they will
-use.</li>
-<li><em>Modular</em>: larger devices implement larger subsets of the same interface,
-rather than different interfaces.</li>
+<li><p><em>Scalable</em>: devices only need to implement the functionality that they will
+use.</p></li>
+<li><p><em>Modular</em>: larger devices implement larger subsets of the same interface,
+rather than different interfaces.</p></li>
</ul>
<p>In this interface, all operations on unbounded amounts of data
allow <em>multi-part</em> processing, as long as the calculations on the data are
@@ -90,9 +83,9 @@
is located in a different environment, which is protected from the frontend.
Various technologies can provide protection, for example:</p>
<ul class="simple">
-<li>Process isolation in an operating system.</li>
-<li>Partition isolation, either with a virtual machine or a partition manager.</li>
-<li>Physical separation between devices.</li>
+<li><p>Process isolation in an operating system.</p></li>
+<li><p>Partition isolation, either with a virtual machine or a partition manager.</p></li>
+<li><p>Physical separation between devices.</p></li>
</ul>
<p>Communication between the frontend and backend is beyond the scope of this
specification.</p>
@@ -107,19 +100,19 @@
instances to share data in any form.</p>
<p>In summary, there are three types of implementation:</p>
<ul class="simple">
-<li>No isolation: there is no security boundary between the application and the
+<li><p>No isolation: there is no security boundary between the application and the
cryptoprocessor. For example, a statically or dynamically linked library is
-an implementation with no isolation.</li>
-<li>Cryptoprocessor isolation: there is a security boundary between the
+an implementation with no isolation.</p></li>
+<li><p>Cryptoprocessor isolation: there is a security boundary between the
application and the cryptoprocessor, but the cryptoprocessor does not
communicate with other applications. For example, a cryptoprocessor chip that
is a companion to an application processor is an implementation with
-cryptoprocessor isolation.</li>
-<li>Caller isolation: there are multiple application instances, with a security
+cryptoprocessor isolation.</p></li>
+<li><p>Caller isolation: there are multiple application instances, with a security
boundary between the application instances among themselves, as well as
between the cryptoprocessor and the application instances. For example, a
cryptography service in a multiprocess environment is an implementation with
-caller and cryptoprocessor isolation.</li>
+caller and cryptoprocessor isolation.</p></li>
</ul>
</div>
<div class="section" id="choice-of-algorithms">
@@ -214,6 +207,7 @@
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -263,13 +257,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -280,8 +274,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/implementation.html b/docs/html/overview/implementation.html
index dd8e2f3..39f7205 100644
--- a/docs/html/overview/implementation.html
+++ b/docs/html/overview/implementation.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="implementation-considerations">
@@ -56,11 +49,11 @@
<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
+as C <code class="docutils literal notranslate"><span class="pre">typedef</span></code> types in this specification, with a comment
<em><a class="reference internal" href="#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> in place of the underlying type
definition. For some types the specification constrains the type, for example,
-by requiring that the type is a <code class="docutils literal"><span class="pre">struct</span></code>, or that it is convertible to and
-from an unsigned integer. In the implementation’s version of <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code>,
+by requiring that the type is a <code class="docutils literal notranslate"><span class="pre">struct</span></code>, or that it is convertible to and
+from an unsigned integer. In the implementation’s version of <code class="file docutils literal notranslate"><span class="pre">psa/crypto.h</span></code>,
these types need to be defined as complete C types so that objects of these
types can be instantiated by application code.</p>
<p>Applications that rely on the implementation specific definition of any of these
@@ -75,10 +68,10 @@
implementation-specific. The description of an implementation-specific macro can
optionally specify each of the following requirements:</p>
<ul class="simple">
-<li>Input domains: the macro must be valid for arguments within the input domain.</li>
-<li>A return type: the macro result must be compatible with this type.</li>
-<li>Output range: the macro result must lie in the output range.</li>
-<li>Computed value: A precise mapping of valid input to output values.</li>
+<li><p>Input domains: the macro must be valid for arguments within the input domain.</p></li>
+<li><p>A return type: the macro result must be compatible with this type.</p></li>
+<li><p>Output range: the macro result must lie in the output range.</p></li>
+<li><p>Computed value: A precise mapping of valid input to output values.</p></li>
</ul>
<p>Each implementation-specific macro is in one of following categories:</p>
<p id="specification-defined-value"><em>Specification-defined value</em></p>
@@ -90,10 +83,10 @@
<em><a class="reference internal" href="#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>.</p>
<p>For function-like macros with specification-defined values:</p>
<ul class="simple">
-<li>Example implementations are provided in an appendix to this specification.
-See <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>
+<li><p>Example implementations are provided in an appendix to this specification.
+See <a class="reference internal" href="../appendix/specdef_values.html#appendix-specdef-values"><span class="secref">Example macro implementations</span></a>.</p></li>
+<li><p>The expected computation for valid and supported input arguments will be
+defined as pseudo-code in a future version of this specification.</p></li>
</ul>
</div></blockquote>
<p id="implementation-defined-value"><em>Implementation-defined value</em></p>
@@ -131,12 +124,12 @@
<div class="section" id="platform-specific-types">
<h3>6.2.2. Platform-specific types</h3>
<p>The specification makes use of some types defined in C99. These types must be
-defined in the implementation version of <code class="file docutils literal"><span class="pre">psa/crypto.h</span></code> or by a header
+defined in the implementation version of <code class="file docutils literal notranslate"><span class="pre">psa/crypto.h</span></code> or by a header
included in this file. The following C99 types are used:</p>
-<dl class="docutils">
-<dt><code class="docutils literal"><span class="pre">uint8_t</span></code>, <code class="docutils literal"><span class="pre">uint16_t</span></code>, <code class="docutils literal"><span class="pre">uint32_t</span></code></dt>
-<dd>Unsigned integer types with 8, 16 and 32 value bits respectively.
-These types are defined by the C99 header <code class="file docutils literal"><span class="pre">stdint.h</span></code>.</dd>
+<dl class="simple">
+<dt><code class="docutils literal notranslate"><span class="pre">uint8_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint16_t</span></code>, <code class="docutils literal notranslate"><span class="pre">uint32_t</span></code></dt><dd><p>Unsigned integer types with 8, 16 and 32 value bits respectively.
+These types are defined by the C99 header <code class="file docutils literal notranslate"><span class="pre">stdint.h</span></code>.</p>
+</dd>
</dl>
</div>
<div class="section" id="cryptographic-hardware-support">
@@ -174,11 +167,11 @@
identifier value. Isolation of key identifiers can be achieved in several ways.
For example:</p>
<ul class="simple">
-<li>There is a single identifier namespace for all clients, and the
+<li><p>There is a single identifier namespace for all clients, and the
implementation verifies that the client is the owner of the identifier when
-looking up the key.</li>
-<li>Each client has an independent identifier namespace, and the implementation
-uses a client specific identifier-to-key mapping when looking up the key.</li>
+looking up the key.</p></li>
+<li><p>Each client has an independent identifier namespace, and the implementation
+uses a client specific identifier-to-key mapping when looking up the key.</p></li>
</ul>
<p>After a volatile key identifier is destroyed, it is recommended that the
implementation does not immediately reuse the same identifier value for a
@@ -209,22 +202,22 @@
<p>Implementing the <a class="reference internal" href="#memory-cleanup"><span class="std std-ref">memory cleanup rule</span></a> for persistent keys
can result in inefficiencies when the same persistent key is used sequentially
in multiple cryptographic operations. The inefficiency stems from loading the
-key from non-volatile storage on each use of the key. The <a class="reference internal" href="../api/keys/policy.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a>
+key from non-volatile storage on each use of the key. The <a class="reference internal" href="../api/keys/policy.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a>
usage flag in a key policy allows an application to request that the implementation does not cleanup
non-essential copies of persistent key material, effectively suspending the
cleanup rules for that key. The effects of this policy depend on the
implementation and the key, for example:</p>
<ul class="simple">
-<li>For volatile keys or keys in a secure element with no open/close mechanism,
-this is likely to have no effect.</li>
-<li>For persistent keys that are not in a secure element, this allows the
+<li><p>For volatile keys or keys in a secure element with no open/close mechanism,
+this is likely to have no effect.</p></li>
+<li><p>For persistent keys that are not in a secure element, this allows the
implementation to keep the key in a memory cache outside of the memory used
-by ongoing operations.</li>
-<li>For keys in a secure element with an open/close mechanism, this is a hint to
-keep the key open in the secure element.</li>
+by ongoing operations.</p></li>
+<li><p>For keys in a secure element with an open/close mechanism, this is a hint to
+keep the key open in the secure element.</p></li>
</ul>
<p>The application can indicate when it has finished using the key by calling
-<a class="reference internal" href="../api/keys/management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_purge_key()</span></code></a>, to request that the key material is cleaned from memory.</p>
+<a class="reference internal" href="../api/keys/management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_purge_key()</span></code></a>, to request that the key material is cleaned from memory.</p>
</div>
<div class="section" id="safe-outputs-on-error">
<h3>6.3.5. Safe outputs on error</h3>
@@ -263,20 +256,20 @@
<div class="section" id="philosophy-of-resource-management">
<h3>6.4.1. Philosophy of resource management</h3>
<p>The specification allows most functions to return
-<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a>. This gives implementations the freedom to
+<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a>. This gives implementations the freedom to
manage memory as they please.</p>
<p>Alternatively, the interface is also designed for conservative strategies of
memory management. An implementation can avoid dynamic memory allocation
altogether by obeying certain restrictions:</p>
<ul class="simple">
-<li>Pre-allocate memory for a predefined number of keys, each with sufficient
-memory for all key types that can be stored.</li>
-<li>For multi-part operations, in an implementation without isolation, place all
+<li><p>Pre-allocate memory for a predefined number of keys, each with sufficient
+memory for all key types that can be stored.</p></li>
+<li><p>For multi-part operations, in an implementation without isolation, place all
the data that needs to be carried over from one step to the next in the
operation object. The application is then fully in control of how memory is
-allocated for the operation.</li>
-<li>In an implementation with isolation, pre-allocate memory for a predefined
-number of operations inside the cryptoprocessor.</li>
+allocated for the operation.</p></li>
+<li><p>In an implementation with isolation, pre-allocate memory for a predefined
+number of operations inside the cryptoprocessor.</p></li>
</ul>
</div>
</div>
@@ -284,6 +277,7 @@
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -343,13 +337,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -360,8 +354,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/intro.html b/docs/html/overview/intro.html
index e7e6c14..7e22280 100644
--- a/docs/html/overview/intro.html
+++ b/docs/html/overview/intro.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="introduction">
@@ -59,15 +52,15 @@
key storage functionality.</p>
<p>This document includes:</p>
<ul class="simple">
-<li>A <a class="reference internal" href="goals.html#design-goals"><span class="std std-ref">rationale</span></a> for the design.</li>
-<li>A <a class="reference internal" href="functionality.html#functionality-overview"><span class="std std-ref">high-level overview of the functionality</span></a>
-provided by the interface.</li>
-<li>A <a class="reference internal" href="sample-arch.html#architectures"><span class="std std-ref">description of typical architectures</span></a> of
-implementations for this specification.</li>
-<li>General considerations <a class="reference internal" href="implementation.html#implementation-considerations"><span class="std std-ref">for implementers</span></a>
+<li><p>A <a class="reference internal" href="goals.html#design-goals"><span class="std std-ref">rationale</span></a> for the design.</p></li>
+<li><p>A <a class="reference internal" href="functionality.html#functionality-overview"><span class="std std-ref">high-level overview of the functionality</span></a>
+provided by the interface.</p></li>
+<li><p>A <a class="reference internal" href="sample-arch.html#architectures"><span class="std std-ref">description of typical architectures</span></a> of
+implementations for this specification.</p></li>
+<li><p>General considerations <a class="reference internal" href="implementation.html#implementation-considerations"><span class="std std-ref">for implementers</span></a>
of this specification and <a class="reference internal" href="usage.html#usage-considerations"><span class="std std-ref">for applications</span></a> that
-use the interface defined in this specification.</li>
-<li>A <a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">detailed definition</span></a> of the API.</li>
+use the interface defined in this specification.</p></li>
+<li><p>A <a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">detailed definition</span></a> of the API.</p></li>
</ul>
<p>Companion documents will define <em>profiles</em> for this specification. A profile is
a minimum mandatory subset of the interface that a compliant implementation must
@@ -76,6 +69,7 @@
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -108,13 +102,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -125,8 +119,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/sample-arch.html b/docs/html/overview/sample-arch.html
index 679aec7..e799241 100644
--- a/docs/html/overview/sample-arch.html
+++ b/docs/html/overview/sample-arch.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="sample-architectures">
@@ -100,10 +93,10 @@
programmable memory during the manufacturing of the device. This key can be used
for one or more purposes:</p>
<ul class="simple">
-<li>Encrypt and authenticate data stored in the application processor.</li>
-<li>Communicate with a paired device.</li>
-<li>Allow the application to perform operations with keys that are derived from
-the hardware unique key.</li>
+<li><p>Encrypt and authenticate data stored in the application processor.</p></li>
+<li><p>Communicate with a paired device.</p></li>
+<li><p>Allow the application to perform operations with keys that are derived from
+the hardware unique key.</p></li>
</ul>
</div>
<div class="section" id="multi-client-cryptoprocessor">
@@ -123,32 +116,33 @@
<p>This system includes multiple cryptoprocessors. There are several reasons to
have multiple cryptoprocessors:</p>
<ul class="simple">
-<li>Different compromises between security and performance for different keys.
+<li><p>Different compromises between security and performance for different keys.
Typically, this means a cryptoprocessor that runs on the same hardware as the
main application and processes short-term secrets, a secure element or a
-similar separate chip that retains long-term secrets.</li>
-<li>Independent provisioning of certain secrets.</li>
-<li>A combination of a non-removable cryptoprocessor and removable ones, for
-example, a smartcard or HSM.</li>
-<li>Cryptoprocessors managed by different stakeholders who do not trust each
-other.</li>
+similar separate chip that retains long-term secrets.</p></li>
+<li><p>Independent provisioning of certain secrets.</p></li>
+<li><p>A combination of a non-removable cryptoprocessor and removable ones, for
+example, a smartcard or HSM.</p></li>
+<li><p>Cryptoprocessors managed by different stakeholders who do not trust each
+other.</p></li>
</ul>
<p>The keystore implementation needs to dispatch each request to the correct
processor. For example:</p>
<ul class="simple">
-<li>All requests involving a non-extractable key must be processed in the
-cryptoprocessor that holds that key.</li>
-<li>Requests involving a persistent key must be processed in the cryptoprocessor
-that corresponds to the key’s lifetime value.</li>
-<li>Requests involving a volatile key might target a cryptoprocessor based on
+<li><p>All requests involving a non-extractable key must be processed in the
+cryptoprocessor that holds that key.</p></li>
+<li><p>Requests involving a persistent key must be processed in the cryptoprocessor
+that corresponds to the key’s lifetime value.</p></li>
+<li><p>Requests involving a volatile key might target a cryptoprocessor based on
parameters supplied by the application, or based on considerations such as
-performance inside the implementation.</li>
+performance inside the implementation.</p></li>
</ul>
</div>
</div>
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -188,13 +182,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -205,8 +199,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>
diff --git a/docs/html/overview/usage.html b/docs/html/overview/usage.html
index ab13482..a1f98ce 100644
--- a/docs/html/overview/usage.html
+++ b/docs/html/overview/usage.html
@@ -1,26 +1,17 @@
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
- "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
- <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <meta charset="utf-8" />
<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.1',
- COLLAPSE_INDEX: false,
- FILE_SUFFIX: '.html',
- HAS_SOURCE: false,
- SOURCELINK_SUFFIX: '.txt'
- };
- </script>
+ <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
+ <script type="text/javascript" src="../_static/language_data.js"></script>
<link rel="author" title="About these documents" href="../about.html" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
@@ -29,15 +20,17 @@
<link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
- </head>
- <body>
+ </head><body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
+
+
<div class="body" role="main">
<div class="section" id="usage-considerations">
@@ -47,28 +40,28 @@
<div class="section" id="always-check-for-errors">
<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>
+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 notranslate"><span class="pre">psa_status_t</span></code></a>. A few functions cannot fail, and thus, return
+<code class="docutils literal notranslate"><span class="pre">void</span></code> or some other type.</p>
<p>If an error occurs, unless otherwise specified, the content of the output
parameters is undefined and must not be used.</p>
<p>Some common causes of errors include:</p>
<ul class="simple">
-<li>In implementations where the keys are stored and processed in a separate
+<li><p>In implementations where the keys are stored and processed in a separate
environment from the application, all functions that need to access the
cryptography processing environment might fail due to an error in the
-communication between the two environments.</li>
-<li>If an algorithm is implemented with a hardware accelerator, which is
+communication between the two environments.</p></li>
+<li><p>If an algorithm is implemented with a hardware accelerator, which is
logically separate from the application processor, the accelerator might fail,
-even when the application processor keeps running normally.</li>
-<li>Most functions might fail due to a lack of resources. However, some
+even when the application processor keeps running normally.</p></li>
+<li><p>Most functions might fail due to a lack of resources. However, some
implementations guarantee that certain functions always have sufficient
-memory.</li>
-<li>All functions that access persistent keys might fail due to a storage failure.</li>
-<li>All functions that require randomness might fail due to a lack of entropy.
+memory.</p></li>
+<li><p>All functions that access persistent keys might fail due to a storage failure.</p></li>
+<li><p>All functions that require randomness might fail due to a lack of entropy.
Implementations are encouraged to seed the random generator with sufficient
-entropy during the execution of <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>. However, some security
+entropy during the execution of <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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>. However, some security
standards require periodic reseeding from a hardware random generator, which
-can fail.</li>
+can fail.</p></li>
</ul>
</div>
<div class="section" id="shared-memory-and-concurrency">
@@ -97,9 +90,9 @@
compromised.</p>
<p>Wiping sensitive data includes:</p>
<ul class="simple">
-<li>Clearing temporary buffers in the stack or on the heap.</li>
-<li>Aborting operations if they will not be finished.</li>
-<li>Destroying keys that are no longer used.</li>
+<li><p>Clearing temporary buffers in the stack or on the heap.</p></li>
+<li><p>Aborting operations if they will not be finished.</p></li>
+<li><p>Destroying keys that are no longer used.</p></li>
</ul>
</div>
</div>
@@ -107,6 +100,7 @@
</div>
+
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
@@ -147,13 +141,13 @@
<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>
+ <h3 id="searchlabel">Quick search</h3>
+ <div class="searchformwrapper">
<form class="search" action="../search.html" method="get">
- <div><input type="text" name="q" /></div>
- <div><input type="submit" value="Go" /></div>
- <input type="hidden" name="check_keywords" value="yes" />
- <input type="hidden" name="area" value="default" />
+ <input type="text" name="q" aria-labelledby="searchlabel" />
+ <input type="submit" value="Go" />
</form>
+ </div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
@@ -164,8 +158,8 @@
© 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>
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
</div>