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/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