Update PSA API specification to 1.0.0
Generated from the PSA Crypto API Dockerfile at tag psa-crypto-api-1.0.0
diff --git a/docs/html/overview/conventions.html b/docs/html/overview/conventions.html
new file mode 100644
index 0000000..b294ef6
--- /dev/null
+++ b/docs/html/overview/conventions.html
@@ -0,0 +1,368 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Library conventions — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Implementation considerations" href="implementation.html" />
+ <link rel="prev" title="Sample architectures" href="sample-arch.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="library-conventions">
+<h1>Library conventions</h1>
+<div class="section" id="error-handling">
+<h2>Error handling</h2>
+<div class="section" id="return-status">
+<h3>Return status</h3>
+<p>Almost all functions return a status indication of type <a class="reference internal" href="../api/library/status.html#c.psa_status_t" title="psa_status_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_status_t</span></code></a>. This
+is an enumeration of integer values, with <code class="docutils literal"><span class="pre">0</span></code> (<a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>) indicating
+successful operation and other values indicating errors. The exceptions are
+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>
+<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
+implementations can make different choices, for example to favor code size over
+ease of debugging or vice versa.</p>
+<p>If the behavior is undefined, for example, if a function receives an invalid
+pointer as a parameter, this specification makes no guarantee that the function
+will return an error. Implementations are encouraged to return an error or halt
+the application in a manner that is appropriate for the platform if the
+undefined behavior condition can be detected. However, application developers need to be aware that undefined behavior conditions cannot be detected in general.</p>
+</div>
+<div class="section" id="behavior-on-error">
+<h3>Behavior on error</h3>
+<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
+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>
+</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
+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
+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
+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
+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>
+</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
+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>
+</div>
+</div>
+<div class="section" id="parameter-conventions">
+<h2>Parameter conventions</h2>
+<div class="section" id="pointer-conventions">
+<h3>Pointer conventions</h3>
+<p>Unless explicitly stated in the documentation of a function, all pointers must
+be valid pointers to an object of the specified type.</p>
+<p>A parameter is considered a <strong>buffer</strong> if it points to an array of bytes. A
+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
+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>
+<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
+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
+dereference.</p>
+<p>Pointers to input parameters can be in read-only memory. Output parameters must
+be in writable memory. Output parameters that are not buffers must also be
+readable, and the implementation must be able to write to a non-buffer output
+parameter and read back the same value, as explained in the
+<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+</div>
+<div class="section" id="input-buffer-sizes">
+<h3>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>
+<p>The interface never uses input-output buffers.</p>
+</div>
+<div class="section" id="output-buffer-sizes">
+<h3>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>
+<p>The content of the data buffer and of <code class="docutils literal"><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
+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
+compile-time constants, so they are suitable for static or stack allocation.
+Refer to an individual function’s documentation for the associated output size
+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>
+</div>
+<div class="section" id="overlap-between-parameters">
+<h3>Overlap between parameters</h3>
+<p>Output parameters that are not buffers must not overlap with any input buffer or
+with any other output parameter. Otherwise, the behavior is undefined.</p>
+<p>Output buffers can overlap with input buffers. In this event, the implementation
+must return the same result as if the buffers did not overlap. The
+implementation must behave as if it had copied all the inputs into temporary
+memory, as far as the result is concerned. However, it is possible that overlap
+between parameters will affect the performance of a function call. Overlap might
+also affect memory management security if the buffer is located in memory that
+the caller shares with another security context, as described in the
+<em><a class="reference internal" href="#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+</div>
+<div class="section" id="stability-of-parameters">
+<span id="id1"></span><h3>Stability of parameters</h3>
+<p>In some environments, it is possible for the content of a parameter to change
+while a function is executing. It might also be possible for the content of an
+output parameter to be read before the function terminates. This can happen if
+the application is multithreaded. In some implementations, memory can be shared
+between security contexts, for example, between tasks in a multitasking
+operating system, between a user land task and the kernel, or between the
+Non-secure world and the Secure world of a trusted execution environment.</p>
+<p>This section describes the assumptions that an implementation can make about
+function parameters, and the guarantees that the implementation must provide
+about how it accesses parameters.</p>
+<p>Parameters that are not buffers are assumed to be under the caller’s full
+control. In a shared memory environment, this means that the parameter must be
+in memory that is exclusively accessible by the application. In a multithreaded
+environment, this means that the parameter must not be modified during the
+execution, and the value of an output parameter is undetermined until the
+function returns. The implementation can read an input parameter that is not a
+buffer multiple times and expect to read the same data. The implementation can
+write to an output parameter that is not a buffer and expect to read back the
+value that it last wrote. The implementation has the same permissions on buffers
+that overlap with a buffer in the opposite direction.</p>
+<p>In an environment with multiple threads or with shared memory, the
+implementation carefully accesses non-overlapping buffer parameters in order to
+prevent any security risk resulting from the content of the buffer being
+modified or observed during the execution of the function. In an input buffer
+that does not overlap with an output buffer, the implementation reads each byte
+of the input once, at most. The implementation does not read from an output
+buffer that does not overlap with an input buffer. Additionally, the
+implementation does not write data to a non-overlapping output buffer if this
+data is potentially confidential and the implementation has not yet verified
+that outputting this data is authorized.</p>
+<p>Unless otherwise specified, the implementation must not keep a reference to any
+parameter once a function call has returned.</p>
+</div>
+</div>
+<div class="section" id="key-types-and-algorithms">
+<h2>Key types and algorithms</h2>
+<p>Types of cryptographic keys and cryptographic algorithms are encoded separately.
+Each is encoded by using an integral type: <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a> and
+<a class="reference internal" href="../api/keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>, respectively.</p>
+<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
+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>
+<div class="section" id="structure-of-key-and-algorithm-types">
+<h3>Structure of key and algorithm types</h3>
+<p>Both types use a partial bitmask structure, which allows the analysis and
+building of values from parts. However, the interface defines constants, so that
+applications do not need to depend on the encoding, and an implementation might
+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
+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
+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>
+</ul>
+</div>
+</div>
+<div class="section" id="concurrent-calls">
+<span id="concurrency"></span><h2>Concurrent calls</h2>
+<p>In some environments, an application can make calls to the PSA crypto API in
+separate threads. In such an environment, concurrent calls are performed
+correctly, as if the calls were executed in sequence, provided that they obey
+the following constraints:</p>
+<ul class="simple">
+<li>There is no overlap between an output parameter of one call and an input or
+output parameter of another call. Overlap between input parameters is
+permitted.</li>
+<li>If a call destroys a key, then no other call must destroy or use that key.
+<em>Using</em>, in this context, includes all functions of multi-part operations
+which have used the key as an input in a previous function.</li>
+<li>Concurrent calls that use the same key are permitted.</li>
+<li>Concurrent calls must not use the same operation object.</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
+progress, the behavior is undefined.</p>
+<p>Individual implementations can provide additional guarantees.</p>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Library conventions</a><ul>
+<li><a class="reference internal" href="#error-handling">Error handling</a><ul>
+<li><a class="reference internal" href="#return-status">Return status</a></li>
+<li><a class="reference internal" href="#behavior-on-error">Behavior on error</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#parameter-conventions">Parameter conventions</a><ul>
+<li><a class="reference internal" href="#pointer-conventions">Pointer conventions</a></li>
+<li><a class="reference internal" href="#input-buffer-sizes">Input buffer sizes</a></li>
+<li><a class="reference internal" href="#output-buffer-sizes">Output buffer sizes</a></li>
+<li><a class="reference internal" href="#overlap-between-parameters">Overlap between parameters</a></li>
+<li><a class="reference internal" href="#stability-of-parameters">Stability of parameters</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#key-types-and-algorithms">Key types and algorithms</a><ul>
+<li><a class="reference internal" href="#structure-of-key-and-algorithm-types">Structure of key and algorithm types</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#concurrent-calls">Concurrent calls</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="sample-arch.html" title="previous chapter">Sample architectures</a></li>
+ <li>Next: <a href="implementation.html" title="next chapter">Implementation considerations</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/conventions.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/conventions.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/functionality.html b/docs/html/overview/functionality.html
new file mode 100644
index 0000000..5f9d447
--- /dev/null
+++ b/docs/html/overview/functionality.html
@@ -0,0 +1,706 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Functionality overview — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Sample architectures" href="sample-arch.html" />
+ <link rel="prev" title="Design goals" href="goals.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="functionality-overview">
+<span id="id1"></span><h1>Functionality overview</h1>
+<p>This section provides a high-level overview of the functionality provided by the
+interface defined in this specification. Refer to the <a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">API definition</span></a> for a detailed description.</p>
+<p><a class="reference internal" href="../appendix/history.html#future"><span class="std std-ref">Future additions</span></a> describes features that might be included in future versions of this
+specification.</p>
+<p>Due to the modularity of the interface, almost every part of the library is
+optional. The only mandatory function is <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</p>
+<div class="section" id="library-management">
+<h2>Library management</h2>
+<p>Applications must call <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a> to initialize the library before
+using any other function.</p>
+</div>
+<div class="section" id="key-management">
+<h2>Key management</h2>
+<p>Applications always access keys indirectly via an identifier, and can perform
+operations using a key without accessing the key material. This allows keys to
+be <em>non-extractable</em>, where an application can use a key but is not permitted to
+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
+is used when creating a key and when querying key attributes.</p>
+<p>Each key has a <em>lifetime</em> that determines when the key material is destroyed.
+There are two types of lifetimes: <a class="reference internal" href="#volatile-keys"><span class="std std-ref">volatile</span></a> and
+<a class="reference internal" href="#persistent-keys"><span class="std std-ref">persistent</span></a>.</p>
+<div class="section" id="volatile-keys">
+<span id="id2"></span><h3>Volatile keys</h3>
+<p>A <em>volatile</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>
+or until the application terminates, which conceptually destroys all of its
+volatile keys.</p>
+<p>Conceptually, a volatile key is stored in RAM. Volatile keys have the
+lifetime <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>.</p>
+<p>To create a volatile key:</p>
+<ol class="arabic simple">
+<li>Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the required type, size, policy
+and other key attributes.</li>
+<li>Create the key with <a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>,
+<a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>. If successful, these
+functions output a transient <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a>.</li>
+</ol>
+<p>To destroy a volatile key, call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier.</p>
+</div>
+<div class="section" id="persistent-keys">
+<span id="id3"></span><h3>Persistent keys</h3>
+<p>A <em>persistent</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>
+or until it is wiped by the reset or destruction of the device.</p>
+<p>Each persistent key has a permanent key identifier, which acts as a name for the key.
+Within an application, the key identifier corresponds to a single key. The
+application specifies the key identifier when the key is created and when
+using the key.</p>
+<p>Persistent keys can be stored in different storage areas; this is indicated
+through different lifetime values. This specification defines a single lifetime
+value <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a> which corresponds to a default storage
+area. Implementations can define alternative lifetime values corresponding to
+different storage areas with different retention policies, or to secure elements
+with different security characteristics.</p>
+<p>To create a persistent key:</p>
+<ol class="arabic">
+<li><p class="first">Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the key’s type, size, policy
+and other attributes.</p>
+</li>
+<li><p class="first">In the attributes object, set the desired lifetime and persistent identifier
+for the key.</p>
+</li>
+<li><p class="first">Create the key with one of the <em>key creation functions</em>:</p>
+<ul class="simple">
+<li><a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a></li>
+<li><a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a></li>
+<li><a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a></li>
+<li><a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a></li>
+</ul>
+<p>If successful, these functions output the <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a>
+that was specified by the application in step 2.</p>
+</li>
+</ol>
+<p>To access an existing persistent key: use the key identifier in any API that
+requires a key.</p>
+<p>To remove cached copies of key material for persistent keys created with the
+<a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> policy: call <a class="reference internal" href="../api/keys/management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_purge_key()</span></code></a> with the key identifier.</p>
+<p>To destroy a persistent key: call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier.
+Destroying a persistent key permanently removes it from memory and storage.</p>
+<p>The key lifetime and identifier are set when the key is created and cannot be
+changed without destroying the key first. If the original key permits copying,
+then the application can specify a different lifetime for the copy of the key.</p>
+</div>
+<div class="section" id="key-identifiers">
+<span id="key-ids"></span><h3>Key identifiers</h3>
+<p>Key identifiers are integral values that act as permanent names for persistent
+keys, or as transient references to volatile keys. Key identifiers use the
+<a class="reference internal" href="../api/keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_id_t</span></code></a> type, and the range of identifier values is divided as follows:</p>
+<dl class="docutils">
+<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"> <span class="pre">=</span> <span class="pre">0</span></code></dt>
+<dd>Reserved as an invalid key identifier.</dd>
+<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a></dt>
+<dd>Applications can freely choose persistent key identifiers in this range.</dd>
+<dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code></a></dt>
+<dd>Implementations can define additional persistent key identifiers in this
+range, and must allocate any volatile key identifiers from this range.</dd>
+</dl>
+<p>Key identifiers outside these ranges are reserved for future use.</p>
+<p>Key identifiers are output from a successful call to one of
+the key creation functions. For persistent keys, this is the same identifier
+as the one specified in the key attributes used to create the key.
+The key identifier remains valid until it is invalidated by passing it to
+<a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>. A volatile key identifier must not be used after it has been
+invalidated.</p>
+<p>Valid key identifiers must have distinct values within the same application. If
+the implementation provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key
+identifiers are local to each application. That is, the same key identifier in two
+applications corresponds to two different keys.</p>
+<p>If an invalid key identifier is provided as a parameter in any function, the
+function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a>; except for the special case of
+calling <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="docutils literal"><span class="pre">psa_destroy_key</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"><span class="pre">)</span></code>, which has no effect and always
+returns <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>.</p>
+<p>There must be a matching call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> for each successful call
+to a create a volatile key.</p>
+<p>A call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> destroys the key material, and will cause any active
+operations that are using the key to fail. Therefore an application must not
+destroy a key while an operation using that key is in progress, unless the
+application is prepared to handle a failure of the operation.</p>
+</div>
+<div class="section" id="recommendations-of-minimum-standards-for-key-management">
+<h3>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
+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.
+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
+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
+designed to work only with short-term keys, or only with long-term
+non-extractable keys, do not need to provide this function.</li>
+</ul>
+</div>
+</div>
+<div class="section" id="usage-policies">
+<h2>Usage policies</h2>
+<p>All keys have an associated policy that regulates which operations are permitted
+on the key. Each key policy is a set of usage flags and a specific algorithm
+that is permitted with the key. The policy is part of the key attributes that
+are managed by a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object.</p>
+<p>The usage flags are encoded in a bitmask, which has the type
+<a class="reference internal" href="../api/keys/attributes.html#c.psa_key_usage_t" title="psa_key_usage_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_usage_t</span></code></a>. Four kinds of usage flag can be specified:</p>
+<ul class="simple">
+<li>The extractable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a> determines whether the key
+material can be extracted.</li>
+<li>The copyable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> determines whether the key material
+can be copied into a new key, which can have a different lifetime or a more
+restrictive policy.</li>
+<li>The cacheable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> determines whether the
+implementation is permitted to retain non-essential copies of the
+key material in RAM. This policy only applies to persistent keys. See also
+<em><a class="reference internal" href="implementation.html#key-material"><span class="std std-ref">Managing key material</span></a></em>.</li>
+<li>The other usage flags, for example, <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> and <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>,
+determine whether the corresponding operation is permitted on the key.</li>
+</ul>
+<p>In addition to the usage bitmask, a policy specifies which algorithm is
+permitted with the key. This specification only defines policies that restrict
+keys to a single algorithm, which is consistent with both common practice and
+security good practice.</p>
+<p>A highly constrained implementation might not be able to support all the policies
+that can be expressed through this interface. If an implementation cannot create
+a key with the required policy, it must return an appropriate error code when
+the key is created.</p>
+</div>
+<div class="section" id="symmetric-cryptography">
+<h2>Symmetric cryptography</h2>
+<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>
+</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>
+</ul>
+<div class="section" id="single-part-functions">
+<h3>Single-part Functions</h3>
+<p>Single-part functions are APIs that implement the cryptographic operation in a
+single function call. This is the easiest API to use when all of the inputs and
+outputs fit into the application memory.</p>
+<p>Some use cases involve messages that are too large to be assembled in memory, or
+require non-default configuration of the algorithm. These use cases require the
+use of a <em><a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a></em>.</p>
+</div>
+<div class="section" id="multi-part-operations">
+<span id="id4"></span><h3>Multi-part operations</h3>
+<p>Multi-part operations are APIs which split a single cryptographic operation into
+a sequence of separate steps. This enables fine control over the configuration
+of the cryptographic operation, and allows the message data to be processed in
+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>
+</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
+following methods:</p>
+<blockquote>
+<div><ul class="simple">
+<li>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>
+</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
+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
+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.
+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
+failure, the operation object will enter an <em>error</em> state.</p>
+</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 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
+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>
+<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
+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
+location. For example, an application can allocate an operation object on the
+stack and return it, or the operation object can be allocated within memory
+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
+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>
+</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
+functions, and any requirements about their usage and ordering.</p>
+</div>
+<div class="section" id="message-digests-hashes">
+<h3>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>
+</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>
+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>
+</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>
+</div>
+<div class="section" id="message-authentication-codes-macs">
+<h3>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>
+</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>
+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>
+</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>
+</div>
+<div class="section" id="encryption-and-decryption">
+<h3>Encryption and decryption</h3>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The unauthenticated cipher API is provided to implement legacy protocols and
+for use cases where the data integrity and authenticity is guaranteed by
+non-cryptographic means. It is recommended that newer protocols use
+<em><a class="reference internal" href="#func-aead"><span class="std std-ref">Authenticated encryption (AEAD)</span></a></em>.</p>
+</div>
+<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
+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>
+</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>
+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),
+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>
+</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>
+</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>
+</div>
+<div class="section" id="authenticated-encryption-aead">
+<span id="func-aead"></span><h3>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>
+</ul>
+<p>These functions follow the interface recommended by <a class="reference external" href="https://tools.ietf.org/html/rfc5116.html">RFC 5116</a>.</p>
+<p>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>
+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>
+</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>
+</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>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
+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
+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
+these lengths before providing input.</p>
+</div>
+<div class="section" id="key-derivation">
+<span id="id5"></span><h3>Key derivation</h3>
+<p>A key derivation encodes a deterministic method to generate a finite stream of
+bytes. This data stream is computed by the cryptoprocessor and extracted in
+chunks. If two key derivation operations are constructed with the same
+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
+“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>
+</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
+extracted from a single derivation operation object.</p>
+<p>In an implementation with <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">isolation</span></a>, the intermediate
+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
+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
+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
+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
+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>
+</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
+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
+will not be used for different purposes.</p>
+</div>
+<div class="section" id="example-of-the-symmetric-cryptography-api">
+<h3>Example of the symmetric cryptography API</h3>
+<p>Here is an example of a use case where a master key is used to generate both a
+message encryption key and an IV for the encryption, and the derived key and IV
+are then used to encrypt a message.</p>
+<ol class="arabic simple">
+<li>Derive the message encryption material from the master key.<ol class="arabic">
+<li>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>
+</ol>
+</li>
+<li>Encrypt the message with the derived material.<ol class="arabic">
+<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>
+</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>
+</ol>
+</div>
+</div>
+<div class="section" id="asymmetric-cryptography">
+<h2>Asymmetric cryptography</h2>
+<p>This specification defines functions for asymmetric cryptography, including
+asymmetric encryption, asymmetric signature, and two-way key agreement.</p>
+<div class="section" id="asymmetric-encryption">
+<h3>Asymmetric encryption</h3>
+<p>Asymmetric encryption is provided through the functions
+<a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_encrypt()</span></code></a> and <a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_decrypt()</span></code></a>.</p>
+</div>
+<div class="section" id="hash-and-sign">
+<h3>Hash-and-sign</h3>
+<p>The signature and verification functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and
+<a class="reference internal" href="../api/ops/sign.html#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> take a message as one of their inputs and perform a
+hash-and-sign algorithm.</p>
+<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
+one of their inputs. This is useful for signing pre-computed hashes, or for
+implementing hash-and-sign using a <a class="reference internal" href="../api/ops/hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a>
+before signing the resulting hash. To determine which
+hash algorithm to use, call the macro <a class="reference internal" href="../api/keys/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the
+corresponding signature algorithm.</p>
+<p>Some hash-and-sign algorithms add padding to the message hash before completing
+the signing operation. The format of the padding that is used depends on the
+algorithm used to construct the signature.</p>
+</div>
+<div class="section" id="key-agreement">
+<h3>Key agreement</h3>
+<p>This specification defines two functions for a Diffie-Hellman-style key
+agreement where each party combines its own private key with the peer’s public
+key.</p>
+<p>The recommended approach is to use a <a class="reference internal" href="#key-derivation"><span class="std std-ref">key derivation
+operation</span></a> with the <a class="reference internal" href="../api/ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>
+input function, which calculates a shared secret for the key derivation
+function.</p>
+<p>Where an application needs direct access to the shared secret, it can call
+<a class="reference internal" href="../api/ops/ka.html#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a> instead. Note that in general the shared secret is not
+directly suitable for use as a key because it is biased.</p>
+</div>
+</div>
+<div class="section" id="randomness-and-key-generation">
+<h2>Randomness and key generation</h2>
+<p>We strongly recommended that implementations include a random generator,
+consisting of a cryptographically secure pseudo-random generator (CSPRNG), which
+is adequately seeded with a cryptographic-quality hardware entropy source,
+commonly referred to as a true random number generator (TRNG). Constrained
+implementations can omit the random generation functionality if they do not
+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
+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>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Functionality overview</a><ul>
+<li><a class="reference internal" href="#library-management">Library management</a></li>
+<li><a class="reference internal" href="#key-management">Key management</a><ul>
+<li><a class="reference internal" href="#volatile-keys">Volatile keys</a></li>
+<li><a class="reference internal" href="#persistent-keys">Persistent keys</a></li>
+<li><a class="reference internal" href="#key-identifiers">Key identifiers</a></li>
+<li><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">Recommendations of minimum standards for key management</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#usage-policies">Usage policies</a></li>
+<li><a class="reference internal" href="#symmetric-cryptography">Symmetric cryptography</a><ul>
+<li><a class="reference internal" href="#single-part-functions">Single-part Functions</a></li>
+<li><a class="reference internal" href="#multi-part-operations">Multi-part operations</a></li>
+<li><a class="reference internal" href="#message-digests-hashes">Message digests (Hashes)</a></li>
+<li><a class="reference internal" href="#message-authentication-codes-macs">Message authentication codes (MACs)</a></li>
+<li><a class="reference internal" href="#encryption-and-decryption">Encryption and decryption</a></li>
+<li><a class="reference internal" href="#authenticated-encryption-aead">Authenticated encryption (AEAD)</a></li>
+<li><a class="reference internal" href="#key-derivation">Key derivation</a></li>
+<li><a class="reference internal" href="#example-of-the-symmetric-cryptography-api">Example of the symmetric cryptography API</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#asymmetric-cryptography">Asymmetric cryptography</a><ul>
+<li><a class="reference internal" href="#asymmetric-encryption">Asymmetric encryption</a></li>
+<li><a class="reference internal" href="#hash-and-sign">Hash-and-sign</a></li>
+<li><a class="reference internal" href="#key-agreement">Key agreement</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#randomness-and-key-generation">Randomness and key generation</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="goals.html" title="previous chapter">Design goals</a></li>
+ <li>Next: <a href="sample-arch.html" title="next chapter">Sample architectures</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/functionality.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/functionality.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/goals.html b/docs/html/overview/goals.html
new file mode 100644
index 0000000..028cf5e
--- /dev/null
+++ b/docs/html/overview/goals.html
@@ -0,0 +1,287 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Design goals — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Functionality overview" href="functionality.html" />
+ <link rel="prev" title="Introduction" href="intro.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="design-goals">
+<span id="id1"></span><h1>Design goals</h1>
+<div class="section" id="suitable-for-constrained-devices">
+<h2>Suitable for constrained devices</h2>
+<p>The interface is suitable for a vast range of devices: from special-purpose
+cryptographic processors that process data with a built-in key, to constrained
+devices running custom application code, such as microcontrollers, and
+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>
+</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
+performed in a streaming manner. This means that the application does not need
+to store the whole message in memory at one time. As a result, this
+specification is suitable for very constrained devices, including those where
+memory is very limited.</p>
+<p>Memory outside the keystore boundary is managed by the application. An
+implementation of the interface is not required to retain any state between
+function calls, apart from the content of the keystore and other data that must
+be kept inside the keystore security boundary.</p>
+<p>The interface does not expose the representation of keys and intermediate data,
+except when required for interchange. This allows each implementation to choose
+optimal data representations. Implementations with multiple components are also
+free to choose which memory area to use for internal data.</p>
+</div>
+<div class="section" id="a-keystore-interface">
+<h2>A keystore interface</h2>
+<p>The specification allows cryptographic operations to be performed on a key to
+which the application does not have direct access. Except where required for
+interchange, applications access all keys indirectly, by an identifier. The key
+material corresponding to that identifier can reside inside a security boundary
+that prevents it from being extracted, except as permitted by a policy that is
+defined when the key is created.</p>
+</div>
+<div class="section" id="optional-isolation">
+<span id="isolation"></span><h2>Optional isolation</h2>
+<p>Implementations can isolate the cryptoprocessor from the calling application,
+and can further isolate multiple calling applications. The interface allows the
+implementation to be separated between a frontend and a backend. In an isolated
+implementation, the frontend is the part of the implementation that is located
+in the same isolation boundary as the application, which the application
+accesses by function calls. The backend is the part of the implementation that
+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>
+</ul>
+<p>Communication between the frontend and backend is beyond the scope of this
+specification.</p>
+<p>In an isolated implementation, the backend can serve more than one
+implementation instance. In this case, a single backend communicates with
+multiple instances of the frontend. The backend must enforce <strong>caller
+isolation</strong>: it must ensure that assets of one frontend are not visible to any
+other frontend. The mechanism for identifying callers is beyond the scope of this
+specification. An implementation that provides caller isolation must document
+the identification mechanism. An implementation that provides isolation must
+document any implementation-specific extension of the API that enables frontend
+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
+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
+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
+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>
+</ul>
+</div>
+<div class="section" id="choice-of-algorithms">
+<h2>Choice of algorithms</h2>
+<p>The specification defines a low-level cryptographic interface, where the caller
+explicitly chooses which algorithm and which security parameters they use. This
+is necessary to implement protocols that are inescapable in various use cases.
+The design of the interface enables applications to implement widely-used
+protocols and data exchange formats, as well as custom ones.</p>
+<p>As a consequence, all cryptographic functionality operates according to the
+precise algorithm specified by the caller. However, this does not apply to
+device-internal functionality, which does not involve any form of
+interoperability, such as random number generation. The specification does not
+include generic higher-level interfaces, where the implementation chooses the
+best algorithm for a purpose. However, higher-level libraries can be built on
+top of the PSA Crypto API.</p>
+<p>Another consequence is that the specification permits the use of algorithms, key
+sizes and other parameters that, while known to be insecure, might be necessary to
+support legacy protocols or legacy data. Where major weaknesses are known, the
+algorithm descriptions give applicable warnings. However, the lack of a warning
+both does not and cannot indicate that an algorithm is secure in all circumstances.
+Application developers need to research the security of the protocols and
+algorithms that they plan to use to determine if these meet their requirements.</p>
+<p>The interface facilitates algorithm agility. As a consequence, cryptographic
+primitives are presented through generic functions with a parameter indicating
+the specific choice of algorithm. For example, there is a single function to
+calculate a message digest, which takes a parameter that identifies the specific
+hash algorithm.</p>
+</div>
+<div class="section" id="ease-of-use">
+<h2>Ease of use</h2>
+<p>The interface is designed to be as user-friendly as possible, given the
+aforementioned constraints on suitability for various types of devices and on
+the freedom to choose algorithms.</p>
+<p>In particular, the code flows are designed to reduce the risk of dangerous
+misuse. The interface is designed in part to make it harder to misuse. Where
+possible, it is designed so that
+typical mistakes result in test failures, rather than subtle security issues.
+Implementations avoid leaking data when a function is called with invalid
+parameters, to the extent allowed by the C language and by implementation size
+constraints.</p>
+</div>
+<div class="section" id="example-use-cases">
+<h2>Example use cases</h2>
+<p>This section lists some of the use cases that were considered during the design
+of this API. This list is not exhaustive, nor are all implementations required to
+support all use cases.</p>
+<div class="section" id="network-security-tls">
+<h3>Network Security (TLS)</h3>
+<p>The API provides all of the cryptographic primitives needed to establish TLS
+connections.</p>
+</div>
+<div class="section" id="secure-storage">
+<h3>Secure Storage</h3>
+<p>The API provides all primitives related to storage encryption, block or
+file-based, with master encryption keys stored inside a key store.</p>
+</div>
+<div class="section" id="network-credentials">
+<h3>Network Credentials</h3>
+<p>The API provides network credential management inside a key store, for example,
+for X.509-based authentication or pre-shared keys on enterprise networks.</p>
+</div>
+<div class="section" id="device-pairing">
+<h3>Device Pairing</h3>
+<p>The API provides support for key agreement protocols that are often used for
+secure pairing of devices over wireless channels. For example, the pairing of an
+NFC token or a Bluetooth device might use key agreement protocols upon
+first use.</p>
+</div>
+<div class="section" id="secure-boot">
+<h3>Secure Boot</h3>
+<p>The API provides primitives for use during firmware integrity and authenticity
+validation, during a secure or trusted boot process.</p>
+</div>
+<div class="section" id="attestation">
+<h3>Attestation</h3>
+<p>The API provides primitives used in attestation activities. Attestation is the
+ability for a device to sign an array of bytes with a device private key and
+return the result to the caller. There are several use cases; ranging from attestation
+of the device state, to the ability to generate a key pair and prove that it has
+been generated inside a secure key store. The API provides access to the
+algorithms commonly used for attestation.</p>
+</div>
+<div class="section" id="factory-provisioning">
+<h3>Factory Provisioning</h3>
+<p>Most IoT devices receive a unique identity during the factory provisioning
+process, or once they have been deployed to the field. This API provides the APIs necessary for
+populating a device with keys that represent that identity.</p>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Design goals</a><ul>
+<li><a class="reference internal" href="#suitable-for-constrained-devices">Suitable for constrained devices</a></li>
+<li><a class="reference internal" href="#a-keystore-interface">A keystore interface</a></li>
+<li><a class="reference internal" href="#optional-isolation">Optional isolation</a></li>
+<li><a class="reference internal" href="#choice-of-algorithms">Choice of algorithms</a></li>
+<li><a class="reference internal" href="#ease-of-use">Ease of use</a></li>
+<li><a class="reference internal" href="#example-use-cases">Example use cases</a><ul>
+<li><a class="reference internal" href="#network-security-tls">Network Security (TLS)</a></li>
+<li><a class="reference internal" href="#secure-storage">Secure Storage</a></li>
+<li><a class="reference internal" href="#network-credentials">Network Credentials</a></li>
+<li><a class="reference internal" href="#device-pairing">Device Pairing</a></li>
+<li><a class="reference internal" href="#secure-boot">Secure Boot</a></li>
+<li><a class="reference internal" href="#attestation">Attestation</a></li>
+<li><a class="reference internal" href="#factory-provisioning">Factory Provisioning</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="intro.html" title="previous chapter">Introduction</a></li>
+ <li>Next: <a href="functionality.html" title="next chapter">Functionality overview</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/goals.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/goals.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/implementation.html b/docs/html/overview/implementation.html
new file mode 100644
index 0000000..53eb1a9
--- /dev/null
+++ b/docs/html/overview/implementation.html
@@ -0,0 +1,367 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Implementation considerations — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Usage considerations" href="usage.html" />
+ <link rel="prev" title="Library conventions" href="conventions.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="implementation-considerations">
+<span id="id1"></span><h1>Implementation considerations</h1>
+<div class="section" id="implementation-specific-aspects-of-the-interface">
+<h2>Implementation-specific aspects of the interface</h2>
+<div class="section" id="implementation-profile">
+<h3>Implementation profile</h3>
+<p>Implementations can implement a subset of the API and a subset of the available
+algorithms. The implemented subset is known as the implementation’s profile. The
+documentation for each implementation must describe the profile that it
+implements. This specification’s companion documents also define a number of
+standard profiles.</p>
+</div>
+<div class="section" id="implementation-specific-types">
+<span id="implementation-defined-type"></span><h3>Implementation-specific types</h3>
+<p>This specification defines a number of implementation-specific types, which
+represent objects whose content depends on the implementation. These are defined
+as C <code class="docutils literal"><span class="pre">typedef</span></code> types in this specification, with a comment
+<em><a class="reference internal" href="#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> in place of the underlying type
+definition. For some types the specification constrains the type, for example,
+by requiring that the type is a <code class="docutils literal"><span class="pre">struct</span></code>, or that it is convertible to and
+from an unsigned integer. In the implementation’s version of <strong>psa/crypto.h</strong>,
+these types need to be defined as complete C types so that objects of these
+types can be instantiated by application code.</p>
+<p>Applications that rely on the implementation specific definition of any of these
+types might not be portable to other implementations of this specification.</p>
+</div>
+<div class="section" id="implementation-specific-macros">
+<span id="implementation-specific-macro"></span><h3>Implementation-specific macros</h3>
+<p>Some macro constants and function-like macros are precisely defined by this
+specification. The use of an exact definition is essential if the definition can
+appear in more than one header file within a compilation.</p>
+<p>Other macros that are defined by this specification have a macro body that is
+implementation-specific. The description of an implementation-specific macro can
+optionally specify each of the following requirements:</p>
+<ul class="simple">
+<li>Input domains: the macro must be valid for arguments within the input domain.</li>
+<li>A return type: the macro result must be compatible with this type.</li>
+<li>Output range: the macro result must lie in the output range.</li>
+<li>Computed value: A precise mapping of valid input to output values.</li>
+</ul>
+<p>Each implementation-specific macro is in one of following categories:</p>
+<p id="specification-defined-value"><em>Specification-defined value</em></p>
+<blockquote>
+<div><p>The result type and computed value of the macro expression is defined by
+this specification, but the definition of the macro body is provided by the
+implementation.</p>
+<p>These macros are indicated in this specification using the comment
+<em><a class="reference internal" href="#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>.</p>
+<p>For function-like macros with specification-defined values:</p>
+<ul class="simple">
+<li>Example implementations are provided in an appendix to this specification.
+See <em><a class="reference internal" href="../appendix/specdef_values.html#appendix-specdef-values"><span class="std std-ref">Example macro implementations</span></a></em>.</li>
+<li>The expected computation for valid and supported input arguments will be
+defined as pseudo-code in a future version of this specification.</li>
+</ul>
+</div></blockquote>
+<p id="implementation-defined-value"><em>Implementation-defined value</em></p>
+<blockquote>
+<div><p>The value of the macro expression is implementation-defined.</p>
+<p>For some macros, the computed value is derived from the specification of one
+or more cryptographic algorithms. In these cases, the result must exactly
+match the value in those external specifications.</p>
+<p>These macros are indicated in this specification using the comment
+<em><a class="reference internal" href="#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>.</p>
+</div></blockquote>
+<p>Some of these macros compute a result based on an algorithm or key type.
+If an implementation defines vendor-specific algorithms or
+key types, then it must provide an implementation for such macros that takes all
+relevant algorithms and types into account. Conversely, an implementation that
+does not support a certain algorithm or key type can define such macros in a
+simpler way that does not take unsupported argument values into account.</p>
+<p>Some macros define the minimum sufficient output buffer size for certain
+functions. In some cases, an implementation is allowed to require a buffer size
+that is larger than the theoretical minimum. An implementation must define
+minimum-size macros in such a way that it guarantees that the buffer of the
+resulting size is sufficient for the output of the corresponding function. Refer
+to each macro’s documentation for the applicable requirements.</p>
+</div>
+</div>
+<div class="section" id="porting-to-a-platform">
+<h2>Porting to a platform</h2>
+<div class="section" id="platform-assumptions">
+<h3>Platform assumptions</h3>
+<p>This specification is designed for a C99 platform. The interface is defined in
+terms of C macros, functions and objects.</p>
+<p>The specification assumes 8-bit bytes, and “byte” and “octet” are used
+synonymously.</p>
+</div>
+<div class="section" id="platform-specific-types">
+<h3>Platform-specific types</h3>
+<p>The specification makes use of some types defined in C99. These types must be
+defined in the implementation version of <strong>psa/crypto.h</strong> or by a header
+included in this file. The following C99 types are used:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">uint8_t</span></code>, <code class="docutils literal"><span class="pre">uint16_t</span></code>, <code class="docutils literal"><span class="pre">uint32_t</span></code></dt>
+<dd>Unsigned integer types with 8, 16 and 32 value bits respectively.
+These types are defined by the C99 header <strong>stdint.h</strong>.</dd>
+</dl>
+</div>
+<div class="section" id="cryptographic-hardware-support">
+<h3>Cryptographic hardware support</h3>
+<p>Implementations are encouraged to make use of hardware accelerators where
+available. A future version of this specification will define a function
+interface that calls drivers for hardware accelerators and external
+cryptographic hardware.</p>
+</div>
+</div>
+<div class="section" id="security-requirements-and-recommendations">
+<h2>Security requirements and recommendations</h2>
+<div class="section" id="error-detection">
+<h3>Error detection</h3>
+<p>Implementations that provide isolation between the caller and the cryptography
+processing environment must validate parameters to ensure that the cryptography
+processing environment is protected from attacks caused by passing invalid
+parameters.</p>
+<p>Even implementations that do not provide isolation are recommended to detect bad
+parameters and fail-safe where possible.</p>
+</div>
+<div class="section" id="indirect-object-references">
+<h3>Indirect object references</h3>
+<p>Implementations can use different strategies for allocating key identifiers,
+and other types of indirect object reference.</p>
+<p>Implementations that provide isolation between the caller and the cryptography
+processing environment must consider the threats relating to abuse and misuse
+of key identifiers and other indirect resource references. For example,
+multi-part operations can be implemented as backend state to which the client
+only maintains an indirect reference in the application’s multi-part operation
+object.</p>
+<p>An implementation that supports multiple callers must implement strict isolation
+of API resources between different callers. For example, a client must not be
+able to obtain a reference to another client’s key by guessing the key
+identifier value. Isolation of key identifiers can be achieved in several ways.
+For example:</p>
+<ul class="simple">
+<li>There is a single identifier namespace for all clients, and the
+implementation verifies that the client is the owner of the identifier when
+looking up the key.</li>
+<li>Each client has an independent identifier namespace, and the implementation
+uses a client specific identifier-to-key mapping when looking up the key.</li>
+</ul>
+<p>After a volatile key identifier is destroyed, it is recommended that the
+implementation does not immediately reuse the same identifier value for a
+different key. This reduces the risk of an attack that is able to exploit a key
+identifier reuse vulnerability within an application.</p>
+</div>
+<div class="section" id="memory-cleanup">
+<span id="id2"></span><h3>Memory cleanup</h3>
+<p>Implementations must wipe all sensitive data from memory when it is no longer
+used. It is recommended that they wipe this sensitive data as soon as possible. All
+temporary data used during the execution of a function, such as stack buffers,
+must be wiped before the function returns. All data associated with an object,
+such as a multi-part operation, must be wiped, at the latest, when the object
+becomes inactive, for example, when a multi-part operation is aborted.</p>
+<p>The rationale for this non-functional requirement is to minimize impact if the
+system is compromised. If sensitive data is wiped immediately after use, only
+data that is currently in use can be leaked. It does not compromise past data.</p>
+</div>
+<div class="section" id="managing-key-material">
+<span id="key-material"></span><h3>Managing key material</h3>
+<p>In implementations that have limited volatile memory for keys, the
+implementation is permitted to store a <a class="reference internal" href="functionality.html#volatile-keys"><span class="std std-ref">volatile key</span></a> to a
+temporary location in non-volatile memory. The implementation must delete any
+such copies when the key is destroyed, and it is recommended that these copies
+are deleted as soon as the key is reloaded into volatile memory. An
+implementation that uses this method must clear any stored volatile key material
+on startup.</p>
+<p>Implementing the <a class="reference internal" href="#memory-cleanup"><span class="std std-ref">memory cleanup rule</span></a> for persistent keys
+can result in inefficiencies when the same persistent key is used sequentially
+in multiple cryptographic operations. The inefficiency stems from loading the
+key from non-volatile storage on each use of the key. The <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a>
+policy allows an application to request that the implementation does not cleanup
+non-essential copies of persistent key material, effectively suspending the
+cleanup rules for that key. The effects of this policy depend on the
+implementation and the key, for example:</p>
+<ul class="simple">
+<li>For volatile keys or keys in a secure element with no open/close mechanism,
+this is likely to have no effect.</li>
+<li>For persistent keys that are not in a secure element, this allows the
+implementation to keep the key in a memory cache outside of the memory used
+by ongoing operations.</li>
+<li>For keys in a secure element with an open/close mechanism, this is a hint to
+keep the key open in the secure element.</li>
+</ul>
+<p>The application can indicate when it has finished using the key by calling
+<a class="reference internal" href="../api/keys/management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_purge_key()</span></code></a>, to request that the key material is cleaned from memory.</p>
+</div>
+<div class="section" id="safe-outputs-on-error">
+<h3>Safe outputs on error</h3>
+<p>Implementations must ensure that confidential data is not written to output
+parameters before validating that the disclosure of this confidential data is
+authorized. This requirement is particularly important for implementations where
+the caller can share memory with another security context, as described in the
+<a class="reference internal" href="conventions.html#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a> section.</p>
+<p>In most cases, the specification does not define the content of output
+parameters when an error occurs. It is recommended that implementations try to
+ensure that the content of output parameters is as safe as possible, in case an
+application flaw or a data leak causes it to be used. In particular, Arm
+recommends that implementations avoid placing partial output in output buffers
+when an action is interrupted. The meaning of “safe as possible” depends on the
+implementation, as different environments require different compromises between
+implementation complexity, overall robustness and performance. Some common
+strategies are to leave output parameters unchanged, in case of errors, or
+zeroing them out.</p>
+</div>
+<div class="section" id="attack-resistance">
+<h3>Attack resistance</h3>
+<p>Cryptographic code tends to manipulate high-value secrets, from which other
+secrets can be unlocked. As such, it is a high-value target for attacks. There
+is a vast body of literature on attack types, such as side channel attacks and
+glitch attacks. Typical side channels include timing, cache access patterns,
+branch-prediction access patterns, power consumption, radio emissions and more.</p>
+<p>This specification does not specify particular requirements for attack
+resistance. Implementers are encouraged to consider the attack resistance
+desired in each use case and design their implementation accordingly. Security
+standards for attack resistance for particular targets might be applicable in
+certain use cases.</p>
+</div>
+</div>
+<div class="section" id="other-implementation-considerations">
+<h2>Other implementation considerations</h2>
+<div class="section" id="philosophy-of-resource-management">
+<h3>Philosophy of resource management</h3>
+<p>The specification allows most functions to return
+<a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a>. This gives implementations the freedom to
+manage memory as they please.</p>
+<p>Alternatively, the interface is also designed for conservative strategies of
+memory management. An implementation can avoid dynamic memory allocation
+altogether by obeying certain restrictions:</p>
+<ul class="simple">
+<li>Pre-allocate memory for a predefined number of keys, each with sufficient
+memory for all key types that can be stored.</li>
+<li>For multi-part operations, in an implementation without isolation, place all
+the data that needs to be carried over from one step to the next in the
+operation object. The application is then fully in control of how memory is
+allocated for the operation.</li>
+<li>In an implementation with isolation, pre-allocate memory for a predefined
+number of operations inside the cryptoprocessor.</li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Implementation considerations</a><ul>
+<li><a class="reference internal" href="#implementation-specific-aspects-of-the-interface">Implementation-specific aspects of the interface</a><ul>
+<li><a class="reference internal" href="#implementation-profile">Implementation profile</a></li>
+<li><a class="reference internal" href="#implementation-specific-types">Implementation-specific types</a></li>
+<li><a class="reference internal" href="#implementation-specific-macros">Implementation-specific macros</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#porting-to-a-platform">Porting to a platform</a><ul>
+<li><a class="reference internal" href="#platform-assumptions">Platform assumptions</a></li>
+<li><a class="reference internal" href="#platform-specific-types">Platform-specific types</a></li>
+<li><a class="reference internal" href="#cryptographic-hardware-support">Cryptographic hardware support</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#security-requirements-and-recommendations">Security requirements and recommendations</a><ul>
+<li><a class="reference internal" href="#error-detection">Error detection</a></li>
+<li><a class="reference internal" href="#indirect-object-references">Indirect object references</a></li>
+<li><a class="reference internal" href="#memory-cleanup">Memory cleanup</a></li>
+<li><a class="reference internal" href="#managing-key-material">Managing key material</a></li>
+<li><a class="reference internal" href="#safe-outputs-on-error">Safe outputs on error</a></li>
+<li><a class="reference internal" href="#attack-resistance">Attack resistance</a></li>
+</ul>
+</li>
+<li><a class="reference internal" href="#other-implementation-considerations">Other implementation considerations</a><ul>
+<li><a class="reference internal" href="#philosophy-of-resource-management">Philosophy of resource management</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="conventions.html" title="previous chapter">Library conventions</a></li>
+ <li>Next: <a href="usage.html" title="next chapter">Usage considerations</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/implementation.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/implementation.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/intro.html b/docs/html/overview/intro.html
new file mode 100644
index 0000000..dd5a664
--- /dev/null
+++ b/docs/html/overview/intro.html
@@ -0,0 +1,127 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Introduction — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Design goals" href="goals.html" />
+ <link rel="prev" title="PSA Cryptography API 1.0" href="../index.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="introduction">
+<h1>Introduction</h1>
+<p>Arm’s Platform Security Architecture (PSA) is a holistic set of threat models,
+security analyses, hardware and firmware architecture specifications, an
+open source firmware reference implementation, and an independent evaluation
+and certification scheme. PSA provides a recipe, based on
+industry best practice, that allows security to be consistently designed in, at
+both a hardware and firmware level.</p>
+<p>The PSA Cryptographic API (Crypto API) described in this document is an
+important PSA component that provides an interface to cryptographic operations
+on resource-constrained devices. The interface is user-friendly, while still
+providing access to the low-level primitives used in modern cryptography. It
+does not require that the user has access to the key material. Instead, it uses
+opaque key identifiers.</p>
+<p>This document is part of the PSA family of specifications. It defines an
+interface for cryptographic services, including cryptography primitives and a
+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>
+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>
+</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
+provide.</p>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper"><div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="../index.html" title="previous chapter">PSA Cryptography API 1.0</a></li>
+ <li>Next: <a href="goals.html" title="next chapter">Design goals</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/intro.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/intro.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/sample-arch.html b/docs/html/overview/sample-arch.html
new file mode 100644
index 0000000..855382d
--- /dev/null
+++ b/docs/html/overview/sample-arch.html
@@ -0,0 +1,212 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Sample architectures — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Library conventions" href="conventions.html" />
+ <link rel="prev" title="Functionality overview" href="functionality.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="sample-architectures">
+<span id="architectures"></span><h1>Sample architectures</h1>
+<p>This section describes some example architectures that can be used for
+implementations of the interface described in this specification. This list is
+not exhaustive and the section is entirely non-normative.</p>
+<div class="section" id="single-partition-architecture">
+<h2>Single-partition architecture</h2>
+<p>In the single-partition architecture, there is no security boundary inside the system. The
+application code can access all the system memory, including the memory used by
+the cryptographic services described in this specification. Thus, the
+architecture provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">no isolation</span></a>.</p>
+<p>This architecture does not conform to the Arm <em>Platform Security Architecture
+Security Model</em>. However, it is useful for providing cryptographic services
+that use the same interface, even on devices that cannot support any security
+boundary. So, while this architecture is not the primary design goal of the API
+defined in the present specification, it is supported.</p>
+<p>The functions in this specification simply execute the underlying algorithmic
+code. Security checks can be kept to a minimum, since the cryptoprocessor cannot
+defend against a malicious application. Key import and export copy data inside
+the same memory space.</p>
+<p>This architecture also describes a subset of some larger systems, where the
+cryptographic services are implemented inside a high-security partition,
+separate from the code of the main application, though it shares this
+high-security partition with other platform security services.</p>
+</div>
+<div class="section" id="cryptographic-token-and-single-application-processor">
+<span id="isolated-cryptoprocessor"></span><h2>Cryptographic token and single-application processor</h2>
+<p>This system is composed of two partitions: one is a cryptoprocessor and the
+other partition runs an application. There is a security boundary between the
+two partitions, so that the application cannot access the cryptoprocessor,
+except through its public interface. Thus, the architecture provides
+<a class="reference internal" href="goals.html#isolation"><span class="std std-ref">cryptoprocessor isolation</span></a>. The cryptoprocessor has
+some non-volatile storage, a TRNG, and possibly, some cryptographic accelerators.</p>
+<p>There are a number of potential physical realizations: the cryptoprocessor might
+be a separate chip, a separate processor on the same chip, or a logical
+partition using a combination of hardware and software to provide the isolation.
+These realizations are functionally equivalent in terms of the offered software
+interface, but they would typically offer different levels of security
+guarantees.</p>
+<p>The PSA crypto API in the application processor consists of a thin layer of code
+that translates function calls to remote procedure calls in the cryptoprocessor.
+All cryptographic computations are, therefore, performed inside the
+cryptoprocessor. Non-volatile keys are stored inside the cryptoprocessor.</p>
+</div>
+<div class="section" id="cryptoprocessor-with-no-key-storage">
+<h2>Cryptoprocessor with no key storage</h2>
+<p>As in the <em><a class="reference internal" href="#isolated-cryptoprocessor"><span class="std std-ref">Cryptographic token and single-application processor</span></a></em> architecture, this system
+is also composed of two partitions separated by a security boundary and also
+provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">cryptoprocessor isolation</span></a>.
+However, unlike the previous architecture, in this system, the cryptoprocessor
+does not have any secure, persistent storage that could be used to store
+application keys.</p>
+<p>If the cryptoprocessor is not capable of storing cryptographic material, then
+there is little use for a separate cryptoprocessor, since all data would have to
+be imported by the application.</p>
+<p>The cryptoprocessor can provide useful services if it is able to store at least
+one key. This might be a hardware unique key that is burnt to one-time
+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>
+</ul>
+</div>
+<div class="section" id="multi-client-cryptoprocessor">
+<h2>Multi-client cryptoprocessor</h2>
+<p>This is an expanded variant of the <a class="reference internal" href="#isolated-cryptoprocessor"><span class="std std-ref">cryptographic token plus application
+architecture</span></a>. In this
+variant, the cryptoprocessor serves multiple applications that are mutually
+untrustworthy. This architecture provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller
+isolation</span></a>.</p>
+<p>In this architecture, API calls are translated to remote procedure calls, which
+encode the identity of the client application. The cryptoprocessor carefully
+segments its internal storage to ensure that a client’s data is never leaked to
+another client.</p>
+</div>
+<div class="section" id="multi-cryptoprocessor-architecture">
+<h2>Multi-cryptoprocessor architecture</h2>
+<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.
+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>
+</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
+parameters supplied by the application, or based on considerations such as
+performance inside the implementation.</li>
+</ul>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Sample architectures</a><ul>
+<li><a class="reference internal" href="#single-partition-architecture">Single-partition architecture</a></li>
+<li><a class="reference internal" href="#cryptographic-token-and-single-application-processor">Cryptographic token and single-application processor</a></li>
+<li><a class="reference internal" href="#cryptoprocessor-with-no-key-storage">Cryptoprocessor with no key storage</a></li>
+<li><a class="reference internal" href="#multi-client-cryptoprocessor">Multi-client cryptoprocessor</a></li>
+<li><a class="reference internal" href="#multi-cryptoprocessor-architecture">Multi-cryptoprocessor architecture</a></li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="functionality.html" title="previous chapter">Functionality overview</a></li>
+ <li>Next: <a href="conventions.html" title="next chapter">Library conventions</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/sample-arch.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/sample-arch.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/overview/usage.html b/docs/html/overview/usage.html
new file mode 100644
index 0000000..306bcee
--- /dev/null
+++ b/docs/html/overview/usage.html
@@ -0,0 +1,171 @@
+
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+
+<html xmlns="http://www.w3.org/1999/xhtml">
+ <head>
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
+ <title>Usage considerations — PSA Crypto API 1.0.0 documentation</title>
+ <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../',
+ VERSION: '1.0.0',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: true,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../_static/jquery.js"></script>
+ <script type="text/javascript" src="../_static/underscore.js"></script>
+ <script type="text/javascript" src="../_static/doctools.js"></script>
+ <link rel="index" title="Index" href="../genindex.html" />
+ <link rel="search" title="Search" href="../search.html" />
+ <link rel="next" title="Library management reference" href="../api/library/index.html" />
+ <link rel="prev" title="Implementation considerations" href="implementation.html" />
+
+ <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
+
+ <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
+
+ </head>
+ <body>
+
+
+ <div class="document">
+ <div class="documentwrapper">
+ <div class="bodywrapper">
+ <div class="body" role="main">
+
+ <div class="section" id="usage-considerations">
+<span id="id1"></span><h1>Usage considerations</h1>
+<div class="section" id="security-recommendations">
+<h2>Security recommendations</h2>
+<div class="section" id="always-check-for-errors">
+<h3>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>
+<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
+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
+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
+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.
+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
+standards require periodic reseeding from a hardware random generator, which
+can fail.</li>
+</ul>
+</div>
+<div class="section" id="shared-memory-and-concurrency">
+<h3>Shared memory and concurrency</h3>
+<p>Some environments allow applications to be multithreaded, while others do not.
+In some environments, applications can share memory with a different security
+context. In environments with multithreaded applications or shared memory,
+applications must be written carefully to avoid data corruption or leakage. This
+specification requires the application to obey certain constraints.</p>
+<p>In general, this API allows either one writer or any number of simultaneous
+readers, on any given object. In other words, if two or more calls access the
+same object concurrently, then the behavior is only well-defined if all the
+calls are only reading from the object and do not modify it. Read accesses
+include reading memory by input parameters and reading keystore content by using
+a key. For more details, refer to the <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>
+section.</p>
+<p>If an application shares memory with another security context, it can pass
+shared memory blocks as input buffers or output buffers, but not as non-buffer
+parameters. For more details, refer to the <em><a class="reference internal" href="conventions.html#stability-of-parameters"><span class="std std-ref">Stability of parameters</span></a></em> section.</p>
+</div>
+<div class="section" id="cleaning-up-after-use">
+<h3>Cleaning up after use</h3>
+<p>To minimize impact if the system is compromised, it is recommended that
+applications wipe all sensitive data from memory when it is no longer used. That
+way, only data that is currently in use can be leaked, and past data is not
+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>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper">
+ <h3><a href="../index.html">Table Of Contents</a></h3>
+ <ul>
+<li><a class="reference internal" href="#">Usage considerations</a><ul>
+<li><a class="reference internal" href="#security-recommendations">Security recommendations</a><ul>
+<li><a class="reference internal" href="#always-check-for-errors">Always check for errors</a></li>
+<li><a class="reference internal" href="#shared-memory-and-concurrency">Shared memory and concurrency</a></li>
+<li><a class="reference internal" href="#cleaning-up-after-use">Cleaning up after use</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<div class="relations">
+<h3>Related Topics</h3>
+<ul>
+ <li><a href="../index.html">Documentation overview</a><ul>
+ <li>Previous: <a href="implementation.html" title="previous chapter">Implementation considerations</a></li>
+ <li>Next: <a href="../api/library/index.html" title="next chapter">Library management reference</a></li>
+ </ul></li>
+</ul>
+</div>
+ <div role="note" aria-label="source link">
+ <h3>This Page</h3>
+ <ul class="this-page-menu">
+ <li><a href="../_sources/overview/usage.rst.txt"
+ rel="nofollow">Show Source</a></li>
+ </ul>
+ </div>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../search.html" method="get">
+ <div><input type="text" name="q" /></div>
+ <div><input type="submit" value="Go" /></div>
+ <input type="hidden" name="check_keywords" value="yes" />
+ <input type="hidden" name="area" value="default" />
+ </form>
+</div>
+<script type="text/javascript">$('#searchbox').show(0);</script>
+ </div>
+ </div>
+ <div class="clearer"></div>
+ </div>
+ <div class="footer">
+ © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ |
+ <a href="../_sources/overview/usage.rst.txt"
+ rel="nofollow">Page source</a>
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file