Update PSA API specification to 1.0.1
Generated according to the instructions in update_psa_crypto_api.sh
using the tag psa-crypto-api-1.0.1.
Signed-off-by: Gilles Peskine <Gilles.Peskine@arm.com>
diff --git a/docs/html/api/ops/aead.html b/docs/html/api/ops/aead.html
index 720a890..a150b20 100644
--- a/docs/html/api/ops/aead.html
+++ b/docs/html/api/ops/aead.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Authenticated encryption with associated data (AEAD) — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.5. Authenticated encryption with associated data (AEAD) — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Key derivation" href="kdf.html" />
- <link rel="prev" title="Unauthenticated ciphers" href="ciphers.html" />
+ <link rel="next" title="10.6. Key derivation" href="kdf.html" />
+ <link rel="prev" title="10.4. Unauthenticated ciphers" href="ciphers.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,37 +41,52 @@
<div class="body" role="main">
<div class="section" id="authenticated-encryption-with-associated-data-aead">
-<span id="aead"></span><h1>Authenticated encryption with associated data (AEAD)</h1>
+<span id="aead"></span><h1>10.5. Authenticated encryption with associated data (AEAD)</h1>
<div class="section" id="aead-algorithms">
-<span id="id1"></span><h2>AEAD algorithms</h2>
+<span id="id1"></span><h2>10.5.1. AEAD algorithms</h2>
<div class="section" id="PSA_ALG_CCM">
<span id="c.PSA_ALG_CCM"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code> (macro)</h3>
-<p>The CCM authenticated encryption algorithm.</p>
+<p>The <em>Counter with CBC-MAC</em> (CCM) authenticated encryption algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM">PSA_ALG_CCM</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500100)
+#define <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM">PSA_ALG_CCM</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500100)
</pre>
-<p>The underlying block cipher is determined by the key type.</p>
+<p>CCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.</p>
+<p>To use <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a> with a multi-part AEAD operation, the application must call <a class="reference internal" href="#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> before providing the nonce, the additional data and plaintext to the operation.</p>
+<p>CCM requires a nonce of between 7 and 13 bytes in length. The length of the nonce depends on the length of the plaintext:</p>
+<ul class="simple">
+<li>CCM encodes the plaintext length <em>pLen</em> in <em>L</em> octets, with <em>L</em> the smallest integer >= 2 where <em>pLen</em> < 2^(8<em>L</em>).</li>
+<li>The nonce length is then 15 - <em>L</em> bytes.</li>
+</ul>
+<p>If the application is generating a random nonce using <a class="reference internal" href="#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>, the size of the generated nonce is 15 - <em>L</em> bytes.</p>
+<p>CCM supports authentication tag sizes of 4, 6, 8, 10, 12, 14, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">tag_length</span></code><code class="docutils literal"><span class="pre">)</span></code>, where <code class="docutils literal"><span class="pre">tag_length</span></code> is a valid CCM tag length.</p>
+<p>The CCM block cipher mode is defined in <span><em>Counter with CBC-MAC (CCM)</em> <a class="reference internal" href="../../about.html#citation-rfc3610"><span class="cite">[RFC3610]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_GCM">
<span id="c.PSA_ALG_GCM"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code> (macro)</h3>
-<p>The GCM authenticated encryption algorithm.</p>
+<p>The <em>Galois/Counter Mode</em> (GCM) authenticated encryption algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM">PSA_ALG_GCM</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500200)
+#define <a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM">PSA_ALG_GCM</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05500200)
</pre>
-<p>The underlying block cipher is determined by the key type.</p>
+<p>GCM is defined for block ciphers that have a 128-bit block size. The underlying block cipher is determined by the key type.</p>
+<p>GCM requires a nonce of at least 1 byte in length. The maximum supported nonce size is <a class="reference internal" href="../../about.html#term-implementation-defined"><span class="scterm">implementation defined</span></a>. Calling <a class="reference internal" href="#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> will generate a random 12-byte nonce.</p>
+<p>GCM supports authentication tag sizes of 4, 8, 12, 13, 14, 15, and 16 bytes. The default tag length is 16. Shortened tag lengths can be requested using <a class="reference internal" href="#c.PSA_ALG_AEAD_WITH_SHORTENED_TAG" title="PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="#c.PSA_ALG_GCM" title="PSA_ALG_GCM"><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code></a><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">tag_length</span></code><code class="docutils literal"><span class="pre">)</span></code>, where <code class="docutils literal"><span class="pre">tag_length</span></code> is a valid GCM tag length.</p>
+<p>The GCM block cipher mode is defined in <span><em>NIST Special Publication 800-38D: Recommendation for Block Cipher Modes of Operation: Galois/Counter Mode (GCM) and GMAC</em> <a class="reference internal" href="../../about.html#citation-sp800-38d"><span class="cite">[SP800-38D]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_CHACHA20_POLY1305">
<span id="c.PSA_ALG_CHACHA20_POLY1305"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code> (macro)</h3>
-<p>The Chacha20-Poly1305 AEAD algorithm.</p>
+<p>The ChaCha20-Poly1305 AEAD algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CHACHA20_POLY1305" title="PSA_ALG_CHACHA20_POLY1305">PSA_ALG_CHACHA20_POLY1305</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05100500)
+#define <a class="reference internal" href="#c.PSA_ALG_CHACHA20_POLY1305" title="PSA_ALG_CHACHA20_POLY1305">PSA_ALG_CHACHA20_POLY1305</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x05100500)
</pre>
-<p>The ChaCha20_Poly1305 construction is defined in <a class="reference external" href="https://tools.ietf.org/html/rfc7539.html">RFC 7539</a>.</p>
-<p>Variants of this algorithm are defined by the length of the nonce:</p>
+<p>There are two defined variants of ChaCha20-Poly1305:</p>
<ul class="simple">
-<li>Implementations must support a 12-byte nonce, as defined in <a class="reference external" href="https://tools.ietf.org/html/rfc7539.html">RFC 7539</a>.</li>
-<li>Implementations can optionally support an 8-byte nonce, the original variant.</li>
-<li>It is recommended that implementations do not support other sizes of nonce.</li>
+<li>An implementation that supports ChaCha20-Poly1305 must support the variant defined by <span><em>ChaCha20 and Poly1305 for IETF Protocols</em> <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a></span>, which has a 96-bit nonce and 32-bit counter.</li>
+<li>An implementation can optionally also support the original variant defined by <span><em>ChaCha, a variant of Salsa20</em> <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a></span>, which has a 64-bit nonce and 64-bit counter.</li>
+</ul>
+<p>The variant used for the AEAD encryption or decryption operation, depends on the nonce provided for an AEAD operation using <a class="reference internal" href="#c.PSA_ALG_CHACHA20_POLY1305" title="PSA_ALG_CHACHA20_POLY1305"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code></a>:</p>
+<ul class="simple">
+<li>A nonce provided in a call to <a class="reference internal" href="#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>, <a class="reference internal" href="#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> or <a class="reference internal" href="#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> must be 8 or 12 bytes. The size of nonce will select the appropriate variant of the algorithm.</li>
+<li>A nonce generated by a call to <a class="reference internal" href="#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> will be 12 bytes, and will use the <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a> variant.</li>
</ul>
<p>Implementations must support 16-byte tags. It is recommended that truncated tag sizes are rejected.</p>
</div>
@@ -84,7 +100,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">aead_alg</span></code></dt>
-<dd>An AEAD algorithm identifier (value of type <a class="reference internal" href="../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> such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">tag_length</span></code></dt>
<dd>Desired length of the authentication tag in bytes.</dd>
</dl>
@@ -97,13 +113,13 @@
</div>
</div>
<div class="section" id="single-part-aead-functions">
-<h2>Single-part AEAD functions</h2>
+<h2>10.5.2. Single-part AEAD functions</h2>
<div class="section" id="psa_aead_encrypt">
<span id="c.psa_aead_encrypt"></span><h3><code class="docutils literal"><span class="pre">psa_aead_encrypt</span></code> (function)</h3>
<p>Process an authenticated encryption operation.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt">psa_aead_encrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_encrypt" title="psa_aead_encrypt">psa_aead_encrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * nonce,
size_t nonce_length,
const uint8_t * additional_data,
@@ -118,9 +134,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">nonce</span></code></dt>
<dd>Nonce or IV to use.</dd>
<dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt>
@@ -152,7 +168,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -181,8 +197,8 @@
<span id="c.psa_aead_decrypt"></span><h3><code class="docutils literal"><span class="pre">psa_aead_decrypt</span></code> (function)</h3>
<p>Process an authenticated decryption operation.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt">psa_aead_decrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_decrypt" title="psa_aead_decrypt">psa_aead_decrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * nonce,
size_t nonce_length,
const uint8_t * additional_data,
@@ -197,9 +213,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">nonce</span></code></dt>
<dd>Nonce or IV to use.</dd>
<dt> <code class="docutils literal"><span class="pre">nonce_length</span></code></dt>
@@ -233,7 +249,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
<dd>The ciphertext is not authentic.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -260,7 +276,7 @@
</div>
</div>
<div class="section" id="multi-part-aead-operations">
-<h2>Multi-part AEAD operations</h2>
+<h2>10.5.3. Multi-part AEAD operations</h2>
<div class="admonition warning" id="aead-multi-part-warning">
<p class="first admonition-title">Warning</p>
<p>When decrypting using a multi-part AEAD operation, there is no guarantee that the input or output is valid until <a class="reference internal" href="#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 class="reference internal" href="../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>
@@ -326,8 +342,8 @@
<p>Set the key for a multi-part authenticated encryption operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup">psa_aead_encrypt_setup</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -335,9 +351,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -348,7 +364,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -394,8 +410,8 @@
<p>Set the key for a multi-part authenticated decryption operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup">psa_aead_decrypt_setup</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -403,9 +419,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The AEAD algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -416,7 +432,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -457,6 +473,51 @@
<li>A call to <a class="reference internal" href="#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>.</li>
</ul>
</div>
+<div class="section" id="psa_aead_set_lengths">
+<span id="c.psa_aead_set_lengths"></span><h3><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</h3>
+<p>Declare the lengths of the message and additional data for AEAD.</p>
+<pre class="literal-block">
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths">psa_aead_set_lengths</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation,
+ size_t ad_length,
+ size_t plaintext_length);
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
+<dd>Active AEAD operation.</dd>
+<dt> <code class="docutils literal"><span class="pre">ad_length</span></code></dt>
+<dd>Size of the non-encrypted additional authenticated data in bytes.</dd>
+<dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt>
+<dd>Size of the plaintext to encrypt in bytes.</dd>
+</dl>
+<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
+<dl class="docutils">
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
+<dd>Success.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
+<dd>The operation state is not valid: it must be active, and <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not have been called yet.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
+<dd>At least one of the lengths is not acceptable for the chosen algorithm.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
+<dd></dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
+<dd></dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
+<dd></dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
+<dd></dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
+<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
+</dl>
+<p class="rubric">Description</p>
+<p>The application must call this function before calling <a class="reference internal" href="#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> or <a class="reference internal" href="#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>, if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.</p>
+<ul class="simple">
+<li>For <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a>, calling this function is required.</li>
+<li>For the other AEAD algorithms defined in this specification, calling this function is not required.</li>
+<li>For vendor-defined algorithm, refer to the vendor documentation.</li>
+</ul>
+<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>
+</div>
<div class="section" id="psa_aead_generate_nonce">
<span id="c.psa_aead_generate_nonce"></span><h3><code class="docutils literal"><span class="pre">psa_aead_generate_nonce</span></code> (function)</h3>
<p>Generate a random nonce for an authenticated encryption operation.</p>
@@ -483,6 +544,8 @@
<dd>Success.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
+<dd>The operation state is not valid: this is an algorithm which requires <a class="reference internal" href="#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 be called before setting the nonce.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">nonce</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_AEAD_NONCE_LENGTH" title="PSA_AEAD_NONCE_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_AEAD_NONCE_MAX_SIZE" title="PSA_AEAD_NONCE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
@@ -504,7 +567,7 @@
</dl>
<p class="rubric">Description</p>
<p>This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.</p>
-<p>The application must call <a class="reference internal" href="#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> before calling this function.</p>
+<p>The application must call <a class="reference internal" href="#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> before calling this function. If applicable for the algorithm, the application must call <a class="reference internal" href="#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> before calling this function.</p>
<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>
</div>
<div class="section" id="psa_aead_set_nonce">
@@ -530,6 +593,8 @@
<dd>Success.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The operation state is not valid: it must be active, with no nonce set.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
+<dd>The operation state is not valid: this is an algorithm which requires <a class="reference internal" href="#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 be called before setting the nonce.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd>The size of <code class="docutils literal"><span class="pre">nonce</span></code> is not acceptable for the chosen algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
@@ -551,59 +616,13 @@
</dl>
<p class="rubric">Description</p>
<p>This function sets the nonce for the authenticated encryption or decryption operation.</p>
-<p>The application must call <a class="reference internal" href="#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="#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> before calling this function.</p>
+<p>The application must call <a class="reference internal" href="#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="#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> before calling this function. If applicable for the algorithm, the application must call <a class="reference internal" href="#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> before calling this function.</p>
<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">When encrypting, <a class="reference internal" href="#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> is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.</p>
</div>
</div>
-<div class="section" id="psa_aead_set_lengths">
-<span id="c.psa_aead_set_lengths"></span><h3><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</h3>
-<p>Declare the lengths of the message and additional data for AEAD.</p>
-<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_aead_set_lengths" title="psa_aead_set_lengths">psa_aead_set_lengths</a>(<a class="reference internal" href="#c.psa_aead_operation_t" title="psa_aead_operation_t">psa_aead_operation_t</a> * operation,
- size_t ad_length,
- size_t plaintext_length);
-</pre>
-<p class="rubric">Parameters</p>
-<dl class="docutils">
-<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
-<dd>Active AEAD operation.</dd>
-<dt> <code class="docutils literal"><span class="pre">ad_length</span></code></dt>
-<dd>Size of the non-encrypted additional authenticated data in bytes.</dd>
-<dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt>
-<dd>Size of the plaintext to encrypt in bytes.</dd>
-</dl>
-<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
-<dl class="docutils">
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
-<dd>Success.</dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
-<dd>The operation state is not valid: it must be active, and <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not have been called yet.</dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
-<dd>At least one of the lengths is not acceptable for the chosen algorithm.</dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
-<dd></dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
-<dd></dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt>
-<dd></dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
-<dd></dd>
-<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
-<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
-</dl>
-<p class="rubric">Description</p>
-<p>The application must call this function before calling <a class="reference internal" href="#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> or <a class="reference internal" href="#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> if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.</p>
-<p>This function can be called before or after setting the nonce with <a class="reference internal" href="#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> or <a class="reference internal" href="#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>.</p>
-<ul class="simple">
-<li>For <a class="reference internal" href="#c.PSA_ALG_CCM" title="PSA_ALG_CCM"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CCM</span></code></a>, calling this function is required.</li>
-<li>For the other AEAD algorithms defined in this specification, calling this function is not required.</li>
-<li>For vendor-defined algorithm, refer to the vendor documentation.</li>
-</ul>
-<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>
-</div>
<div class="section" id="psa_aead_update_ad">
<span id="c.psa_aead_update_ad"></span><h3><code class="docutils literal"><span class="pre">psa_aead_update_ad</span></code> (function)</h3>
<p>Pass additional data to an active AEAD operation.</p>
@@ -927,7 +946,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.5.4. Support macros</h2>
<div class="section" id="PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER">
<span id="c.PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</span></code> (macro)</h3>
<p>Whether the specified algorithm is an AEAD mode on a block cipher.</p>
@@ -937,7 +956,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an AEAD algorithm which is an AEAD mode based on a block cipher, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -953,7 +972,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">aead_alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding AEAD algorithm with the default tag length for that algorithm.</p>
@@ -972,7 +991,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">plaintext_length</span></code></dt>
<dd>Size of the plaintext in bytes.</dd>
</dl>
@@ -1010,7 +1029,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">ciphertext_length</span></code></dt>
<dd>Size of the ciphertext in bytes.</dd>
</dl>
@@ -1047,7 +1066,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The default nonce size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p>
@@ -1075,7 +1094,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the input in bytes.</dd>
</dl>
@@ -1113,7 +1132,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient ciphertext buffer size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p>
@@ -1143,7 +1162,7 @@
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the AEAD key in bits.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The tag length for the specified algorithm and key.
@@ -1172,7 +1191,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>An AEAD algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient plaintext buffer size for the specified key type and algorithm. If the key type or AEAD algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and AEAD algorithm that it recognizes, but does not support.</p>
@@ -1196,78 +1215,52 @@
</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="#">Authenticated encryption with associated data (AEAD)</a><ul>
-<li><a class="reference internal" href="#aead-algorithms">AEAD algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_CCM"><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_GCM"><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CHACHA20_POLY1305"><code class="docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#single-part-aead-functions">Single-part AEAD functions</a><ul>
-<li><a class="reference internal" href="#psa_aead_encrypt"><code class="docutils literal"><span class="pre">psa_aead_encrypt</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_decrypt"><code class="docutils literal"><span class="pre">psa_aead_decrypt</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#multi-part-aead-operations">Multi-part AEAD operations</a><ul>
-<li><a class="reference internal" href="#psa_aead_operation_t"><code class="docutils literal"><span class="pre">psa_aead_operation_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#psa_aead_operation_init"><code class="docutils literal"><span class="pre">psa_aead_operation_init</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_encrypt_setup"><code class="docutils literal"><span class="pre">psa_aead_encrypt_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_decrypt_setup"><code class="docutils literal"><span class="pre">psa_aead_decrypt_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_generate_nonce"><code class="docutils literal"><span class="pre">psa_aead_generate_nonce</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_set_nonce"><code class="docutils literal"><span class="pre">psa_aead_set_nonce</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_set_lengths"><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_update_ad"><code class="docutils literal"><span class="pre">psa_aead_update_ad</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_update"><code class="docutils literal"><span class="pre">psa_aead_update</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_finish"><code class="docutils literal"><span class="pre">psa_aead_finish</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_verify"><code class="docutils literal"><span class="pre">psa_aead_verify</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_aead_abort"><code class="docutils literal"><span class="pre">psa_aead_abort</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_NONCE_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_NONCE_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_NONCE_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_UPDATE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_FINISH_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_FINISH_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_TAG_LENGTH"><code class="docutils literal"><span class="pre">PSA_AEAD_TAG_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_TAG_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_TAG_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_VERIFY_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="ciphers.html" title="previous chapter">Unauthenticated ciphers</a></li>
- <li>Next: <a href="kdf.html" title="next chapter">Key derivation</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/aead.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.5. Authenticated encryption with associated data (AEAD)</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#aead-algorithms">10.5.1. AEAD algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#single-part-aead-functions">10.5.2. Single-part AEAD functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#multi-part-aead-operations">10.5.3. Multi-part AEAD operations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.5.4. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -1283,15 +1276,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/aead.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/algorithms.html b/docs/html/api/ops/algorithms.html
new file mode 100644
index 0000000..58fdae7
--- /dev/null
+++ b/docs/html/api/ops/algorithms.html
@@ -0,0 +1,349 @@
+
+<!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>10.1. Algorithms — PSA Crypto API 1.0.1 documentation</title>
+ <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
+ <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
+ <script type="text/javascript">
+ var DOCUMENTATION_OPTIONS = {
+ URL_ROOT: '../../',
+ VERSION: '1.0.1',
+ COLLAPSE_INDEX: false,
+ FILE_SUFFIX: '.html',
+ HAS_SOURCE: false,
+ SOURCELINK_SUFFIX: '.txt'
+ };
+ </script>
+ <script type="text/javascript" src="../../_static/jquery.js"></script>
+ <script type="text/javascript" src="../../_static/underscore.js"></script>
+ <script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
+ <link rel="index" title="Index" href="../../genindex.html" />
+ <link rel="search" title="Search" href="../../search.html" />
+ <link rel="next" title="10.2. Message digests" href="hashes.html" />
+ <link rel="prev" title="10. Cryptographic operation reference" 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="algorithms">
+<span id="id1"></span><h1>10.1. Algorithms</h1>
+<p>This specification encodes algorithms into a structured 32-bit integer value.</p>
+<p>Algorithm identifiers are used for two purposes in this API:</p>
+<ol class="arabic simple">
+<li>To specify a specific algorithm to use in a cryptographic operation. These are all defined in <a class="reference internal" href="index.html#crypto-operations"><span class="secref">Cryptographic operation reference</span></a>.</li>
+<li>To specify the policy for a key, identifying the permitted algorithm for use with the key. This use is described in <a class="reference internal" href="../keys/policy.html#key-policy"><span class="secref">Key policies</span></a>.</li>
+</ol>
+<p>The specific algorithm identifiers are described alongside the cryptographic operation functions to which they apply:</p>
+<ul class="simple">
+<li><a class="reference internal" href="hashes.html#hash-algorithms"><span class="secref">Hash algorithms</span></a></li>
+<li><a class="reference internal" href="macs.html#mac-algorithms"><span class="secref">MAC algorithms</span></a></li>
+<li><a class="reference internal" href="ciphers.html#cipher-algorithms"><span class="secref">Cipher algorithms</span></a></li>
+<li><a class="reference internal" href="aead.html#aead-algorithms"><span class="secref">AEAD algorithms</span></a></li>
+<li><a class="reference internal" href="kdf.html#key-derivation-algorithms"><span class="secref">Key derivation algorithms</span></a></li>
+<li><a class="reference internal" href="sign.html#sign-algorithms"><span class="secref">Asymmetric signature algorithms</span></a></li>
+<li><a class="reference internal" href="pke.html#asymmetric-encryption-algorithms"><span class="secref">Asymmetric encryption algorithms</span></a></li>
+<li><a class="reference internal" href="ka.html#key-agreement-algorithms"><span class="secref">Key agreement algorithms</span></a></li>
+</ul>
+<div class="section" id="algorithm-encoding">
+<h2>10.1.1. Algorithm encoding</h2>
+<div class="section" id="psa_algorithm_t">
+<span id="c.psa_algorithm_t"></span><h3><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code> (type)</h3>
+<p>Encoding of a cryptographic algorithm.</p>
+<pre class="literal-block">
+typedef uint32_t <a class="reference internal" href="#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>;
+</pre>
+<p>This is a structured bitfield that identifies the category and type of algorithm. The range of algorithm identifier values is divided as follows:</p>
+<dl class="docutils">
+<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x00000000</span></code></dt>
+<dd>Reserved as an invalid algorithm identifier.</dd>
+<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x00000001</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">x7fffffff</span></code></dt>
+<dd>Specification-defined algorithm identifiers.
+Algorithm identifiers defined by this standard always have bit 31 clear.
+Unallocated algorithm identifier values in this range are reserved for future use.</dd>
+<dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x80000000</span></code><code class="docutils literal"> <span class="pre">-</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">xffffffff</span></code></dt>
+<dd>Implementation-defined algorithm identifiers.
+Implementations that define additional algorithms must use an encoding with bit 31 set.
+The related support macros will be easier to write if these algorithm identifier encodings also respect the bitwise structure used by standard encodings.</dd>
+</dl>
+<p>For algorithms that can be applied to multiple key types, this identifier does not encode the key type. For example, for symmetric ciphers based on a block cipher, <a class="reference internal" href="#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> encodes the block cipher mode and the padding mode while the block cipher itself is encoded via <a class="reference internal" href="../keys/types.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a>.</p>
+</div>
+<div class="section" id="PSA_ALG_NONE">
+<span id="c.PSA_ALG_NONE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_NONE</span></code> (macro)</h3>
+<p>An invalid algorithm identifier value.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_NONE" title="PSA_ALG_NONE">PSA_ALG_NONE</a> ((<a class="reference internal" href="#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0)
+</pre>
+<p>Zero is not the encoding of any algorithm.</p>
+</div>
+</div>
+<div class="section" id="algorithm-categories">
+<h2>10.1.2. Algorithm categories</h2>
+<div class="section" id="PSA_ALG_IS_HASH">
+<span id="c.PSA_ALG_IS_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code> (macro)</h3>
+<p>Whether the specified algorithm is a hash algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH">PSA_ALG_IS_HASH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="hashes.html#hash-algorithms"><span class="secref">Hash algorithms</span></a> for a list of defined hash algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_MAC">
+<span id="c.PSA_ALG_IS_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code> (macro)</h3>
+<p>Whether the specified algorithm is a MAC algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC">PSA_ALG_IS_MAC</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a MAC algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="macs.html#mac-algorithms"><span class="secref">MAC algorithms</span></a> for a list of defined MAC algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_CIPHER">
+<span id="c.PSA_ALG_IS_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code> (macro)</h3>
+<p>Whether the specified algorithm is a symmetric cipher algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER">PSA_ALG_IS_CIPHER</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a symmetric cipher algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="ciphers.html#cipher-algorithms"><span class="secref">Cipher algorithms</span></a> for a list of defined cipher algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_AEAD">
+<span id="c.PSA_ALG_IS_AEAD"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code> (macro)</h3>
+<p>Whether the specified algorithm is an authenticated encryption with associated data (AEAD) algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_AEAD" title="PSA_ALG_IS_AEAD">PSA_ALG_IS_AEAD</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an AEAD algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="aead.html#aead-algorithms"><span class="secref">AEAD algorithms</span></a> for a list of defined AEAD algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_SIGN">
+<span id="c.PSA_ALG_IS_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN</span></code> (macro)</h3>
+<p>Whether the specified algorithm is an asymmetric signature algorithm, also known as public-key signature algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_SIGN" title="PSA_ALG_IS_SIGN">PSA_ALG_IS_SIGN</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an asymmetric signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="sign.html#sign-algorithms"><span class="secref">Asymmetric signature algorithms</span></a> for a list of defined signature algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_ASYMMETRIC_ENCRYPTION">
+<span id="c.PSA_ALG_IS_ASYMMETRIC_ENCRYPTION"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_ASYMMETRIC_ENCRYPTION</span></code> (macro)</h3>
+<p>Whether the specified algorithm is an asymmetric encryption algorithm, also known as public-key encryption algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_ASYMMETRIC_ENCRYPTION" title="PSA_ALG_IS_ASYMMETRIC_ENCRYPTION">PSA_ALG_IS_ASYMMETRIC_ENCRYPTION</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an asymmetric encryption algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="pke.html#asymmetric-encryption-algorithms"><span class="secref">Asymmetric encryption algorithms</span></a> for a list of defined asymmetric encryption algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_KEY_AGREEMENT">
+<span id="c.PSA_ALG_IS_KEY_AGREEMENT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code> (macro)</h3>
+<p>Whether the specified algorithm is a key agreement algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT">PSA_ALG_IS_KEY_AGREEMENT</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="ka.html#key-agreement-algorithms"><span class="secref">Key agreement algorithms</span></a> for a list of defined key agreement algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_KEY_DERIVATION">
+<span id="c.PSA_ALG_IS_KEY_DERIVATION"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code> (macro)</h3>
+<p>Whether the specified algorithm is a key derivation algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION">PSA_ALG_IS_KEY_DERIVATION</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a key derivation algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>See <a class="reference internal" href="kdf.html#key-derivation-algorithms"><span class="secref">Key derivation algorithms</span></a> for a list of defined key derivation algorithms.</p>
+</div>
+<div class="section" id="PSA_ALG_IS_WILDCARD">
+<span id="c.PSA_ALG_IS_WILDCARD"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD</span></code> (macro)</h3>
+<p>Whether the specified algorithm encoding is a wildcard.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_IS_WILDCARD" title="PSA_ALG_IS_WILDCARD">PSA_ALG_IS_WILDCARD</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a wildcard algorithm encoding.</p>
+<p><code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a non-wildcard algorithm encoding that is suitable for an operation.</p>
+<p>This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
+<p class="rubric">Description</p>
+<p>Wildcard algorithm values can only be used to set the permitted algorithm field in a key policy, wildcard values cannot be used to perform an operation.</p>
+<p>See <a class="reference internal" href="sign.html#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> for example of how a wildcard algorithm can be used in a key policy.</p>
+</div>
+<div class="section" id="PSA_ALG_GET_HASH">
+<span id="c.PSA_ALG_GET_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code> (macro)</h3>
+<p>Get the hash used by a composite algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH">PSA_ALG_GET_HASH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
+</pre>
+<p class="rubric">Parameters</p>
+<dl class="docutils">
+<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="#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>).</dd>
+</dl>
+<p class="rubric">Returns</p>
+<p>The underlying hash algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a composite algorithm that uses a hash algorithm.</p>
+<p><a class="reference internal" href="#c.PSA_ALG_NONE" title="PSA_ALG_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_NONE</span></code></a> if <code class="docutils literal"><span class="pre">alg</span></code> is not a composite algorithm that uses a hash.</p>
+<p class="rubric">Description</p>
+<p>The following composite algorithms require a hash algorithm:</p>
+<ul class="simple">
+<li><a class="reference internal" href="sign.html#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a></li>
+<li><a class="reference internal" href="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></li>
+<li><a class="reference internal" href="macs.html#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_HMAC()</span></code></a></li>
+<li><a class="reference internal" href="pke.html#c.PSA_ALG_RSA_OAEP" title="PSA_ALG_RSA_OAEP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_OAEP()</span></code></a></li>
+<li><a class="reference internal" href="sign.html#c.PSA_ALG_IS_RSA_PKCS1V15_SIGN" title="PSA_ALG_IS_RSA_PKCS1V15_SIGN"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN()</span></code></a></li>
+<li><a class="reference internal" href="sign.html#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_RSA_PSS()</span></code></a></li>
+<li><a class="reference internal" href="kdf.html#c.PSA_ALG_TLS12_PRF" title="PSA_ALG_TLS12_PRF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_TLS12_PRF()</span></code></a></li>
+<li><a class="reference internal" href="kdf.html#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS()</span></code></a></li>
+</ul>
+</div>
+</div>
+</div>
+
+
+ </div>
+ </div>
+ </div>
+ <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
+</ul>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.1. Algorithms</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#algorithm-encoding">10.1.1. Algorithm encoding</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#algorithm-categories">10.1.2. Algorithm categories</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
+<div id="searchbox" style="display: none" role="search">
+ <h3>Quick search</h3>
+ <form class="search" action="../../search.html" method="get">
+ <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">
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
+
+ |
+ Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
+ & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
+
+ </div>
+
+
+
+
+ </body>
+</html>
\ No newline at end of file
diff --git a/docs/html/api/ops/ciphers.html b/docs/html/api/ops/ciphers.html
index 7826c94..56bc7f2 100644
--- a/docs/html/api/ops/ciphers.html
+++ b/docs/html/api/ops/ciphers.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Unauthenticated ciphers — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.4. Unauthenticated ciphers — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Authenticated encryption with associated data (AEAD)" href="aead.html" />
- <link rel="prev" title="Message authentication codes (MAC)" href="macs.html" />
+ <link rel="next" title="10.5. Authenticated encryption with associated data (AEAD)" href="aead.html" />
+ <link rel="prev" title="10.3. Message authentication codes (MAC)" href="macs.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,101 +41,168 @@
<div class="body" role="main">
<div class="section" id="unauthenticated-ciphers">
-<span id="ciphers"></span><h1>Unauthenticated ciphers</h1>
+<span id="ciphers"></span><h1>10.4. Unauthenticated ciphers</h1>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p>The unauthenticated cipher API is provided to implement legacy protocols and
for use cases where the data integrity and authenticity is guaranteed by
non-cryptographic means.</p>
-<p class="last">It is recommended that newer protocols use <em><a class="reference internal" href="aead.html#aead"><span class="std std-ref">Authenticated encryption with associated data (AEAD)</span></a></em>.</p>
+<p class="last">It is recommended that newer protocols use <a class="reference internal" href="aead.html#aead"><span class="secref">Authenticated encryption with associated data (AEAD)</span></a>.</p>
</div>
<div class="section" id="cipher-algorithms">
-<span id="id1"></span><h2>Cipher algorithms</h2>
+<span id="id1"></span><h2>10.4.1. Cipher algorithms</h2>
<div class="section" id="PSA_ALG_STREAM_CIPHER">
<span id="c.PSA_ALG_STREAM_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</h3>
<p>The stream cipher mode of a stream cipher algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER">PSA_ALG_STREAM_CIPHER</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04800100)
+#define <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER">PSA_ALG_STREAM_CIPHER</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04800100)
</pre>
-<p>The underlying stream cipher is determined by the key type:</p>
+<p>The underlying stream cipher is determined by the key type. The ARC4 and ChaCha20 ciphers use this algorithm identifier.</p>
+<p class="rubric">ARC4</p>
+<p>To use ARC4, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</p>
+<div class="admonition warning">
+<p class="first admonition-title">Warning</p>
+<p class="last">The ARC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.</p>
+</div>
+<p>The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with the <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a> algorithm and an ARC4 key, <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not be called.</p>
+<p class="rubric">ChaCha20</p>
+<p>To use ChaCha20, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</p>
+<p>Implementations must support the variant that is defined in <span><em>ChaCha20 and Poly1305 for IETF Protocols</em> <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc7539.html#section-2.4">§2.4</a>, which has a 96-bit nonce and a 32-bit counter. Implementations can optionally also support the original variant, as defined in <span><em>ChaCha, a variant of Salsa20</em> <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a></span>, which has a 64-bit nonce and a 64-bit counter. Except where noted, the <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a> variant must be used.</p>
+<p>ChaCha20 defines a nonce and an initial counter to be provided to the encryption and decryption operations. When using a ChaCha20 key with the <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a> algorithm, these values are provided using the initialization vector (IV) functions in the following ways:</p>
<ul class="simple">
-<li>To use ChaCha20, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</li>
-<li>To use ARC4, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</li>
+<li>A call to <a class="reference internal" href="#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> will generate a random 12-byte nonce, and set the counter value to zero. The random nonce is output as a 12-byte IV value in the output.</li>
+<li>A call to <a class="reference internal" href="#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> will use first 12 bytes of the input buffer as the nonce and set the counter value to zero.</li>
+<li>A call to <a class="reference internal" href="#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> on a multi-part cipher operation will generate and return a random 12-byte nonce and set the counter value to zero.</li>
+<li>A call to <a class="reference internal" href="#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> on a multi-part cipher operation can support the following IV sizes:<ul>
+<li>12 bytes: the provided IV is used as the nonce, and the counter value is set to zero.</li>
+<li>16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 12 bytes is used as the nonce.</li>
+<li>8 bytes: the cipher operation uses the original <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a> definition of ChaCha20: the provided IV is used as the 64-bit nonce, and the 64-bit counter value is set to zero.</li>
+<li>It is recommended that implementations do not support other sizes of IV.</li>
+</ul>
+</li>
</ul>
</div>
<div class="section" id="PSA_ALG_CTR">
<span id="c.PSA_ALG_CTR"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CTR</span></code> (macro)</h3>
<p>A stream cipher built using the Counter (CTR) mode of a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR">PSA_ALG_CTR</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01000)
+#define <a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR">PSA_ALG_CTR</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01000)
</pre>
-<p>CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type <a class="reference internal" href="../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> and a length of 128 bits (16 bytes).</p>
+<p>CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type <a class="reference internal" href="../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> and a size of 128 bits (16 bytes).</p>
+<p>The CTR block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
+<p>CTR mode requires a <em>counter block</em> which is the same size as the cipher block length. The counter block is updated for each block (or a partial final block) that is encrypted or decrypted.</p>
+<p>A counter block value must only be used once across all messages encrypted using the same key value. This is typically achieved by splitting the counter block into a nonce, which is unique among all message encrypted with the key, and a counter which is incremented for each block of a message.</p>
+<p>For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a 12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to 2^32 blocks (64GB) of message data to be encrypted in each message.</p>
+<p>The first counter block is constructed from the initialization vector (IV). The initial counter block is is constructed in the following ways:</p>
+<ul class="simple">
+<li>A call to <a class="reference internal" href="#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> will generate a random counter block value. This is the first block of output.</li>
+<li>A call to <a class="reference internal" href="#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> will use first block of the input buffer as the initial counter block value.</li>
+<li>A call to <a class="reference internal" href="#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> on a multi-part cipher operation will generate and return a random counter block value.</li>
+<li>A call to <a class="reference internal" href="#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> on a multi-part cipher operation requires an IV must be between <code class="docutils literal"><span class="pre">1</span></code> and <em>n</em> bytes in length, where <em>n</em> is the cipher block length. The counter block is initialized using the IV, and padded with zero bytes up to the block length.</li>
+</ul>
+<p>During the counter block update operation, the counter block is treated as a single big-endian encoded integer and the update operation increments this integer by <code class="docutils literal"><span class="pre">1</span></code>.</p>
+<p>This scheme meets the recommendations in Appendix B of <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite psa_c psa_c-cite">[SP800-38A]</span></a>.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
</div>
<div class="section" id="PSA_ALG_CFB">
<span id="c.PSA_ALG_CFB"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CFB</span></code> (macro)</h3>
<p>A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB">PSA_ALG_CFB</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01100)
+#define <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB">PSA_ALG_CFB</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01100)
</pre>
-<p>The underlying block cipher is determined by the key type.</p>
+<p>The underlying block cipher is determined by the key type. This is the variant of CFB where each iteration encrypts or decrypts a segment of the input that is the same length as the cipher block size. For example, using <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CFB</span></code></a> with a key of type <a class="reference internal" href="../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> will result in the AES-CFB-128 cipher.</p>
+<p>CFB mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
+<p>The CFB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>, using a segment size <em>s</em> equal to the block size <em>b</em>. The definition in <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite psa_c psa_c-cite">[SP800-38A]</span></a> is extended to allow an incomplete final block of input, in which case the algorithm discards the final bytes of the key stream when encrypting or decrypting the final partial block.</p>
</div>
<div class="section" id="PSA_ALG_OFB">
<span id="c.PSA_ALG_OFB"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_OFB</span></code> (macro)</h3>
<p>A stream cipher built using the Output Feedback (OFB) mode of a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_OFB" title="PSA_ALG_OFB">PSA_ALG_OFB</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01200)
+#define <a class="reference internal" href="#c.PSA_ALG_OFB" title="PSA_ALG_OFB">PSA_ALG_OFB</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01200)
</pre>
<p>The underlying block cipher is determined by the key type.</p>
+<p>OFB mode requires an initialization vector (IV) that is the same size as the cipher block length. OFB mode requires that the IV is a nonce, and must be unique for each use of the mode with the same key.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
+<p>The OFB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_XTS">
<span id="c.PSA_ALG_XTS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_XTS</span></code> (macro)</h3>
-<p>The XTS cipher mode of a block cipher.</p>
+<p>The XEX with Ciphertext Stealing (XTS) cipher mode of a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_XTS" title="PSA_ALG_XTS">PSA_ALG_XTS</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0440ff00)
+#define <a class="reference internal" href="#c.PSA_ALG_XTS" title="PSA_ALG_XTS">PSA_ALG_XTS</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0440ff00)
</pre>
-<p>XTS is a cipher mode which is built from a block cipher. It requires at least one full block of input, but beyond this minimum the input does not need to be a whole number of blocks.</p>
+<p>XTS is a cipher mode which is built from a block cipher, designed for use in disk encryption. It requires at least one full cipher block length of input, but beyond this minimum the input does not need to be a whole number of blocks.</p>
+<p>XTS mode uses two keys for the underlying block cipher. These are provided by using a key that is twice the normal key size for the cipher. For example, to use AES-256-XTS the application must create a key with type <a class="reference internal" href="../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> and bit size <code class="docutils literal"><span class="pre">512</span></code>.</p>
+<p>XTS mode requires an initialization vector (IV) that is the same size as the cipher block length. The IV for XTS is typically defined to be the sector number of the disk block being encrypted or decrypted.</p>
+<p>The XTS block cipher mode is defined in <span><em>1619-2018 - IEEE Standard for Cryptographic Protection of Data on Block-Oriented Storage Devices</em> <a class="reference internal" href="../../about.html#citation-ieee-xts"><span class="cite">[IEEE-XTS]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_ECB_NO_PADDING">
<span id="c.PSA_ALG_ECB_NO_PADDING"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECB_NO_PADDING</span></code> (macro)</h3>
-<p>The Electronic Code Book (ECB) mode of a block cipher, with no padding.</p>
+<p>The Electronic Codebook (ECB) mode of a block cipher, with no padding.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_ECB_NO_PADDING" title="PSA_ALG_ECB_NO_PADDING">PSA_ALG_ECB_NO_PADDING</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404400)
+#define <a class="reference internal" href="#c.PSA_ALG_ECB_NO_PADDING" title="PSA_ALG_ECB_NO_PADDING">PSA_ALG_ECB_NO_PADDING</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404400)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">ECB mode does not protect the confidentiality of the encrypted data except in extremely narrow circumstances. It is recommended that applications only use ECB if they need to construct an operating mode that the implementation does not provide. Implementations are encouraged to provide the modes that applications need in preference to supporting direct access to ECB.</p>
</div>
<p>The underlying block cipher is determined by the key type.</p>
-<p>This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.</p>
+<p>This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher.</p>
<p>ECB mode does not accept an initialization vector (IV). When using a multi-part cipher operation with this algorithm, <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not be called.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
+<p>The ECB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_CBC_NO_PADDING">
<span id="c.PSA_ALG_CBC_NO_PADDING"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_NO_PADDING</span></code> (macro)</h3>
<p>The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CBC_NO_PADDING" title="PSA_ALG_CBC_NO_PADDING">PSA_ALG_CBC_NO_PADDING</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404000)
+#define <a class="reference internal" href="#c.PSA_ALG_CBC_NO_PADDING" title="PSA_ALG_CBC_NO_PADDING">PSA_ALG_CBC_NO_PADDING</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404000)
</pre>
<p>The underlying block cipher is determined by the key type.</p>
-<p>This symmetric cipher mode can only be used with messages whose lengths are whole number of blocks for the chosen block cipher.</p>
+<p>This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher.</p>
+<p>CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
+<p>The CBC block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_CBC_PKCS7">
<span id="c.PSA_ALG_CBC_PKCS7"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</h3>
<p>The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CBC_PKCS7" title="PSA_ALG_CBC_PKCS7">PSA_ALG_CBC_PKCS7</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404100)
+#define <a class="reference internal" href="#c.PSA_ALG_CBC_PKCS7" title="PSA_ALG_CBC_PKCS7">PSA_ALG_CBC_PKCS7</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404100)
</pre>
<p>The underlying block cipher is determined by the key type.</p>
-<p>This is the padding method defined by PKCS#7 <a class="reference external" href="https://tools.ietf.org/html/rfc2315.html#section-10.3">RFC 2315 §10.3</a>.</p>
+<p>CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
+</div>
+<p>The CBC block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>. The padding operation is defined by <span><em>PKCS #7: Cryptographic Message Syntax Version 1.5</em> <a class="reference internal" href="../../about.html#citation-rfc2315"><span class="cite">[RFC2315]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc2315.html#section-10.3">§10.3</a>.</p>
</div>
</div>
<div class="section" id="single-part-cipher-functions">
-<h2>Single-part cipher functions</h2>
+<h2>10.4.2. Single-part cipher functions</h2>
<div class="section" id="psa_cipher_encrypt">
<span id="c.psa_cipher_encrypt"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_encrypt</span></code> (function)</h3>
<p>Encrypt a message using a symmetric cipher.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt">psa_cipher_encrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt">psa_cipher_encrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
uint8_t * output,
@@ -145,9 +213,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the message to encrypt.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -171,9 +239,11 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
+<dd>The <code class="docutils literal"><span class="pre">input_length</span></code> is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
@@ -205,8 +275,8 @@
<span id="c.psa_cipher_decrypt"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_decrypt</span></code> (function)</h3>
<p>Decrypt a message using a symmetric cipher.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt">psa_cipher_decrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt">psa_cipher_decrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
uint8_t * output,
@@ -217,9 +287,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -243,9 +313,11 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
+<dd>The <code class="docutils literal"><span class="pre">input_length</span></code> is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
@@ -274,7 +346,7 @@
</div>
</div>
<div class="section" id="multi-part-cipher-operations">
-<h2>Multi-part cipher operations</h2>
+<h2>10.4.3. Multi-part cipher operations</h2>
<div class="section" id="psa_cipher_operation_t">
<span id="c.psa_cipher_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code> (type)</h3>
<p>The type of the state object for multi-part cipher operations.</p>
@@ -328,8 +400,8 @@
<p>Set the key for a multi-part symmetric encryption operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup">psa_cipher_encrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -337,9 +409,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -348,7 +420,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -394,8 +466,8 @@
<p>Set the key for a multi-part symmetric decryption operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup">psa_cipher_decrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -403,9 +475,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The cipher algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -414,7 +486,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -723,7 +795,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.4.4. Support macros</h2>
<div class="section" id="PSA_ALG_IS_STREAM_CIPHER">
<span id="c.PSA_ALG_IS_STREAM_CIPHER"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</h3>
<p>Whether the specified algorithm is a stream cipher.</p>
@@ -733,7 +805,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a stream cipher algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier or if it is not a symmetric cipher algorithm.</p>
@@ -752,7 +824,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the input in bytes.</dd>
</dl>
@@ -790,7 +862,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the input in bytes.</dd>
</dl>
@@ -827,7 +899,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The default IV size for the specified key type and algorithm.
@@ -859,7 +931,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
<dd>Size of the input in bytes.</dd>
</dl>
@@ -897,7 +969,7 @@
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A symmetric key type that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A cipher algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
@@ -922,7 +994,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">type</span></code></dt>
-<dd>A cipher key type (value of type <a class="reference internal" href="../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>).</dd>
+<dd>A cipher key type (value of type <a class="reference internal" href="../keys/types.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_type_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The block size for a block cipher, or <code class="docutils literal"><span class="pre">1</span></code> for a stream cipher. The return value is undefined if <code class="docutils literal"><span class="pre">type</span></code> is not a supported cipher key type.</p>
@@ -957,76 +1029,52 @@
</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="#">Unauthenticated ciphers</a><ul>
-<li><a class="reference internal" href="#cipher-algorithms">Cipher algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CTR"><code class="docutils literal"><span class="pre">PSA_ALG_CTR</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CFB"><code class="docutils literal"><span class="pre">PSA_ALG_CFB</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_OFB"><code class="docutils literal"><span class="pre">PSA_ALG_OFB</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_XTS"><code class="docutils literal"><span class="pre">PSA_ALG_XTS</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_ECB_NO_PADDING"><code class="docutils literal"><span class="pre">PSA_ALG_ECB_NO_PADDING</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CBC_NO_PADDING"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_NO_PADDING</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CBC_PKCS7"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#single-part-cipher-functions">Single-part cipher functions</a><ul>
-<li><a class="reference internal" href="#psa_cipher_encrypt"><code class="docutils literal"><span class="pre">psa_cipher_encrypt</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_decrypt"><code class="docutils literal"><span class="pre">psa_cipher_decrypt</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#multi-part-cipher-operations">Multi-part cipher operations</a><ul>
-<li><a class="reference internal" href="#psa_cipher_operation_t"><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#psa_cipher_operation_init"><code class="docutils literal"><span class="pre">psa_cipher_operation_init</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_encrypt_setup"><code class="docutils literal"><span class="pre">psa_cipher_encrypt_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_decrypt_setup"><code class="docutils literal"><span class="pre">psa_cipher_decrypt_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_generate_iv"><code class="docutils literal"><span class="pre">psa_cipher_generate_iv</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_set_iv"><code class="docutils literal"><span class="pre">psa_cipher_set_iv</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_update"><code class="docutils literal"><span class="pre">psa_cipher_update</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_finish"><code class="docutils literal"><span class="pre">psa_cipher_finish</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_cipher_abort"><code class="docutils literal"><span class="pre">psa_cipher_abort</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_IV_LENGTH"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_IV_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="macs.html" title="previous chapter">Message authentication codes (MAC)</a></li>
- <li>Next: <a href="aead.html" title="next chapter">Authenticated encryption with associated data (AEAD)</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/ciphers.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.4. Unauthenticated ciphers</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#cipher-algorithms">10.4.1. Cipher algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#single-part-cipher-functions">10.4.2. Single-part cipher functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#multi-part-cipher-operations">10.4.3. Multi-part cipher operations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.4.4. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -1042,15 +1090,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/ciphers.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/hashes.html b/docs/html/api/ops/hashes.html
index de98091..a87d91c 100644
--- a/docs/html/api/ops/hashes.html
+++ b/docs/html/api/ops/hashes.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Message digests — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.2. Message digests — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Message authentication codes (MAC)" href="macs.html" />
- <link rel="prev" title="Cryptographic operation reference" href="index.html" />
+ <link rel="next" title="10.3. Message authentication codes (MAC)" href="macs.html" />
+ <link rel="prev" title="10.1. Algorithms" href="algorithms.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,138 +41,161 @@
<div class="body" role="main">
<div class="section" id="message-digests">
-<span id="hashes"></span><h1>Message digests</h1>
+<span id="hashes"></span><h1>10.2. Message digests</h1>
<div class="section" id="hash-algorithms">
-<span id="id1"></span><h2>Hash algorithms</h2>
+<span id="id1"></span><h2>10.2.1. Hash algorithms</h2>
<div class="section" id="PSA_ALG_MD2">
<span id="c.PSA_ALG_MD2"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD2</span></code> (macro)</h3>
-<p>MD2.</p>
+<p>The MD2 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_MD2" title="PSA_ALG_MD2">PSA_ALG_MD2</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000001)
+#define <a class="reference internal" href="#c.PSA_ALG_MD2" title="PSA_ALG_MD2">PSA_ALG_MD2</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000001)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The MD2 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
</div>
+<p>MD2 is defined in <span><em>The MD2 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1319"><span class="cite">[RFC1319]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_MD4">
<span id="c.PSA_ALG_MD4"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD4</span></code> (macro)</h3>
-<p>MD4.</p>
+<p>The MD4 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_MD4" title="PSA_ALG_MD4">PSA_ALG_MD4</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000002)
+#define <a class="reference internal" href="#c.PSA_ALG_MD4" title="PSA_ALG_MD4">PSA_ALG_MD4</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000002)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The MD4 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
</div>
+<p>MD4 is defined in <span><em>The MD4 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1320"><span class="cite">[RFC1320]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_MD5">
<span id="c.PSA_ALG_MD5"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_MD5</span></code> (macro)</h3>
-<p>MD5.</p>
+<p>The MD5 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_MD5" title="PSA_ALG_MD5">PSA_ALG_MD5</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000003)
+#define <a class="reference internal" href="#c.PSA_ALG_MD5" title="PSA_ALG_MD5">PSA_ALG_MD5</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000003)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The MD5 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
</div>
+<p>MD5 is defined in <span><em>The MD5 Message-Digest Algorithm</em> <a class="reference internal" href="../../about.html#citation-rfc1321"><span class="cite">[RFC1321]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_RIPEMD160">
<span id="c.PSA_ALG_RIPEMD160"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RIPEMD160</span></code> (macro)</h3>
-<p>RIPEMD-160.</p>
+<p>The RIPEMD-160 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_RIPEMD160" title="PSA_ALG_RIPEMD160">PSA_ALG_RIPEMD160</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000004)
+#define <a class="reference internal" href="#c.PSA_ALG_RIPEMD160" title="PSA_ALG_RIPEMD160">PSA_ALG_RIPEMD160</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000004)
</pre>
+<p>RIPEMD-160 is defined in <span><em>RIPEMD-160: A Strengthened Version of RIPEMD</em> <a class="reference internal" href="../../about.html#citation-ripemd"><span class="cite">[RIPEMD]</span></a></span>, and also in <span><em>ISO/IEC 10118-3:2018 IT Security techniques — Hash-functions — Part 3: Dedicated hash-functions</em> <a class="reference internal" href="../../about.html#citation-iso10118"><span class="cite">[ISO10118]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_1">
<span id="c.PSA_ALG_SHA_1"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_1</span></code> (macro)</h3>
-<p>SHA-1.</p>
+<p>The SHA-1 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_1" title="PSA_ALG_SHA_1">PSA_ALG_SHA_1</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000005)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_1" title="PSA_ALG_SHA_1">PSA_ALG_SHA_1</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000005)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">The SHA-1 hash is weak and deprecated and is only recommended for use in legacy protocols.</p>
</div>
+<p>SHA-1 is defined in <span><em>FIPS Publication 180-4: Secure Hash Standard (SHS)</em> <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_224">
<span id="c.PSA_ALG_SHA_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_224</span></code> (macro)</h3>
-<p>SHA-224.</p>
+<p>The SHA-224 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_224" title="PSA_ALG_SHA_224">PSA_ALG_SHA_224</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000008)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_224" title="PSA_ALG_SHA_224">PSA_ALG_SHA_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000008)
</pre>
+<p>SHA-224 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_256">
<span id="c.PSA_ALG_SHA_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code> (macro)</h3>
-<p>SHA-256.</p>
+<p>The SHA-256 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256">PSA_ALG_SHA_256</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000009)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256">PSA_ALG_SHA_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000009)
</pre>
+<p>SHA-256 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_384">
<span id="c.PSA_ALG_SHA_384"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_384</span></code> (macro)</h3>
-<p>SHA-384.</p>
+<p>The SHA-384 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_384" title="PSA_ALG_SHA_384">PSA_ALG_SHA_384</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000a)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_384" title="PSA_ALG_SHA_384">PSA_ALG_SHA_384</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000a)
</pre>
+<p>SHA-384 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_512">
<span id="c.PSA_ALG_SHA_512"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512</span></code> (macro)</h3>
-<p>SHA-512.</p>
+<p>The SHA-512 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512">PSA_ALG_SHA_512</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000b)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_512" title="PSA_ALG_SHA_512">PSA_ALG_SHA_512</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000b)
</pre>
+<p>SHA-512 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_512_224">
<span id="c.PSA_ALG_SHA_512_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_224</span></code> (macro)</h3>
-<p>SHA-512/224.</p>
+<p>The SHA-512/224 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_224" title="PSA_ALG_SHA_512_224">PSA_ALG_SHA_512_224</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000c)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_224" title="PSA_ALG_SHA_512_224">PSA_ALG_SHA_512_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000c)
</pre>
+<p>SHA-512/224 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA_512_256">
<span id="c.PSA_ALG_SHA_512_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_256</span></code> (macro)</h3>
-<p>SHA-512/256.</p>
+<p>The SHA-512/256 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_256" title="PSA_ALG_SHA_512_256">PSA_ALG_SHA_512_256</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000d)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA_512_256" title="PSA_ALG_SHA_512_256">PSA_ALG_SHA_512_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0200000d)
</pre>
+<p>SHA-512/256 is defined in <a class="reference internal" href="../../about.html#citation-fips180-4"><span class="cite">[FIPS180-4]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA3_224">
<span id="c.PSA_ALG_SHA3_224"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_224</span></code> (macro)</h3>
-<p>SHA3-224.</p>
+<p>The SHA3-224 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA3_224" title="PSA_ALG_SHA3_224">PSA_ALG_SHA3_224</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000010)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA3_224" title="PSA_ALG_SHA3_224">PSA_ALG_SHA3_224</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000010)
</pre>
+<p>SHA3-224 is defined in <span><em>FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions</em> <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_SHA3_256">
<span id="c.PSA_ALG_SHA3_256"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_256</span></code> (macro)</h3>
-<p>SHA3-256.</p>
+<p>The SHA3-256 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000011)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000011)
</pre>
+<p>SHA3-256 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA3_384">
<span id="c.PSA_ALG_SHA3_384"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_384</span></code> (macro)</h3>
-<p>SHA3-384.</p>
+<p>The SHA3-384 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA3_384" title="PSA_ALG_SHA3_384">PSA_ALG_SHA3_384</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000012)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA3_384" title="PSA_ALG_SHA3_384">PSA_ALG_SHA3_384</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000012)
</pre>
+<p>SHA3-384 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
</div>
<div class="section" id="PSA_ALG_SHA3_512">
<span id="c.PSA_ALG_SHA3_512"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_512</span></code> (macro)</h3>
-<p>SHA3-512.</p>
+<p>The SHA3-512 message-digest algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_SHA3_512" title="PSA_ALG_SHA3_512">PSA_ALG_SHA3_512</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000013)
+#define <a class="reference internal" href="#c.PSA_ALG_SHA3_512" title="PSA_ALG_SHA3_512">PSA_ALG_SHA3_512</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000013)
</pre>
+<p>SHA3-512 is defined in <a class="reference internal" href="../../about.html#citation-fips202"><span class="cite">[FIPS202]</span></a>.</p>
+</div>
+<div class="section" id="PSA_ALG_SM3">
+<span id="c.PSA_ALG_SM3"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_SM3</span></code> (macro)</h3>
+<p>The SM3 message-digest algorithm.</p>
+<pre class="literal-block">
+#define <a class="reference internal" href="#c.PSA_ALG_SM3" title="PSA_ALG_SM3">PSA_ALG_SM3</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x02000014)
+</pre>
+<p>SM3 is defined in <span><em>GB/T 32905-2016: Information security techniques — SM3 cryptographic hash algorithm</em> <a class="reference internal" href="../../about.html#citation-prc-sm3"><span class="cite">[PRC-SM3]</span></a></span> and <span><em>The SM3 Cryptographic Hash Function</em> <a class="reference internal" href="../../about.html#citation-ietf-sm3"><span class="cite">[IETF-SM3]</span></a></span>.</p>
</div>
</div>
<div class="section" id="single-part-hashing-functions">
-<h2>Single-part hashing functions</h2>
+<h2>10.2.2. Single-part hashing functions</h2>
<div class="section" id="psa_hash_compute">
<span id="c.psa_hash_compute"></span><h3><code class="docutils literal"><span class="pre">psa_hash_compute</span></code> (function)</h3>
<p>Calculate the hash (digest) of a message.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compute" title="psa_hash_compute">psa_hash_compute</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compute" title="psa_hash_compute">psa_hash_compute</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
uint8_t * hash,
@@ -181,7 +205,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the message to hash.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -228,7 +252,7 @@
<span id="c.psa_hash_compare"></span><h3><code class="docutils literal"><span class="pre">psa_hash_compare</span></code> (function)</h3>
<p>Calculate the hash (digest) of a message and compare it with a reference value.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare">psa_hash_compare</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_compare" title="psa_hash_compare">psa_hash_compare</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
const uint8_t * hash,
@@ -237,7 +261,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the message to hash.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -273,7 +297,7 @@
</div>
</div>
<div class="section" id="multi-part-hashing-operations">
-<span id="hash-mp"></span><h2>Multi-part hashing operations</h2>
+<span id="hash-mp"></span><h2>10.2.3. Multi-part hashing operations</h2>
<div class="section" id="psa_hash_operation_t">
<span id="c.psa_hash_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_hash_operation_t</span></code> (type)</h3>
<p>The type of the state object for multi-part hash operations.</p>
@@ -327,14 +351,14 @@
<p>Set up a multi-part hash operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_hash_setup" title="psa_hash_setup">psa_hash_setup</a>(<a class="reference internal" href="#c.psa_hash_operation_t" title="psa_hash_operation_t">psa_hash_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The hash algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -585,7 +609,7 @@
<p>The application must call <a class="reference internal" href="#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> or <a class="reference internal" href="#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> before calling this function. This function extracts an intermediate state of the hash computation of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#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>.</p>
<p>This function can be used to halt a hash operation, and then resume the hash operation at a later time, or in another application, by transferring the extracted hash suspend state to a call to <a class="reference internal" href="#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>.</p>
<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_abort()</span></code></a>.</p>
-<p>Hash suspend and resume is not defined for the SHA3 family of hash algorithms. <em><a class="reference internal" href="#hash-suspend-state"><span class="std std-ref">Hash suspend state</span></a></em> defines the format of the output from <a class="reference internal" href="#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>.</p>
+<p>Hash suspend and resume is not defined for the SHA3 family of hash algorithms. <a class="reference internal" href="#hash-suspend-state"><span class="secref">Hash suspend state</span></a> defines the format of the output from <a class="reference internal" href="#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>.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Applications must not use any of the hash suspend state as if it was a hash output. Instead, the suspend state must only be used to resume a hash operation, and <a class="reference internal" href="#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> or <a class="reference internal" href="#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> can then calculate or verify the final hash value.</p>
@@ -595,7 +619,7 @@
<ol class="arabic">
<li><p class="first">Compute the first part of the hash.</p>
<blockquote>
-<div><ol class="arabic simple">
+<div><ol class="loweralpha simple">
<li>Allocate an operation object and initialize it as described in the documentation for <a class="reference internal" href="#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>.</li>
<li>Call <a class="reference internal" href="#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 algorithm.</li>
<li>Call <a class="reference internal" href="#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> zero, one or more times, passing a fragment of the message each time.</li>
@@ -607,7 +631,7 @@
</li>
<li><p class="first">Compute the rest of the hash.</p>
<blockquote>
-<div><ol class="arabic simple">
+<div><ol class="loweralpha simple">
<li>Allocate an operation object and initialize it as described in the documentation for <a class="reference internal" href="#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>.</li>
<li>Call <a class="reference internal" href="#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> with the extracted hash state.</li>
<li>Call <a class="reference internal" href="#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> zero, one or more times, passing a fragment of the message each time.</li>
@@ -631,7 +655,7 @@
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">hash_state</span></code></dt>
-<dd>A buffer containing the suspended hash state which is to be resumed. This must be in the format output by <a class="reference internal" href="#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>, which is described in <em><a class="reference internal" href="#hash-suspend-state-format"><span class="std std-ref">Hash suspend state format</span></a></em>.</dd>
+<dd>A buffer containing the suspended hash state which is to be resumed. This must be in the format output by <a class="reference internal" href="#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>, which is described in <a class="reference internal" href="#hash-suspend-state-format"><span class="secref">Hash suspend state format</span></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">hash_state_length</span></code></dt>
<dd>Length of <code class="docutils literal"><span class="pre">hash_state</span></code> in bytes.</dd>
</dl>
@@ -642,7 +666,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd>The provided hash suspend state is for an algorithm that is not supported.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
-<dd><code class="docutils literal"><span class="pre">hash_state</span></code> does not correspond to a valid hash suspend state. See <em><a class="reference internal" href="#hash-suspend-state-format"><span class="std std-ref">Hash suspend state format</span></a></em> for the definition.</dd>
+<dd><code class="docutils literal"><span class="pre">hash_state</span></code> does not correspond to a valid hash suspend state. See <a class="reference internal" href="#hash-suspend-state-format"><span class="secref">Hash suspend state format</span></a> for the definition.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The operation state is not valid: it must be inactive.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
@@ -702,7 +726,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.2.4. Support macros</h2>
<div class="section" id="PSA_HASH_LENGTH">
<span id="c.PSA_HASH_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_LENGTH</span></code> (macro)</h3>
<p>The size of the output of <a class="reference internal" href="#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> and <a class="reference internal" href="#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>, in bytes.</p>
@@ -712,7 +736,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), or an HMAC algorithm (<a class="reference internal" href="macs.html#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">hash_alg</span></code> is a hash algorithm).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), or an HMAC algorithm (<a class="reference internal" href="macs.html#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">hash_alg</span></code> is a hash algorithm).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The hash length for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
@@ -739,7 +763,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient output size for the algorithm. If the hash algorithm is not recognized, or is not supported by <a class="reference internal" href="#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>, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a hash algorithm that it recognizes, but does not support.</p>
@@ -780,11 +804,11 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The size, in bytes, of the <em>input-length</em> field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
-<p>The algorithm-specific values are defined in <em><a class="reference internal" href="#hash-suspend-state-constants"><span class="std std-ref">Hash suspend state field sizes</span></a></em>.</p>
+<p>The algorithm-specific values are defined in <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
<p class="rubric">Description</p>
<p>Applications can use this value to unpack the hash suspend state that is output by <a class="reference internal" href="#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>.</p>
</div>
@@ -798,60 +822,53 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The size, in bytes, of the <em>hash-state</em> field of the hash suspend state for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
-<p>The algorithm-specific values are defined in <em><a class="reference internal" href="#hash-suspend-state-constants"><span class="std std-ref">Hash suspend state field sizes</span></a></em>.</p>
+<p>The algorithm-specific values are defined in <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
<p class="rubric">Description</p>
<p>Applications can use this value to unpack the hash suspend state that is output by <a class="reference internal" href="#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>.</p>
</div>
<div class="section" id="PSA_HASH_BLOCK_LENGTH">
<span id="c.PSA_HASH_BLOCK_LENGTH"></span><h3><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code> (macro)</h3>
-<p>The input block size of a hash algorithm.</p>
+<p>The input block size of a hash algorithm, in bytes.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH">PSA_HASH_BLOCK_LENGTH</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
-<p>The block size for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
+<p>The block size in bytes for the specified hash algorithm. If the hash algorithm is not recognized, return <code class="docutils literal"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or the correct size for a hash algorithm that it recognizes, but does not support.</p>
<p class="rubric">Description</p>
<p>Hash algorithms process their input data in blocks. Hash operations will retain any partial blocks until they have enough input to fill the block or until the operation is finished.</p>
<p>This affects the output from <a class="reference internal" href="#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>.</p>
</div>
</div>
<div class="section" id="hash-suspend-state">
-<span id="id2"></span><h2>Hash suspend state</h2>
+<span id="id2"></span><h2>10.2.5. Hash suspend state</h2>
<p>The hash suspend state is output by <a class="reference internal" href="#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> and input to <a class="reference internal" href="#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>.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">Hash suspend and resume is not defined for the SHA3 family of hash algorithms.</p>
</div>
-<p class="rubric" id="hash-suspend-state-format">Hash suspend state format</p>
+<div class="section" id="hash-suspend-state-format">
+<span id="id3"></span><h3>Hash suspend state format</h3>
<p>The hash suspend state has the following format:</p>
<p><em>hash-suspend-state</em> = <em>algorithm</em> || <em>input-length</em> || <em>hash-state</em> || <em>unprocessed-input</em></p>
<p>The fields in the hash suspend state are defined as follows:</p>
-<table border="1" class="colwidths-given docutils">
-<colgroup>
-<col width="25%" />
-<col width="75%" />
-</colgroup>
-<tbody valign="top">
-<tr class="row-odd"><td><p class="first"><em>algorithm</em></p>
-<p class="last">big-endian 32-bit unsigned integer</p>
-</td>
-<td><p class="first">The PSA Crypto API algorithm identifier. Encoded as a big-endian 32-bit unsigned integer.</p>
+<dl class="docutils">
+<dt><em>algorithm</em></dt>
+<dd><p class="first">A big-endian 32-bit unsigned integer.</p>
+<p>The PSA Crypto API algorithm identifier value.</p>
<p class="last">The byte length of the <em>algorithm</em> field can be evaluated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a>.</p>
-</td>
-</tr>
-<tr class="row-even"><td><p class="first"><em>input-length</em></p>
-<p class="last">big-endian unsigned integer</p>
-</td>
-<td><p class="first">The content of this field is algorithm-specific:</p>
+</dd>
+<dt><em>input-length</em></dt>
+<dd><p class="first">A big-endian unsigned integer</p>
+<p>The content of this field is algorithm-specific:</p>
<ul class="simple">
<li>For MD2, this is the number of bytes in the <em>unprocessed-input</em>.</li>
<li>For all other hash algorithms, this is the total number of bytes of input to the hash computation. This includes the <em>unprocessed-input</em> bytes.</li>
@@ -863,13 +880,11 @@
<li>For SHA-512, SHA-384 and SHA-512/256: <em>input-length</em> is a 128-bit unsigned integer.</li>
</ul>
<p class="last">The length, in bytes, of the <em>input-length</em> field can be calculated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH" title="PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
-See <em><a class="reference internal" href="#hash-suspend-state-constants"><span class="std std-ref">Hash suspend state field sizes</span></a></em>.</p>
-</td>
-</tr>
-<tr class="row-odd"><td><p class="first"><em>hash-state</em></p>
-<p class="last">array of bytes</p>
-</td>
-<td><p class="first">Algorithm-specific intermediate hash state:</p>
+See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
+</dd>
+<dt><em>hash-state</em></dt>
+<dd><p class="first">An array of bytes</p>
+<p>Algorithm-specific intermediate hash state:</p>
<ul class="simple">
<li>For MD2: 16 bytes of internal checksum, then 48 bytes of intermediate digest.</li>
<li>For MD4 and MD5: 4x 32-bit integers, in little-endian encoding.</li>
@@ -880,22 +895,20 @@
</ul>
<p class="last">The length of this field is specific to the algorithm.
The length, in bytes, of the <em>hash-state</em> field can be calculated using <a class="reference internal" href="#c.PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH" title="PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
-See <em><a class="reference internal" href="#hash-suspend-state-constants"><span class="std std-ref">Hash suspend state field sizes</span></a></em>.</p>
-</td>
-</tr>
-<tr class="row-even"><td><p class="first"><em>unprocessed-input</em></p>
-<p class="last">0 to (<em>hash-block-size</em>-1) bytes</p>
-</td>
-<td><p class="first">A partial block of unprocessed input data. This is between zero and <em>hash-block-size</em>-1 bytes of data, the length can be calculated by:</p>
+See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
+</dd>
+<dt><em>unprocessed-input</em></dt>
+<dd><p class="first">0 to (<em>hash-block-size</em>-1) bytes</p>
+<p>A partial block of unprocessed input data. This is between zero and <em>hash-block-size</em>-1 bytes of data, the length can be calculated by:</p>
<p><code class="docutils literal"><span class="pre">length(</span></code><em>unprocessed-input</em><code class="docutils literal"><span class="pre">)</span></code> <code class="docutils literal"><span class="pre">=</span></code> <em>input-length</em> <code class="docutils literal"><span class="pre">%</span></code> <em>hash-block-size</em>.</p>
<p class="last">The <em>hash-block-size</em> is specific to the algorithm.
The size of a hash block can be calculated using <a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> is a hash algorithm.
-See <em><a class="reference internal" href="#hash-suspend-state-constants"><span class="std std-ref">Hash suspend state field sizes</span></a></em>.</p>
-</td>
-</tr>
-</tbody>
-</table>
-<p class="rubric" id="hash-suspend-state-constants">Hash suspend state field sizes</p>
+See <a class="reference internal" href="#hash-suspend-state-constants"><span class="secref">Hash suspend state field sizes</span></a>.</p>
+</dd>
+</dl>
+</div>
+<div class="section" id="hash-suspend-state-field-sizes">
+<span id="hash-suspend-state-constants"></span><h3>Hash suspend state field sizes</h3>
<p>The following table defines the algorithm-specific field lengths for the hash suspend state returned by <a class="reference internal" href="#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>. All of the field lengths are in bytes. To compute the field lengths for algorithm <code class="docutils literal"><span class="pre">alg</span></code>, use the following expressions:</p>
<ul class="simple">
<li><a class="reference internal" href="#c.PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH" title="PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code></a> returns the length of the <em>algorithm</em> field.</li>
@@ -904,13 +917,7 @@
<li><a class="reference internal" href="#c.PSA_HASH_BLOCK_LENGTH" title="PSA_HASH_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)-1</span></code> is the maximum length of the <em>unprocessed-bytes</em> field.</li>
<li><a class="reference internal" href="#c.PSA_HASH_SUSPEND_OUTPUT_SIZE" title="PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">slg</span></code><code class="docutils literal"><span class="pre">)</span></code> returns the maximum size of the hash suspend state.</li>
</ul>
-<table border="1" class="docutils">
-<colgroup>
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-<col width="25%" />
-</colgroup>
+<table border="1" class="colwidths-auto docutils align-left">
<thead valign="bottom">
<tr class="row-odd"><th class="head">Hash algorithm</th>
<th class="head"><em>input-length</em> size (bytes)</th>
@@ -973,86 +980,60 @@
</table>
</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="#">Message digests</a><ul>
-<li><a class="reference internal" href="#hash-algorithms">Hash algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_MD2"><code class="docutils literal"><span class="pre">PSA_ALG_MD2</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_MD4"><code class="docutils literal"><span class="pre">PSA_ALG_MD4</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_MD5"><code class="docutils literal"><span class="pre">PSA_ALG_MD5</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_RIPEMD160"><code class="docutils literal"><span class="pre">PSA_ALG_RIPEMD160</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_1"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_1</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_224"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_224</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_384"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_384</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_512"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_512_224"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_224</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA_512_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_512_256</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA3_224"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_224</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA3_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_256</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA3_384"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_384</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_SHA3_512"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_512</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#single-part-hashing-functions">Single-part hashing functions</a><ul>
-<li><a class="reference internal" href="#psa_hash_compute"><code class="docutils literal"><span class="pre">psa_hash_compute</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_compare"><code class="docutils literal"><span class="pre">psa_hash_compare</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#multi-part-hashing-operations">Multi-part hashing operations</a><ul>
-<li><a class="reference internal" href="#psa_hash_operation_t"><code class="docutils literal"><span class="pre">psa_hash_operation_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#psa_hash_operation_init"><code class="docutils literal"><span class="pre">psa_hash_operation_init</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_setup"><code class="docutils literal"><span class="pre">psa_hash_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_update"><code class="docutils literal"><span class="pre">psa_hash_update</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_finish"><code class="docutils literal"><span class="pre">psa_hash_finish</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_verify"><code class="docutils literal"><span class="pre">psa_hash_verify</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_abort"><code class="docutils literal"><span class="pre">psa_hash_abort</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_suspend"><code class="docutils literal"><span class="pre">psa_hash_suspend</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_resume"><code class="docutils literal"><span class="pre">psa_hash_resume</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_hash_clone"><code class="docutils literal"><span class="pre">psa_hash_clone</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_HASH_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_ALGORITHM_FIELD_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_INPUT_LENGTH_FIELD_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_HASH_STATE_FIELD_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_HASH_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#hash-suspend-state">Hash suspend state</a></li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="index.html" title="previous chapter">Cryptographic operation reference</a></li>
- <li>Next: <a href="macs.html" title="next chapter">Message authentication codes (MAC)</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/hashes.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.2. Message digests</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#hash-algorithms">10.2.1. Hash algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#single-part-hashing-functions">10.2.2. Single-part hashing functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#multi-part-hashing-operations">10.2.3. Multi-part hashing operations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.2.4. Support macros</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#hash-suspend-state">10.2.5. Hash suspend state</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -1068,15 +1049,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/hashes.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/index.html b/docs/html/api/ops/index.html
index 9fe1155..69f903e 100644
--- a/docs/html/api/ops/index.html
+++ b/docs/html/api/ops/index.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Cryptographic operation reference — PSA Crypto API 1.0.0 documentation</title>
+ <title>10. Cryptographic operation reference — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Message digests" href="hashes.html" />
- <link rel="prev" title="Key management functions" href="../keys/management.html" />
+ <link rel="next" title="10.1. Algorithms" href="algorithms.html" />
+ <link rel="prev" title="9.6. Key management functions" href="../keys/management.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,11 +41,32 @@
<div class="body" role="main">
<div class="section" id="cryptographic-operation-reference">
-<span id="crypto-operations"></span><h1>Cryptographic operation reference</h1>
+<span id="crypto-operations"></span><h1>10. Cryptographic operation reference</h1>
<div class="toctree-wrapper compound">
<ul>
-<li class="toctree-l1"><a class="reference internal" href="hashes.html">Message digests</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="hashes.html#hash-algorithms">Hash algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html#algorithm-encoding">10.1.1. Algorithm encoding</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#psa_algorithm_t"><code class="docutils literal"><span class="pre">psa_algorithm_t</span></code> (type)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_NONE"><code class="docutils literal"><span class="pre">PSA_ALG_NONE</span></code> (macro)</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html#algorithm-categories">10.1.2. Algorithm categories</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_CIPHER</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_AEAD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_ASYMMETRIC_ENCRYPTION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_ASYMMETRIC_ENCRYPTION</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_IS_WILDCARD"><code class="docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="algorithms.html#PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code> (macro)</a></li>
+</ul>
+</li>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="hashes.html">10.2. Message digests</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html#hash-algorithms">10.2.1. Hash algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_MD2"><code class="docutils literal"><span class="pre">PSA_ALG_MD2</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_MD4"><code class="docutils literal"><span class="pre">PSA_ALG_MD4</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_MD5"><code class="docutils literal"><span class="pre">PSA_ALG_MD5</span></code> (macro)</a></li>
@@ -60,14 +82,15 @@
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_SHA3_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_256</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_SHA3_384"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_384</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_SHA3_512"><code class="docutils literal"><span class="pre">PSA_ALG_SHA3_512</span></code> (macro)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_ALG_SM3"><code class="docutils literal"><span class="pre">PSA_ALG_SM3</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="hashes.html#single-part-hashing-functions">Single-part hashing functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html#single-part-hashing-functions">10.2.2. Single-part hashing functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#psa_hash_compute"><code class="docutils literal"><span class="pre">psa_hash_compute</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#psa_hash_compare"><code class="docutils literal"><span class="pre">psa_hash_compare</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="hashes.html#multi-part-hashing-operations">Multi-part hashing operations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html#multi-part-hashing-operations">10.2.3. Multi-part hashing operations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#psa_hash_operation_t"><code class="docutils literal"><span class="pre">psa_hash_operation_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_HASH_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#psa_hash_operation_init"><code class="docutils literal"><span class="pre">psa_hash_operation_init</span></code> (function)</a></li>
@@ -81,7 +104,7 @@
<li class="toctree-l3"><a class="reference internal" href="hashes.html#psa_hash_clone"><code class="docutils literal"><span class="pre">psa_hash_clone</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="hashes.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html#support-macros">10.2.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_HASH_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_LENGTH</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_HASH_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_MAX_SIZE</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_HASH_SUSPEND_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_HASH_SUSPEND_OUTPUT_SIZE</span></code> (macro)</a></li>
@@ -92,23 +115,27 @@
<li class="toctree-l3"><a class="reference internal" href="hashes.html#PSA_HASH_BLOCK_LENGTH"><code class="docutils literal"><span class="pre">PSA_HASH_BLOCK_LENGTH</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="hashes.html#hash-suspend-state">Hash suspend state</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html#hash-suspend-state">10.2.5. Hash suspend state</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="hashes.html#hash-suspend-state-format">Hash suspend state format</a></li>
+<li class="toctree-l3"><a class="reference internal" href="hashes.html#hash-suspend-state-field-sizes">Hash suspend state field sizes</a></li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="macs.html">Message authentication codes (MAC)</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="macs.html#mac-algorithms">MAC algorithms</a><ul>
+</ul>
+</li>
+<li class="toctree-l1"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="macs.html#mac-algorithms">10.3.1. MAC algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_TRUNCATED_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_TRUNCATED_MAC</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_CBC_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_MAC</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_CMAC"><code class="docutils literal"><span class="pre">PSA_ALG_CMAC</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="macs.html#single-part-mac-functions">Single-part MAC functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="macs.html#single-part-mac-functions">10.3.2. Single-part MAC functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="macs.html#psa_mac_compute"><code class="docutils literal"><span class="pre">psa_mac_compute</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#psa_mac_verify"><code class="docutils literal"><span class="pre">psa_mac_verify</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="macs.html#multi-part-mac-operations">Multi-part MAC operations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="macs.html#multi-part-mac-operations">10.3.3. Multi-part MAC operations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="macs.html#psa_mac_operation_t"><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_MAC_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#psa_mac_operation_init"><code class="docutils literal"><span class="pre">psa_mac_operation_init</span></code> (function)</a></li>
@@ -120,7 +147,7 @@
<li class="toctree-l3"><a class="reference internal" href="macs.html#psa_mac_abort"><code class="docutils literal"><span class="pre">psa_mac_abort</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="macs.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="macs.html#support-macros">10.3.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_IS_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_IS_BLOCK_CIPHER_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_BLOCK_CIPHER_MAC</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="macs.html#PSA_ALG_FULL_LENGTH_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_FULL_LENGTH_MAC</span></code> (macro)</a></li>
@@ -130,8 +157,8 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="ciphers.html">Unauthenticated ciphers</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="ciphers.html#cipher-algorithms">Cipher algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html#cipher-algorithms">10.4.1. Cipher algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_ALG_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_ALG_CTR"><code class="docutils literal"><span class="pre">PSA_ALG_CTR</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_ALG_CFB"><code class="docutils literal"><span class="pre">PSA_ALG_CFB</span></code> (macro)</a></li>
@@ -142,12 +169,12 @@
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_ALG_CBC_PKCS7"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ciphers.html#single-part-cipher-functions">Single-part cipher functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html#single-part-cipher-functions">10.4.2. Single-part cipher functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#psa_cipher_encrypt"><code class="docutils literal"><span class="pre">psa_cipher_encrypt</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#psa_cipher_decrypt"><code class="docutils literal"><span class="pre">psa_cipher_decrypt</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ciphers.html#multi-part-cipher-operations">Multi-part cipher operations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html#multi-part-cipher-operations">10.4.3. Multi-part cipher operations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#psa_cipher_operation_t"><code class="docutils literal"><span class="pre">psa_cipher_operation_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_CIPHER_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#psa_cipher_operation_init"><code class="docutils literal"><span class="pre">psa_cipher_operation_init</span></code> (function)</a></li>
@@ -160,7 +187,7 @@
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#psa_cipher_abort"><code class="docutils literal"><span class="pre">psa_cipher_abort</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ciphers.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html#support-macros">10.4.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_ALG_IS_STREAM_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ciphers.html#PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
@@ -178,28 +205,28 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="aead.html">Authenticated encryption with associated data (AEAD)</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="aead.html#aead-algorithms">AEAD algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="aead.html#aead-algorithms">10.5.1. AEAD algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_CCM"><code class="docutils literal"><span class="pre">PSA_ALG_CCM</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_GCM"><code class="docutils literal"><span class="pre">PSA_ALG_GCM</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_CHACHA20_POLY1305"><code class="docutils literal"><span class="pre">PSA_ALG_CHACHA20_POLY1305</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_AEAD_WITH_SHORTENED_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_SHORTENED_TAG</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="aead.html#single-part-aead-functions">Single-part AEAD functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="aead.html#single-part-aead-functions">10.5.2. Single-part AEAD functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_encrypt"><code class="docutils literal"><span class="pre">psa_aead_encrypt</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_decrypt"><code class="docutils literal"><span class="pre">psa_aead_decrypt</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="aead.html#multi-part-aead-operations">Multi-part AEAD operations</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="aead.html#multi-part-aead-operations">10.5.3. Multi-part AEAD operations</a><ul>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_operation_t"><code class="docutils literal"><span class="pre">psa_aead_operation_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_AEAD_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_operation_init"><code class="docutils literal"><span class="pre">psa_aead_operation_init</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_encrypt_setup"><code class="docutils literal"><span class="pre">psa_aead_encrypt_setup</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_decrypt_setup"><code class="docutils literal"><span class="pre">psa_aead_decrypt_setup</span></code> (function)</a></li>
+<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_set_lengths"><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_generate_nonce"><code class="docutils literal"><span class="pre">psa_aead_generate_nonce</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_set_nonce"><code class="docutils literal"><span class="pre">psa_aead_set_nonce</span></code> (function)</a></li>
-<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_set_lengths"><code class="docutils literal"><span class="pre">psa_aead_set_lengths</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_update_ad"><code class="docutils literal"><span class="pre">psa_aead_update_ad</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_update"><code class="docutils literal"><span class="pre">psa_aead_update</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_finish"><code class="docutils literal"><span class="pre">psa_aead_finish</span></code> (function)</a></li>
@@ -207,7 +234,7 @@
<li class="toctree-l3"><a class="reference internal" href="aead.html#psa_aead_abort"><code class="docutils literal"><span class="pre">psa_aead_abort</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="aead.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="aead.html#support-macros">10.5.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER"><code class="docutils literal"><span class="pre">PSA_ALG_IS_AEAD_ON_BLOCK_CIPHER</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG"><code class="docutils literal"><span class="pre">PSA_ALG_AEAD_WITH_DEFAULT_LENGTH_TAG</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="aead.html#PSA_AEAD_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_AEAD_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
@@ -228,14 +255,14 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="kdf.html">Key derivation</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="kdf.html#key-derivation-algorithms">Key derivation algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="kdf.html">10.6. Key derivation</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html#key-derivation-algorithms">10.6.1. Key derivation algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="kdf.html#input-step-types">Input step types</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html#input-step-types">10.6.2. Input step types</a><ul>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#psa_key_derivation_step_t"><code class="docutils literal"><span class="pre">psa_key_derivation_step_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_KEY_DERIVATION_INPUT_SECRET"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_KEY_DERIVATION_INPUT_LABEL"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code> (macro)</a></li>
@@ -245,7 +272,7 @@
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_KEY_DERIVATION_INPUT_SEED"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="kdf.html#key-derivation-functions">Key derivation functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html#key-derivation-functions">10.6.3. Key derivation functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#psa_key_derivation_operation_t"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code> (type)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_KEY_DERIVATION_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#psa_key_derivation_operation_init"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_init</span></code> (function)</a></li>
@@ -259,7 +286,7 @@
<li class="toctree-l3"><a class="reference internal" href="kdf.html#psa_key_derivation_abort"><code class="docutils literal"><span class="pre">psa_key_derivation_abort</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="kdf.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html#support-macros">10.6.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_IS_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_IS_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PRF</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="kdf.html#PSA_ALG_IS_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
@@ -269,8 +296,8 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="sign.html">Asymmetric signature</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="sign.html#asymmetric-signature-algorithms">Asymmetric signature algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="sign.html#asymmetric-signature-algorithms">10.7.1. Asymmetric signature algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_RSA_PSS"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code> (macro)</a></li>
@@ -279,14 +306,14 @@
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_DETERMINISTIC_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="sign.html#asymmetric-signature-functions">Asymmetric signature functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="sign.html#asymmetric-signature-functions">10.7.2. Asymmetric signature functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="sign.html#psa_sign_message"><code class="docutils literal"><span class="pre">psa_sign_message</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#psa_verify_message"><code class="docutils literal"><span class="pre">psa_verify_message</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#psa_sign_hash"><code class="docutils literal"><span class="pre">psa_sign_hash</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#psa_verify_hash"><code class="docutils literal"><span class="pre">psa_verify_hash</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="sign.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="sign.html#support-macros">10.7.3. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="sign.html#PSA_ALG_IS_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN</span></code> (macro)</a></li>
@@ -302,18 +329,18 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="pke.html">Asymmetric encryption</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="pke.html#asymmetric-encryption-algorithms">Asymmetric encryption algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="pke.html#asymmetric-encryption-algorithms">10.8.1. Asymmetric encryption algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="pke.html#PSA_ALG_RSA_PKCS1V15_CRYPT"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_CRYPT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="pke.html#PSA_ALG_RSA_OAEP"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_OAEP</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="pke.html#asymmetric-encryption-functions">Asymmetric encryption functions</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="pke.html#asymmetric-encryption-functions">10.8.2. Asymmetric encryption functions</a><ul>
<li class="toctree-l3"><a class="reference internal" href="pke.html#psa_asymmetric_encrypt"><code class="docutils literal"><span class="pre">psa_asymmetric_encrypt</span></code> (function)</a></li>
<li class="toctree-l3"><a class="reference internal" href="pke.html#psa_asymmetric_decrypt"><code class="docutils literal"><span class="pre">psa_asymmetric_decrypt</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="pke.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="pke.html#support-macros">10.8.3. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="pke.html#PSA_ALG_IS_RSA_OAEP"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_OAEP</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="pke.html#PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="pke.html#PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
@@ -323,22 +350,22 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="ka.html">Key agreement</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="ka.html#key-agreement-algorithms">Key agreement algorithms</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="ka.html">10.9. Key agreement</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ka.html#key-agreement-algorithms">10.9.1. Key agreement algorithms</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_FFDH"><code class="docutils literal"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_ECDH"><code class="docutils literal"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ka.html#standalone-key-agreement">Standalone key agreement</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ka.html#standalone-key-agreement">10.9.2. Standalone key agreement</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ka.html#psa_raw_key_agreement"><code class="docutils literal"><span class="pre">psa_raw_key_agreement</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ka.html#combining-key-agreement-and-key-derivation">Combining key agreement and key derivation</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ka.html#combining-key-agreement-and-key-derivation">10.9.3. Combining key agreement and key derivation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ka.html#psa_key_derivation_key_agreement"><code class="docutils literal"><span class="pre">psa_key_derivation_key_agreement</span></code> (function)</a></li>
</ul>
</li>
-<li class="toctree-l2"><a class="reference internal" href="ka.html#support-macros">Support macros</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="ka.html#support-macros">10.9.4. Support macros</a><ul>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_KEY_AGREEMENT_GET_BASE"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_KEY_AGREEMENT_GET_KDF"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF</span></code> (macro)</a></li>
<li class="toctree-l3"><a class="reference internal" href="ka.html#PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code> (macro)</a></li>
@@ -350,8 +377,8 @@
</li>
</ul>
</li>
-<li class="toctree-l1"><a class="reference internal" href="rng.html">Other cryptographic services</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="rng.html#random-number-generation">Random number generation</a><ul>
+<li class="toctree-l1"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="rng.html#random-number-generation">10.10.1. Random number generation</a><ul>
<li class="toctree-l3"><a class="reference internal" href="rng.html#psa_generate_random"><code class="docutils literal"><span class="pre">psa_generate_random</span></code> (function)</a></li>
</ul>
</li>
@@ -366,22 +393,46 @@
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
- <div class="sphinxsidebarwrapper"><div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li>Previous: <a href="../keys/management.html" title="previous chapter">Key management functions</a></li>
- <li>Next: <a href="hashes.html" title="next chapter">Message digests</a></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/index.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="current reference internal" href="#">10. Cryptographic operation reference</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -397,15 +448,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/index.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/ka.html b/docs/html/api/ops/ka.html
index 36f38a7..afdf394 100644
--- a/docs/html/api/ops/ka.html
+++ b/docs/html/api/ops/ka.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Key agreement — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.9. Key agreement — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Other cryptographic services" href="rng.html" />
- <link rel="prev" title="Asymmetric encryption" href="pke.html" />
+ <link rel="next" title="10.10. Other cryptographic services" href="rng.html" />
+ <link rel="prev" title="10.8. Asymmetric encryption" href="pke.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,9 +41,9 @@
<div class="body" role="main">
<div class="section" id="key-agreement">
-<span id="id1"></span><h1>Key agreement</h1>
+<span id="id1"></span><h1>10.9. Key agreement</h1>
<div class="section" id="key-agreement-algorithms">
-<span id="id2"></span><h2>Key agreement algorithms</h2>
+<span id="id2"></span><h2>10.9.1. Key agreement algorithms</h2>
<div class="section" id="PSA_ALG_KEY_AGREEMENT">
<span id="c.PSA_ALG_KEY_AGREEMENT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</h3>
<p>Macro to build a combined algorithm that chains a key agreement with a key derivation.</p>
@@ -53,46 +54,65 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">ka_alg</span></code></dt>
-<dd>A key agreement algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ka_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A key agreement algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ka_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">kdf_alg</span></code></dt>
-<dd>A key derivation algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">kdf_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A key derivation algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">kdf_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding key agreement and derivation algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">ka_alg</span></code> is not a supported key agreement algorithm or <code class="docutils literal"><span class="pre">kdf_alg</span></code> is not a supported key derivation algorithm.</p>
<p class="rubric">Description</p>
+<p>A combined key agreement algorithm is used with a multi-part key derivation operation, using a call to <a class="reference internal" href="#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>.</p>
<p>The component parts of a key agreement algorithm can be extracted using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_BASE" title="PSA_ALG_KEY_AGREEMENT_GET_BASE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_KDF" title="PSA_ALG_KEY_AGREEMENT_GET_KDF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF()</span></code></a>.</p>
</div>
<div class="section" id="PSA_ALG_FFDH">
<span id="c.PSA_ALG_FFDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</h3>
<p>The finite-field Diffie-Hellman (DH) key agreement algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_FFDH" title="PSA_ALG_FFDH">PSA_ALG_FFDH</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09010000)
+#define <a class="reference internal" href="#c.PSA_ALG_FFDH" title="PSA_ALG_FFDH">PSA_ALG_FFDH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09010000)
</pre>
-<p>The shared secret produced by key agreement is <code class="docutils literal"><span class="pre">g^{ab}</span></code> in big-endian format. It is <code class="docutils literal"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal"><span class="pre">m</span></code> is the size of the prime <code class="docutils literal"><span class="pre">p</span></code> in bits.</p>
+<p>This algorithm can be used directly in a call to <a class="reference internal" href="#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>, or combined with a key derivation operation using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a> for use with <a class="reference internal" href="#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>.</p>
+<p>When used as part of a multi-part key derivation operation, this implements a Diffie-Hellman key agreement scheme using a single Diffie-Hellman key-pair for each participant. This includes the <em>dhEphem</em>, <em>dhOneFlow</em>, and <em>dhStatic</em> schemes. The input step <a class="reference internal" href="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> is used when providing the secret and peer keys to the operation.</p>
+<p>The shared secret produced by this key agreement algorithm is <code class="docutils literal"><span class="pre">g^{ab}</span></code> in big-endian format. It is <code class="docutils literal"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal"><span class="pre">m</span></code> is the size of the prime <code class="docutils literal"><span class="pre">p</span></code> in bits.</p>
+<p>This key agreement scheme is defined by <span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.7.1.1 under the name FFC DH.</p>
</div>
<div class="section" id="PSA_ALG_ECDH">
<span id="c.PSA_ALG_ECDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</h3>
<p>The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_ECDH" title="PSA_ALG_ECDH">PSA_ALG_ECDH</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09020000)
+#define <a class="reference internal" href="#c.PSA_ALG_ECDH" title="PSA_ALG_ECDH">PSA_ALG_ECDH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09020000)
</pre>
+<p>This algorithm can be used directly in a call to <a class="reference internal" href="#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>, or combined with a key derivation operation using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a> for use with <a class="reference internal" href="#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>.</p>
+<p>When used as part of a multi-part key derivation operation, this implements a Diffie-Hellman key agreement scheme using a single elliptic curve key-pair for each participant. This includes the <em>Ephemeral unified model</em>, the <em>Static unified model</em>, and the <em>One-pass Diffie-Hellman</em> schemes. The input step <a class="reference internal" href="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> is used when providing the secret and peer keys to the operation.</p>
<p>The shared secret produced by key agreement is the x-coordinate of the shared secret point. It is always <code class="docutils literal"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal"><span class="pre">m</span></code> is the bit size associated with the curve, i.e. the bit size of the order of the curve’s coordinate field. When <code class="docutils literal"><span class="pre">m</span></code> is not a multiple of 8, the byte containing the most significant bit of the shared secret is padded with zero bits. The byte order is either little-endian or big-endian depending on the curve type.</p>
+<ul>
+<li><p class="first">For Montgomery curves (curve family <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>), the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in little-endian byte order.</p>
<ul class="simple">
-<li>For Montgomery curves (curve family <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>), the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in little-endian byte order. The bit size is 448 for Curve448 and 255 for Curve25519.</li>
-<li>For Weierstrass curves over prime fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a> and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>), the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in big-endian byte order. The bit size is <code class="docutils literal"><span class="pre">m</span> <span class="pre">=</span> <span class="pre">ceiling(log_2(p))</span></code> for the field <code class="docutils literal"><span class="pre">F_p</span></code>.</li>
-<li>For Weierstrass curves over binary fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>), the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in big-endian byte order. The bit size is <code class="docutils literal"><span class="pre">m</span></code> for the field <code class="docutils literal"><span class="pre">F_{2^m}</span></code>.</li>
+<li>For Curve25519, this is the X25519 function defined in <span><em>Curve25519: new Diffie-Hellman speed records</em> <a class="reference internal" href="../../about.html#citation-curve25519"><span class="cite">[Curve25519]</span></a></span>. The bit size <code class="docutils literal"><span class="pre">m</span></code> is 255.</li>
+<li>For Curve448, this is the X448 function defined in <span><em>Ed448-Goldilocks, a new elliptic curve</em> <a class="reference internal" href="../../about.html#citation-curve448"><span class="cite">[Curve448]</span></a></span>. The bit size <code class="docutils literal"><span class="pre">m</span></code> is 448.</li>
+</ul>
+</li>
+<li><p class="first">For Weierstrass curves (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a> and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>) the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">h</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">h</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in big-endian byte order. This is the Elliptic Curve Cryptography Cofactor Diffie-Hellman primitive defined by <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="../../about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span> §3.3.2 as, and also as ECC CDH by <span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.7.1.2.</p>
+<ul class="simple">
+<li>Over prime fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a> and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>), the bit size is <code class="docutils literal"><span class="pre">m</span> <span class="pre">=</span> <span class="pre">ceiling(log_2(p))</span></code> for the field <code class="docutils literal"><span class="pre">F_p</span></code>.</li>
+<li>Over binary fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>), the bit size is <code class="docutils literal"><span class="pre">m</span></code> for the field <code class="docutils literal"><span class="pre">F_{2^m}</span></code>.</li>
+</ul>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">The cofactor Diffie-Hellman primitive is equivalent to the standard elliptic curve Diffie-Hellman calculation <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> (<a class="reference internal" href="../../about.html#citation-sec1"><span class="cite psa_c psa_c-cite">[SEC1]</span></a> §3.3.1) for curves where the cofactor <code class="docutils literal"><span class="pre">h</span></code> is <code class="docutils literal"><span class="pre">1</span></code>. This is true for all curves in the <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a>, and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a> families.</p>
+</div>
+</li>
</ul>
</div>
</div>
<div class="section" id="standalone-key-agreement">
-<h2>Standalone key agreement</h2>
+<h2>10.9.2. Standalone key agreement</h2>
<div class="section" id="psa_raw_key_agreement">
<span id="c.psa_raw_key_agreement"></span><h3><code class="docutils literal"><span class="pre">psa_raw_key_agreement</span></code> (function)</h3>
<p>Perform a key agreement and return the raw shared secret.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement">psa_raw_key_agreement</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement">psa_raw_key_agreement</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
const uint8_t * peer_key,
size_t peer_key_length,
uint8_t * output,
@@ -105,13 +125,13 @@
<dd>The key agreement algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_RAW_KEY_AGREEMENT" title="PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
<dd>Identifier of the private key to use.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
<dd>Public key of the peer. It must be in the same format that <a class="reference internal" href="../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> accepts. The standard formats for public keys are documented in the documentation of <a class="reference internal" href="../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>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
<dd>Size of <code class="docutils literal"><span class="pre">peer_key</span></code> in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
-<dd>Buffer where the decrypted message is to be written.</dd>
+<dd>Buffer where the raw shared secret is to be written.</dd>
<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes.
This must be appropriate for the keys:</p>
@@ -130,7 +150,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a key agreement algorithm</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
@@ -165,26 +185,26 @@
</div>
</div>
<div class="section" id="combining-key-agreement-and-key-derivation">
-<h2>Combining key agreement and key derivation</h2>
+<h2>10.9.3. Combining key agreement and key derivation</h2>
<div class="section" id="psa_key_derivation_key_agreement">
<span id="c.psa_key_derivation_key_agreement"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_key_agreement</span></code> (function)</h3>
<p>Perform a key agreement and use the shared secret as input to a key derivation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement">psa_key_derivation_key_agreement</a>(<a class="reference internal" href="kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
<a class="reference internal" href="kdf.html#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
const uint8_t * peer_key,
size_t peer_key_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
-<dd>The key derivation operation object to use. It must have been set up with <a class="reference internal" href="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 key agreement and derivation algorithm <code class="docutils literal"><span class="pre">alg</span></code> (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true and <a class="reference internal" href="#c.PSA_ALG_IS_RAW_KEY_AGREEMENT" title="PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is false). The operation must be ready for an input of the type given by <code class="docutils literal"><span class="pre">step</span></code>.</dd>
+<dd>The key derivation operation object to use. It must have been set up with <a class="reference internal" href="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 key agreement and derivation algorithm <code class="docutils literal"><span class="pre">alg</span></code> (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true and <a class="reference internal" href="#c.PSA_ALG_IS_RAW_KEY_AGREEMENT" title="PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is false). The operation must be ready for an input of the type given by <code class="docutils literal"><span class="pre">step</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
<dd>Which step the input data is for.</dd>
<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
<dd>Identifier of the private key to use.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
<dd>Public key of the peer. The peer key must be in the same format that <a class="reference internal" href="../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> accepts for the public key type corresponding to the type of private_key. That is, this function performs the equivalent of <a class="reference internal" href="../keys/management.html#c.psa_import_key" title="psa_import_key"><code class="docutils literal"><span class="pre">psa_import_key</span></code></a><code class="docutils literal"><span class="pre">(...,</span> </code><code class="docutils literal"><span class="pre">peer_key</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">peer_key_length</span></code><code class="docutils literal"><span class="pre">)</span></code> where with key attributes indicating the public key type corresponding to the type of <code class="docutils literal"><span class="pre">private_key</span></code>. For example, for EC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of <a class="reference internal" href="../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>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
@@ -199,7 +219,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>, or <code class="docutils literal"><span class="pre">peer_key</span></code> is not valid for <code class="docutils literal"><span class="pre">alg</span></code> or not compatible with <code class="docutils literal"><span class="pre">private_key</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -229,7 +249,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.9.4. Support macros</h2>
<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_BASE">
<span id="c.PSA_ALG_KEY_AGREEMENT_GET_BASE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE</span></code> (macro)</h3>
<p>Get the raw key agreement algorithm from a full key agreement algorithm.</p>
@@ -239,7 +259,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A key agreement algorithm identifier (value of type <a class="reference internal" href="../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> such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A key agreement algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The underlying raw key agreement algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
@@ -256,7 +276,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A key agreement algorithm identifier (value of type <a class="reference internal" href="../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> such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A key agreement algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The underlying key derivation algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
@@ -273,7 +293,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a raw key agreement algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -290,7 +310,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a finite field Diffie-Hellman algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
@@ -306,7 +326,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an elliptic curve Diffie-Hellman algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
@@ -356,55 +376,52 @@
</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="#">Key agreement</a><ul>
-<li><a class="reference internal" href="#key-agreement-algorithms">Key agreement algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_FFDH"><code class="docutils literal"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_ECDH"><code class="docutils literal"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#standalone-key-agreement">Standalone key agreement</a><ul>
-<li><a class="reference internal" href="#psa_raw_key_agreement"><code class="docutils literal"><span class="pre">psa_raw_key_agreement</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#combining-key-agreement-and-key-derivation">Combining key agreement and key derivation</a><ul>
-<li><a class="reference internal" href="#psa_key_derivation_key_agreement"><code class="docutils literal"><span class="pre">psa_key_derivation_key_agreement</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_KEY_AGREEMENT_GET_BASE"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_KEY_AGREEMENT_GET_KDF"><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_FFDH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_FFDH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_ECDH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="pke.html" title="previous chapter">Asymmetric encryption</a></li>
- <li>Next: <a href="rng.html" title="next chapter">Other cryptographic services</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/ka.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.9. Key agreement</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#key-agreement-algorithms">10.9.1. Key agreement algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#standalone-key-agreement">10.9.2. Standalone key agreement</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#combining-key-agreement-and-key-derivation">10.9.3. Combining key agreement and key derivation</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.9.4. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -420,15 +437,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/ka.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/kdf.html b/docs/html/api/ops/kdf.html
index 0fa88a6..38371cc 100644
--- a/docs/html/api/ops/kdf.html
+++ b/docs/html/api/ops/kdf.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Key derivation — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.6. Key derivation — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Asymmetric signature" href="sign.html" />
- <link rel="prev" title="Authenticated encryption with associated data (AEAD)" href="aead.html" />
+ <link rel="next" title="10.7. Asymmetric signature" href="sign.html" />
+ <link rel="prev" title="10.5. Authenticated encryption with associated data (AEAD)" href="aead.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,9 +41,9 @@
<div class="body" role="main">
<div class="section" id="key-derivation">
-<span id="kdf"></span><h1>Key derivation</h1>
+<span id="kdf"></span><h1>10.6. Key derivation</h1>
<div class="section" id="key-derivation-algorithms">
-<span id="id1"></span><h2>Key derivation algorithms</h2>
+<span id="id1"></span><h2>10.6.1. Key derivation algorithms</h2>
<div class="section" id="PSA_ALG_HKDF">
<span id="c.PSA_ALG_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</h3>
<p>Macro to build an HKDF algorithm.</p>
@@ -52,12 +53,13 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding HKDF algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_HKDF" title="PSA_ALG_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> is HKDF using HMAC-SHA-256.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
+<p>This is the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) specified by <span><em>HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</em> <a class="reference internal" href="../../about.html#citation-rfc5869"><span class="cite">[RFC5869]</span></a></span>.</p>
<p>This key derivation algorithm uses the following inputs:</p>
<ul class="simple">
<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SALT" title="PSA_KEY_DERIVATION_INPUT_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code></a> is the salt used in the “extract” step. It is optional; if omitted, the derivation uses an empty salt.</li>
@@ -65,6 +67,7 @@
<li><a class="reference internal" href="#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> is the info string used in the “expand” step.</li>
</ul>
<p>If <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SALT" title="PSA_KEY_DERIVATION_INPUT_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code></a> is provided, it must be before <a class="reference internal" href="#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>. <a class="reference internal" href="#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> can be provided at any time after setup and before starting to generate output.</p>
+<p>Each input may only be passed once.</p>
</div>
<div class="section" id="PSA_ALG_TLS12_PRF">
<span id="c.PSA_ALG_TLS12_PRF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</h3>
@@ -75,19 +78,20 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding TLS-1.2 PRF algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_TLS12_PRF" title="PSA_ALG_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> represents the TLS 1.2 PRF using HMAC-SHA-256.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">RFC 5246 §5</a>. It is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
+<p>TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in <span><em>The Transport Layer Security (TLS) Protocol Version 1.2</em> <a class="reference internal" href="../../about.html#citation-rfc5246"><span class="cite">[RFC5246]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">§5</a>. It is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
<ul class="simple">
<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SEED" title="PSA_KEY_DERIVATION_INPUT_SEED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code></a> is the seed.</li>
<li><a class="reference internal" href="#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> is the secret key.</li>
<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_LABEL" title="PSA_KEY_DERIVATION_INPUT_LABEL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code></a> is the label.</li>
</ul>
+<p>Each input may only be passed once.</p>
<p>For the application to TLS-1.2 key expansion:</p>
<ul class="simple">
<li>The seed is the concatenation of <code class="docutils literal"><span class="pre">ServerHello.Random</span> <span class="pre">+</span> <span class="pre">ClientHello.Random</span></code>.</li>
@@ -103,19 +107,20 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding TLS-1.2 PSK to MS algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> represents the TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK) through the application of padding (<a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-2">RFC 4279 §2</a>) and the TLS-1.2 PRF (<a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">RFC 5246 §5</a>). The latter is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
+<p>In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK) through the application of padding (<span><em>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</em> <a class="reference internal" href="../../about.html#citation-rfc4279"><span class="cite">[RFC4279]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-2">§2</a>) and the TLS-1.2 PRF (<span><em>The Transport Layer Security (TLS) Protocol Version 1.2</em> <a class="reference internal" href="../../about.html#citation-rfc5246"><span class="cite">[RFC5246]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">§5</a>). The latter is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
<ul class="simple">
<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SEED" title="PSA_KEY_DERIVATION_INPUT_SEED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code></a> is the seed.</li>
<li><a class="reference internal" href="#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> is the PSK. The PSK must not be larger than <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code></a>.</li>
<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_LABEL" title="PSA_KEY_DERIVATION_INPUT_LABEL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code></a> is the label.</li>
</ul>
+<p>Each input may only be passed once.</p>
<p>For the application to TLS-1.2:</p>
<ul class="simple">
<li>The seed, which is forwarded to the TLS-1.2 PRF, is the concatenation of the <code class="docutils literal"><span class="pre">ClientHello.Random</span> <span class="pre">+</span> <span class="pre">ServerHello.Random</span></code>.</li>
@@ -124,7 +129,7 @@
</div>
</div>
<div class="section" id="input-step-types">
-<h2>Input step types</h2>
+<h2>10.6.2. Input step types</h2>
<div class="section" id="psa_key_derivation_step_t">
<span id="c.psa_key_derivation_step_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_step_t</span></code> (type)</h3>
<p>Encoding of the step of a key derivation.</p>
@@ -183,7 +188,7 @@
</div>
</div>
<div class="section" id="key-derivation-functions">
-<h2>Key derivation functions</h2>
+<h2>10.6.3. Key derivation functions</h2>
<div class="section" id="psa_key_derivation_operation_t">
<span id="c.psa_key_derivation_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code> (type)</h3>
<p>The type of the state object for key derivation operations.</p>
@@ -237,14 +242,14 @@
<p>Set up a key derivation operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_setup" title="psa_key_derivation_setup">psa_key_derivation_setup</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
<dd>The key derivation operation object to set up. It must have been initialized but not set up yet.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The key derivation algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The key derivation algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -401,7 +406,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
-<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>.</dd>
+<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>. This can happen if the application provides a step out of order or repeats a step that may not be repeated.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
</dl>
@@ -416,7 +421,7 @@
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key">psa_key_derivation_input_key</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
<a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -425,7 +430,7 @@
<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
<dd>Which step the input data is for.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>Identifier of the key. It must have an appropriate type for <code class="docutils literal"><span class="pre">step</span></code> and must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
+<dd>Identifier of the key. It must have an appropriate type for <code class="docutils literal"><span class="pre">step</span></code> and must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -434,7 +439,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
@@ -454,7 +459,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
-<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>.</dd>
+<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>. This can happen if the application provides a step out of order or repeats a step that may not be repeated.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
</dl>
@@ -506,7 +511,7 @@
<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
</dl>
<p class="rubric">Description</p>
-<p>This function calculates output bytes from a key derivation algorithm and return those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.</p>
+<p>This function calculates output bytes from a key derivation algorithm and returns those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.</p>
<p>If this function returns an error status other than <a class="reference internal" href="../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>, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>.</p>
</div>
<div class="section" id="psa_key_derivation_output_key">
@@ -515,16 +520,29 @@
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key">psa_key_derivation_output_key</a>(const <a class="reference internal" href="../keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
-<dd>The attributes for the new key.</dd>
+<dd><p class="first">The attributes for the new key.
+This function uses the attributes as follows:</p>
+<ul class="simple">
+<li>The key type is required. It cannot be an asymmetric public key.</li>
+<li>The key size is required. It must be a valid size for the key type.</li>
+<li>The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see <a class="reference internal" href="../keys/policy.html#permitted-algorithms"><span class="secref">Permitted algorithms</span></a>.</li>
+<li>The key usage flags define what operations are permitted with the key, see <a class="reference internal" href="../keys/policy.html#key-usage-flags"><span class="secref">Key usage flags</span></a>.</li>
+<li>The key lifetime and identifier are required for a persistent key.</li>
+</ul>
+<div class="last admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling <a class="reference internal" href="../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> with the key’s identifier.</p>
+</div>
+</dd>
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
<dd>The key derivation operation object to read from.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>On success, an identifier for the newly created key. <a class="reference internal" href="../keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
+<dd>On success, an identifier for the newly created key. <a class="reference internal" href="../keys/ids.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -537,9 +555,13 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd>The key type or key size is not supported, either by the implementation in general or in this particular location.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
-<dd>The provided key attributes are not valid for the operation.</dd>
+<dd>The key attributes, as a whole, are invalid.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
+<dd>The key type is an asymmetric public key type.</dd>
+<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
+<dd>The key size is not a valid size for the key type.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The <a class="reference internal" href="#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> input was not provided through a key.</dd>
+<dd>The <a class="reference internal" href="#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> input was neither provided through a key nor the result of a key agreement.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The operation state is not valid: it must be active and completed all required input steps.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
@@ -562,43 +584,98 @@
<dd>The library has not been previously initialized by <a class="reference internal" href="../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>. It is implementation-dependent whether a failure to initialize results in this error code.</dd>
</dl>
<p class="rubric">Description</p>
-<p>This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, usage policy, type and size are taken from <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
+<p>This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, policy, type and size are taken from <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
<p>If the key derivation’s output is viewed as a stream of bytes, this function consumes the required number of bytes from the stream. The operation’s capacity decreases by the number of bytes used to derive the key.</p>
<p>If this function returns an error status other than <a class="reference internal" href="../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>, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#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>.</p>
-<p>How much output is produced and consumed from the operation, and how the key is derived, depends on the key type:</p>
-<ul>
-<li><p class="first">For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling <a class="reference internal" href="#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> and passing the resulting output to <a class="reference internal" href="../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>. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly <code class="docutils literal"><span class="pre">(bits/8)</span></code> bytes from the operation. The following key types defined in this specification follow this scheme:</p>
-<ul class="simple">
-<li><a class="reference internal" href="../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>;</li>
-<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a>;</li>
-<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a>;</li>
-<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DERIVE" title="PSA_KEY_TYPE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DERIVE</span></code></a>;</li>
-<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_HMAC" title="PSA_KEY_TYPE_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_HMAC</span></code></a>.</li>
-</ul>
-</li>
-<li><p class="first">For ECC keys on a Montgomery elliptic curve (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a><code class="docutils literal"><span class="pre">)</span></code>), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:</p>
-<ul class="simple">
-<li>Curve25519 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 255 bits): draw a 32-byte string and process it as specified in <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">RFC 7748 §5</a>.</li>
-<li>Curve448 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 448 bits): draw a 56-byte string and process it as specified in <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">RFC 7748 §5</a>.</li>
-</ul>
-</li>
-<li><p class="first">For key types for which the key is represented by a single sequence of <code class="docutils literal"><span class="pre">bits</span></code> bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length <code class="docutils literal"><span class="pre">ceiling(bits/8)</span></code> bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by <a class="reference internal" href="../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>. The following key types defined in this specification follow this scheme:</p>
-<ul>
-<li><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively. For example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.</p>
-</li>
-<li><p class="first">Finite-field Diffie-Hellman keys (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DH_KEY_PAIR" title="PSA_KEY_TYPE_DH_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_DH_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">dh_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">dh_family</span></code> designates any Diffie-Hellman family) and ECC keys on a Weierstrass elliptic curve (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ecc_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">ecc_family</span></code> designates a Weierstrass curve family). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, <em>N</em> - 2] where <em>N</em> is the boundary of the private key domain: <em>N</em> is the prime <em>p</em> for Diffie-Hellman, or the order of the curve’s base point for ECC. Add <code class="docutils literal"><span class="pre">1</span></code> to the resulting integer and use this as the private key <em>x</em>.</p>
-<p>This method allows compliance to NIST standards, specifically the methods titled <em>Key-Pair Generation by Testing Candidates</em> in the following publications:</p>
-<ul class="simple">
-<li><a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-56Ar3"><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em></a> (NIST SP 800-56A) §5.6.1.1.4 for Diffie-Hellman keys.</li>
-<li><a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-56Ar3">NIST SP 800-56A</a> §5.6.1.2.2 or <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.186-4"><em>FIPS Publication 186-4: Digital Signature Standard (DSS)</em></a> (FIPS 186-4) §B.4.2 for elliptic curve keys.</li>
-</ul>
-</li>
-</ul>
-</li>
-<li><p class="first">For other key types, including <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>, the way in which the operation output is consumed is implementation-defined.</p>
-</li>
-</ul>
+<p>How much output is produced and consumed from the operation, and how the key is derived, depends on the key type. <span><a class="reference internal" href="#std-key-derivation"><span class="numref">Table 5</span></a></span> describes the required key derivation procedures for standard key derivation algorithms. Implementations can use other methods for implementation-specific algorithms.</p>
<p>In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by the number of bytes read.</p>
+<table border="1" class="colwidths-given longtable docutils align-right" id="std-key-derivation">
+<caption><span class="caption-number">Table 5 </span><span class="caption-text">Standard key derivation process</span></caption>
+<colgroup>
+<col width="29%" />
+<col width="71%" />
+</colgroup>
+<thead valign="bottom">
+<tr class="row-odd"><th class="head">Key type</th>
+<th class="head">Key type details and derivation procedure</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr class="row-even"><td><p class="first">AES</p>
+<p>ARC4</p>
+<p>CAMELLIA</p>
+<p>ChaCha20</p>
+<p>SM4</p>
+<p>Secrets for derivation</p>
+<p class="last">HMAC</p>
+</td>
+<td><p class="first"><a class="reference internal" href="../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>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a></p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a></p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a></p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_SM4" title="PSA_KEY_TYPE_SM4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_SM4</span></code></a></p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DERIVE" title="PSA_KEY_TYPE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DERIVE</span></code></a></p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_HMAC" title="PSA_KEY_TYPE_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_HMAC</span></code></a></p>
+<p class="last">For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling <a class="reference internal" href="#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> and passing the resulting output to <a class="reference internal" href="../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>. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly <code class="docutils literal"><span class="pre">(bits/8)</span></code> bytes from the operation.</p>
+</td>
+</tr>
+<tr class="row-odd"><td>DES</td>
+<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 64 bits.</p>
+<p>This function generates a key using the following process:</p>
+<ol class="last arabic simple">
+<li>Draw an 8-byte string.</li>
+<li>Set/clear the parity bits in each byte.</li>
+<li>If the result is a forbidden weak key, discard the result and return to step 1.</li>
+<li>Output the string.</li>
+</ol>
+</td>
+</tr>
+<tr class="row-even"><td><p class="first">2-key 3DES</p>
+<p class="last">3-key 3DES</p>
+</td>
+<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 192 bits.</p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 128 bits.</p>
+<p>The two or three keys are generated by repeated application of the process used to generate a DES key.</p>
+<p class="last">For example, for 3-key 3DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.</p>
+</td>
+</tr>
+<tr class="row-odd"><td><p class="first">Finite-field Diffie-Hellman keys</p>
+<p class="last">ECC keys on a Weierstrass elliptic curve</p>
+</td>
+<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DH_KEY_PAIR" title="PSA_KEY_TYPE_DH_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_DH_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">dh_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">dh_family</span></code> designates any Diffie-Hellman family.</p>
+<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ecc_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">ecc_family</span></code> designates a Weierstrass curve family.</p>
+<p>These key types require the generation of a private key which is an integer in the range [1, <em>N</em> - 1], where <em>N</em> is the boundary of the private key domain: <em>N</em> is the prime <em>p</em> for Diffie-Hellman, or the order of the curve’s base point for ECC.</p>
+<p>Let <code class="docutils literal"><span class="pre">m</span></code> be the bit size of <em>N</em>, such that <code class="docutils literal"><span class="pre">2^m</span></code> > <em>N</em> >= <code class="docutils literal"><span class="pre">2^(m-1)</span></code>. This function generates the private key using the following process:</p>
+<ol class="arabic simple">
+<li>Draw a byte string of length <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code> bytes.</li>
+<li>If <code class="docutils literal"><span class="pre">m</span></code> is not a multiple of <code class="docutils literal"><span class="pre">8</span></code>, set the most significant <code class="docutils literal"><span class="pre">(8</span> <span class="pre">*</span> <span class="pre">ceiling(m/8)</span> <span class="pre">-</span> <span class="pre">m)</span></code> bits of the first byte in the string to zero.</li>
+<li>Convert the string to integer <em>k</em> by decoding it as a big-endian byte string.</li>
+<li>If <em>k</em> > <em>N</em> - <code class="docutils literal"><span class="pre">2</span></code>, discard the result and return to step 1.</li>
+<li>Output <em>k</em> + <code class="docutils literal"><span class="pre">1</span></code> as the private key.</li>
+</ol>
+<p>This method allows compliance to NIST standards, specifically the methods titled <em>Key-Pair Generation by Testing Candidates</em> in the following publications:</p>
+<ul class="last simple">
+<li><span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.6.1.1.4 for Diffie-Hellman keys.</li>
+<li><a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a> §5.6.1.2.2 or <span><em>FIPS Publication 186-4: Digital Signature Standard (DSS)</em> <a class="reference internal" href="../../about.html#citation-fips186-4"><span class="cite">[FIPS186-4]</span></a></span> §B.4.2 for elliptic curve keys.</li>
+</ul>
+</td>
+</tr>
+<tr class="row-even"><td>ECC keys on a Montgomery elliptic curve</td>
+<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a><code class="docutils literal"><span class="pre">)</span></code></p>
+<p>This function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:</p>
+<ul class="last simple">
+<li>Curve25519 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 255 bits): draw a 32-byte string and process it as specified in <span><em>Elliptic Curves for Security</em> <a class="reference internal" href="../../about.html#citation-rfc7748"><span class="cite">[RFC7748]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">§5</a>.</li>
+<li>Curve448 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 448 bits): draw a 56-byte string and process it as specified in <a class="reference internal" href="../../about.html#citation-rfc7748"><span class="cite">[RFC7748]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">§5</a>.</li>
+</ul>
+</td>
+</tr>
+<tr class="row-odd"><td><em>Other key types</em></td>
+<td><p class="first">This includes <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>.</p>
+<p class="last">The way in which the operation output is consumed is implementation-defined.</p>
+</td>
+</tr>
+</tbody>
+</table>
<p>For algorithms that take an input step <a class="reference internal" href="#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>, the input to that step must be provided with <a class="reference internal" href="#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>. Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.</p>
</div>
<div class="section" id="psa_key_derivation_abort">
@@ -632,7 +709,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.6.4. Support macros</h2>
<div class="section" id="PSA_ALG_IS_HKDF">
<span id="c.PSA_ALG_IS_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</h3>
<p>Whether the specified algorithm is an HKDF algorithm.</p>
@@ -642,7 +719,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an HKDF algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
@@ -658,7 +735,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a TLS-1.2 PRF algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
@@ -672,7 +749,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a TLS-1.2 PSK to MS algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
@@ -693,9 +770,9 @@
#define <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p>This implementation-defined value specifies the maximum length for the PSK input used with a <a class="reference internal" href="#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS()</span></code></a> key agreement algorithm.</p>
-<p>Quoting <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-5.3">RFC 4279 §5.3</a>:</p>
+<p>Quoting <span><em>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</em> <a class="reference internal" href="../../about.html#citation-rfc4279"><span class="cite">[RFC4279]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-5.3">§5.3</a>:</p>
<blockquote>
-<div>TLS implementations supporting these ciphersuites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.</div></blockquote>
+<div>TLS implementations supporting these cipher suites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.</div></blockquote>
<p>Therefore, it is recommended that implementations define <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code></a> with a value greater than or equal to <code class="docutils literal"><span class="pre">64</span></code>.</p>
</div>
</div>
@@ -706,69 +783,52 @@
</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="#">Key derivation</a><ul>
-<li><a class="reference internal" href="#key-derivation-algorithms">Key derivation algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#input-step-types">Input step types</a><ul>
-<li><a class="reference internal" href="#psa_key_derivation_step_t"><code class="docutils literal"><span class="pre">psa_key_derivation_step_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SECRET"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_LABEL"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_CONTEXT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_CONTEXT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SALT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_INFO"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SEED"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#key-derivation-functions">Key derivation functions</a><ul>
-<li><a class="reference internal" href="#psa_key_derivation_operation_t"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_operation_init"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_init</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_setup"><code class="docutils literal"><span class="pre">psa_key_derivation_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_get_capacity"><code class="docutils literal"><span class="pre">psa_key_derivation_get_capacity</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_set_capacity"><code class="docutils literal"><span class="pre">psa_key_derivation_set_capacity</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_input_bytes"><code class="docutils literal"><span class="pre">psa_key_derivation_input_bytes</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_input_key"><code class="docutils literal"><span class="pre">psa_key_derivation_input_key</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_output_bytes"><code class="docutils literal"><span class="pre">psa_key_derivation_output_bytes</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_output_key"><code class="docutils literal"><span class="pre">psa_key_derivation_output_key</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_key_derivation_abort"><code class="docutils literal"><span class="pre">psa_key_derivation_abort</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PRF</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_KEY_DERIVATION_UNLIMITED_CAPACITY"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_UNLIMITED_CAPACITY</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="aead.html" title="previous chapter">Authenticated encryption with associated data (AEAD)</a></li>
- <li>Next: <a href="sign.html" title="next chapter">Asymmetric signature</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/kdf.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.6. Key derivation</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#key-derivation-algorithms">10.6.1. Key derivation algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#input-step-types">10.6.2. Input step types</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#key-derivation-functions">10.6.3. Key derivation functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.6.4. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -784,15 +844,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/kdf.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/macs.html b/docs/html/api/ops/macs.html
index c53a533..38e608c 100644
--- a/docs/html/api/ops/macs.html
+++ b/docs/html/api/ops/macs.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Message authentication codes (MAC) — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.3. Message authentication codes (MAC) — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Unauthenticated ciphers" href="ciphers.html" />
- <link rel="prev" title="Message digests" href="hashes.html" />
+ <link rel="next" title="10.4. Unauthenticated ciphers" href="ciphers.html" />
+ <link rel="prev" title="10.2. Message digests" href="hashes.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,25 +41,26 @@
<div class="body" role="main">
<div class="section" id="message-authentication-codes-mac">
-<span id="macs"></span><h1>Message authentication codes (MAC)</h1>
+<span id="macs"></span><h1>10.3. Message authentication codes (MAC)</h1>
<div class="section" id="mac-algorithms">
-<span id="id1"></span><h2>MAC algorithms</h2>
+<span id="id1"></span><h2>10.3.1. MAC algorithms</h2>
<div class="section" id="PSA_ALG_HMAC">
<span id="c.PSA_ALG_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code> (macro)</h3>
-<p>Macro to build an HMAC algorithm.</p>
+<p>Macro to build an HMAC message-authentication-code algorithm from an underlying hash algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC">PSA_ALG_HMAC</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding HMAC algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
<p>For example, <a class="reference internal" href="#c.PSA_ALG_HMAC" title="PSA_ALG_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> is HMAC-SHA-256.</p>
+<p>The HMAC construction is defined in <span><em>HMAC: Keyed-Hashing for Message Authentication</em> <a class="reference internal" href="../../about.html#citation-rfc2104"><span class="cite">[RFC2104]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_TRUNCATED_MAC">
<span id="c.PSA_ALG_TRUNCATED_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TRUNCATED_MAC</span></code> (macro)</h3>
@@ -70,7 +72,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt>
-<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="../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> such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This can be a truncated or untruncated MAC algorithm.</dd>
+<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This can be a truncated or untruncated MAC algorithm.</dd>
<dt> <code class="docutils literal"><span class="pre">mac_length</span></code></dt>
<dd>Desired length of the truncated MAC in bytes. This must be at most the full length of the MAC and must be at least an implementation-specified minimum. The implementation-specified minimum must not be zero.</dd>
</dl>
@@ -91,31 +93,35 @@
</div>
<div class="section" id="PSA_ALG_CBC_MAC">
<span id="c.PSA_ALG_CBC_MAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CBC_MAC</span></code> (macro)</h3>
-<p>The CBC-MAC construction over a block cipher.</p>
+<p>The CBC-MAC message-authentication-code algorithm, constructed over a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CBC_MAC" title="PSA_ALG_CBC_MAC">PSA_ALG_CBC_MAC</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00100)
+#define <a class="reference internal" href="#c.PSA_ALG_CBC_MAC" title="PSA_ALG_CBC_MAC">PSA_ALG_CBC_MAC</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00100)
</pre>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">CBC-MAC is insecure in many cases. A more secure mode, such as <a class="reference internal" href="#c.PSA_ALG_CMAC" title="PSA_ALG_CMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_CMAC</span></code></a>, is recommended.</p>
</div>
+<p>The CBC-MAC algorithm must be used with a key for a block cipher. For example, one of <a class="reference internal" href="../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>
+<p>CBC-MAC is defined as <em>MAC Algorithm 1</em> in <span><em>ISO/IEC 9797-1:2011 Information technology — Security techniques — Message Authentication Codes (MACs) — Part 1: Mechanisms using a block cipher</em> <a class="reference internal" href="../../about.html#citation-iso9797"><span class="cite">[ISO9797]</span></a></span>.</p>
</div>
<div class="section" id="PSA_ALG_CMAC">
<span id="c.PSA_ALG_CMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_CMAC</span></code> (macro)</h3>
-<p>The CMAC construction over a block cipher.</p>
+<p>The CMAC message-authentication-code algorithm, constructed over a block cipher.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_CMAC" title="PSA_ALG_CMAC">PSA_ALG_CMAC</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00200)
+#define <a class="reference internal" href="#c.PSA_ALG_CMAC" title="PSA_ALG_CMAC">PSA_ALG_CMAC</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x03c00200)
</pre>
+<p>The CMAC algorithm must be used with a key for a block cipher. For example, when used with a key with type <a class="reference internal" href="../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>, the resulting operation is AES-CMAC.</p>
+<p>CMAC is defined in <span><em>NIST Special Publication 800-38B: Recommendation for Block Cipher Modes of Operation: the CMAC Mode for Authentication</em> <a class="reference internal" href="../../about.html#citation-sp800-38b"><span class="cite">[SP800-38B]</span></a></span>.</p>
</div>
</div>
<div class="section" id="single-part-mac-functions">
-<h2>Single-part MAC functions</h2>
+<h2>10.3.2. Single-part MAC functions</h2>
<div class="section" id="psa_mac_compute">
<span id="c.psa_mac_compute"></span><h3><code class="docutils literal"><span class="pre">psa_mac_compute</span></code> (function)</h3>
<p>Calculate the message authentication code (MAC) of a message.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_compute" title="psa_mac_compute">psa_mac_compute</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_compute" title="psa_mac_compute">psa_mac_compute</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
uint8_t * mac,
@@ -126,9 +132,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the input message.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -153,7 +159,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -188,8 +194,8 @@
<span id="c.psa_mac_verify"></span><h3><code class="docutils literal"><span class="pre">psa_mac_verify</span></code> (function)</h3>
<p>Calculate the MAC of a message and compare it with a reference value.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_verify" title="psa_mac_verify">psa_mac_verify</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_verify" title="psa_mac_verify">psa_mac_verify</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
const uint8_t * mac,
@@ -199,9 +205,9 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
<dd>Buffer containing the input message.</dd>
<dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt>
@@ -220,7 +226,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -245,7 +251,7 @@
</div>
</div>
<div class="section" id="multi-part-mac-operations">
-<h2>Multi-part MAC operations</h2>
+<h2>10.3.3. Multi-part MAC operations</h2>
<div class="section" id="psa_mac_operation_t">
<span id="c.psa_mac_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code> (type)</h3>
<p>The type of the state object for multi-part MAC operations.</p>
@@ -299,8 +305,8 @@
<p>Set up a multi-part MAC calculation operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_sign_setup" title="psa_mac_sign_setup">psa_mac_sign_setup</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -308,9 +314,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -319,7 +325,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -365,8 +371,8 @@
<p>Set up a multi-part MAC verification operation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_mac_verify_setup" title="psa_mac_verify_setup">psa_mac_verify_setup</a>(<a class="reference internal" href="#c.psa_mac_operation_t" title="psa_mac_operation_t">psa_mac_operation_t</a> * operation,
- <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
+ <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
@@ -374,9 +380,9 @@
<dd>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</dd>
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>The MAC algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
@@ -385,7 +391,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">key</span></code> is not compatible with <code class="docutils literal"><span class="pre">alg</span></code>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -612,7 +618,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.3.4. Support macros</h2>
<div class="section" id="PSA_ALG_IS_HMAC">
<span id="c.PSA_ALG_IS_HMAC"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code> (macro)</h3>
<p>Whether the specified algorithm is an HMAC algorithm.</p>
@@ -622,7 +628,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an HMAC algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -638,7 +644,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a MAC algorithm based on a block cipher, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -652,7 +658,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">mac_alg</span></code></dt>
-<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="../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> such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This can be a truncated or untruncated MAC algorithm.</dd>
+<dd>A MAC algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This can be a truncated or untruncated MAC algorithm.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding MAC algorithm with a full length MAC.</p>
@@ -672,7 +678,7 @@
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the MAC key in bits.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>A MAC algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
+<dd>A MAC algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_MAC" title="PSA_ALG_IS_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_MAC</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
</dl>
<p class="rubric">Returns</p>
<p>The MAC length for the specified algorithm with the specified key parameters.</p>
@@ -701,63 +707,52 @@
</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="#">Message authentication codes (MAC)</a><ul>
-<li><a class="reference internal" href="#mac-algorithms">MAC algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_HMAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_TRUNCATED_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_TRUNCATED_MAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CBC_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_CBC_MAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_CMAC"><code class="docutils literal"><span class="pre">PSA_ALG_CMAC</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#single-part-mac-functions">Single-part MAC functions</a><ul>
-<li><a class="reference internal" href="#psa_mac_compute"><code class="docutils literal"><span class="pre">psa_mac_compute</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_verify"><code class="docutils literal"><span class="pre">psa_mac_verify</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#multi-part-mac-operations">Multi-part MAC operations</a><ul>
-<li><a class="reference internal" href="#psa_mac_operation_t"><code class="docutils literal"><span class="pre">psa_mac_operation_t</span></code> (type)</a></li>
-<li><a class="reference internal" href="#PSA_MAC_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#psa_mac_operation_init"><code class="docutils literal"><span class="pre">psa_mac_operation_init</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_sign_setup"><code class="docutils literal"><span class="pre">psa_mac_sign_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_verify_setup"><code class="docutils literal"><span class="pre">psa_mac_verify_setup</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_update"><code class="docutils literal"><span class="pre">psa_mac_update</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_sign_finish"><code class="docutils literal"><span class="pre">psa_mac_sign_finish</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_verify_finish"><code class="docutils literal"><span class="pre">psa_mac_verify_finish</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_mac_abort"><code class="docutils literal"><span class="pre">psa_mac_abort</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_HMAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HMAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_BLOCK_CIPHER_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_IS_BLOCK_CIPHER_MAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_FULL_LENGTH_MAC"><code class="docutils literal"><span class="pre">PSA_ALG_FULL_LENGTH_MAC</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_MAC_LENGTH"><code class="docutils literal"><span class="pre">PSA_MAC_LENGTH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_MAC_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_MAC_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="hashes.html" title="previous chapter">Message digests</a></li>
- <li>Next: <a href="ciphers.html" title="next chapter">Unauthenticated ciphers</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/macs.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.3. Message authentication codes (MAC)</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#mac-algorithms">10.3.1. MAC algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#single-part-mac-functions">10.3.2. Single-part MAC functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#multi-part-mac-operations">10.3.3. Multi-part MAC operations</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.3.4. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -773,15 +768,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/macs.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/pke.html b/docs/html/api/ops/pke.html
index 0d364c5..27d7a3e 100644
--- a/docs/html/api/ops/pke.html
+++ b/docs/html/api/ops/pke.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Asymmetric encryption — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.8. Asymmetric encryption — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Key agreement" href="ka.html" />
- <link rel="prev" title="Asymmetric signature" href="sign.html" />
+ <link rel="next" title="10.9. Key agreement" href="ka.html" />
+ <link rel="prev" title="10.7. Asymmetric signature" href="sign.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,42 +41,43 @@
<div class="body" role="main">
<div class="section" id="asymmetric-encryption">
-<span id="pke"></span><h1>Asymmetric encryption</h1>
+<span id="pke"></span><h1>10.8. Asymmetric encryption</h1>
<div class="section" id="asymmetric-encryption-algorithms">
-<span id="id1"></span><h2>Asymmetric encryption algorithms</h2>
+<span id="id1"></span><h2>10.8.1. Asymmetric encryption algorithms</h2>
<div class="section" id="PSA_ALG_RSA_PKCS1V15_CRYPT">
<span id="c.PSA_ALG_RSA_PKCS1V15_CRYPT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_CRYPT</span></code> (macro)</h3>
-<p>RSA PKCS#1 v1.5 encryption.</p>
+<p>The RSA PKCS#1 v1.5 asymmetric encryption algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_CRYPT" title="PSA_ALG_RSA_PKCS1V15_CRYPT">PSA_ALG_RSA_PKCS1V15_CRYPT</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x07000200)
+#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_CRYPT" title="PSA_ALG_RSA_PKCS1V15_CRYPT">PSA_ALG_RSA_PKCS1V15_CRYPT</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x07000200)
</pre>
+<p>This encryption scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-7.2">§7.2</a> under the name RSAES-PKCS-v1_5.</p>
</div>
<div class="section" id="PSA_ALG_RSA_OAEP">
<span id="c.PSA_ALG_RSA_OAEP"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_OAEP</span></code> (macro)</h3>
-<p>RSA OAEP encryption.</p>
+<p>The RSA OAEP asymmetric encryption algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_OAEP" title="PSA_ALG_RSA_OAEP">PSA_ALG_RSA_OAEP</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>The hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true) to use for MGF1.</dd>
+<dd>The hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true) to use for <em>MGF1</em>.</dd>
</dl>
<p class="rubric">Returns</p>
-<p>The corresponding RSA OAEP signature algorithm.</p>
+<p>The corresponding RSA OAEP encryption algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>This is the encryption scheme defined by <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html">RFC 8017</a> (PKCS#1: RSA Cryptography Specifications) under the name RSAES-OAEP, with the message generation function MGF1.</p>
+<p>This encryption scheme is defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-7.1">§7.1</a> under the name RSAES-OAEP, with the mask generation function <em>MGF1</em> defined in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#appendix-B">Appendix B</a>.</p>
</div>
</div>
<div class="section" id="asymmetric-encryption-functions">
-<h2>Asymmetric encryption functions</h2>
+<h2>10.8.2. Asymmetric encryption functions</h2>
<div class="section" id="psa_asymmetric_encrypt">
<span id="c.psa_asymmetric_encrypt"></span><h3><code class="docutils literal"><span class="pre">psa_asymmetric_encrypt</span></code> (function)</h3>
<p>Encrypt a short message with a public key.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt">psa_asymmetric_encrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt">psa_asymmetric_encrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
const uint8_t * salt,
@@ -88,7 +90,7 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifer of the key to use for the operation. It must be a public key or an asymmetric key pair.
-It must allow the usage <a class="reference internal" href="../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>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric encryption algorithm that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
@@ -119,7 +121,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE" title="PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
@@ -155,8 +157,8 @@
<span id="c.psa_asymmetric_decrypt"></span><h3><code class="docutils literal"><span class="pre">psa_asymmetric_decrypt</span></code> (function)</h3>
<p>Decrypt a short message with a private key.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt">psa_asymmetric_decrypt</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt">psa_asymmetric_decrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
const uint8_t * salt,
@@ -169,7 +171,7 @@
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair.
-It must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
+It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric encryption algorithm that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
@@ -200,7 +202,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE" title="PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
@@ -236,7 +238,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.8.3. Support macros</h2>
<div class="section" id="PSA_ALG_IS_RSA_OAEP">
<span id="c.PSA_ALG_IS_RSA_OAEP"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_OAEP</span></code> (macro)</h3>
<p>Whether the specified algorithm is an RSA OAEP encryption algorithm.</p>
@@ -246,7 +248,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA OAEP algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -266,7 +268,7 @@
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the key in bits.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The signature algorithm.</dd>
+<dd>The asymmetric encryption algorithm.</dd>
</dl>
<p class="rubric">Returns</p>
<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#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> will not fail with <a class="reference internal" href="../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 parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or <code class="docutils literal"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
@@ -301,12 +303,12 @@
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the key in bits.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>The signature algorithm.</dd>
+<dd>The asymmetric encryption algorithm.</dd>
</dl>
<p class="rubric">Returns</p>
<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#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> will not fail with <a class="reference internal" href="../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 parameters are a valid combination that is not supported by the implementation, this macro must return either a sensible size or <code class="docutils literal"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
<p class="rubric">Description</p>
-<p>This macro returns a sufficient buffer size for a ciphertext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the ciphertext might be smaller, depending on the algorithm.</p>
+<p>This macro returns a sufficient buffer size for a plaintext produced using a key of the specified type and size, with the specified algorithm. Note that the actual size of the plaintext might be smaller, depending on the algorithm.</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">This function might evaluate its arguments multiple times or zero times. Providing arguments that have side effects will result in implementation-specific behavior, and is non-portable.</p>
@@ -330,49 +332,51 @@
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
- <div class="sphinxsidebarwrapper">
- <h3><a href="../../index.html">Table Of Contents</a></h3>
- <ul>
-<li><a class="reference internal" href="#">Asymmetric encryption</a><ul>
-<li><a class="reference internal" href="#asymmetric-encryption-algorithms">Asymmetric encryption algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_RSA_PKCS1V15_CRYPT"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_CRYPT</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_RSA_OAEP"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_OAEP</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#asymmetric-encryption-functions">Asymmetric encryption functions</a><ul>
-<li><a class="reference internal" href="#psa_asymmetric_encrypt"><code class="docutils literal"><span class="pre">psa_asymmetric_encrypt</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_asymmetric_decrypt"><code class="docutils literal"><span class="pre">psa_asymmetric_decrypt</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_RSA_OAEP"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_OAEP</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="sign.html" title="previous chapter">Asymmetric signature</a></li>
- <li>Next: <a href="ka.html" title="next chapter">Key agreement</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/pke.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.8. Asymmetric encryption</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption-algorithms">10.8.1. Asymmetric encryption algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption-functions">10.8.2. Asymmetric encryption functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.8.3. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -388,15 +392,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/pke.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/rng.html b/docs/html/api/ops/rng.html
index 23476b5..949fe20 100644
--- a/docs/html/api/ops/rng.html
+++ b/docs/html/api/ops/rng.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Other cryptographic services — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.10. Other cryptographic services — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="Example header file" href="../../appendix/example_header.html" />
- <link rel="prev" title="Key agreement" href="ka.html" />
+ <link rel="prev" title="10.9. Key agreement" href="ka.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,9 +41,9 @@
<div class="body" role="main">
<div class="section" id="other-cryptographic-services">
-<h1>Other cryptographic services</h1>
+<h1>10.10. Other cryptographic services</h1>
<div class="section" id="random-number-generation">
-<span id="rng"></span><h2>Random number generation</h2>
+<span id="rng"></span><h2>10.10.1. Random number generation</h2>
<div class="section" id="psa_generate_random">
<span id="c.psa_generate_random"></span><h3><code class="docutils literal"><span class="pre">psa_generate_random</span></code> (function)</h3>
<p>Generate random bytes.</p>
@@ -94,35 +95,49 @@
</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="#">Other cryptographic services</a><ul>
-<li><a class="reference internal" href="#random-number-generation">Random number generation</a><ul>
-<li><a class="reference internal" href="#psa_generate_random"><code class="docutils literal"><span class="pre">psa_generate_random</span></code> (function)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="ka.html" title="previous chapter">Key agreement</a></li>
- <li>Next: <a href="../../appendix/example_header.html" title="next chapter">Example header file</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/rng.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.10. Other cryptographic services</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#random-number-generation">10.10.1. Random number generation</a></li>
+</ul>
+</li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -138,15 +153,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/rng.rst.txt"
- rel="nofollow">Page source</a>
</div>
diff --git a/docs/html/api/ops/sign.html b/docs/html/api/ops/sign.html
index c8fb817..9a1cb86 100644
--- a/docs/html/api/ops/sign.html
+++ b/docs/html/api/ops/sign.html
@@ -5,26 +5,27 @@
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
- <title>Asymmetric signature — PSA Crypto API 1.0.0 documentation</title>
+ <title>10.7. Asymmetric signature — PSA Crypto API 1.0.1 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
- VERSION: '1.0.0',
+ VERSION: '1.0.1',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
- HAS_SOURCE: true,
+ HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
+ <link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
- <link rel="next" title="Asymmetric encryption" href="pke.html" />
- <link rel="prev" title="Key derivation" href="kdf.html" />
+ <link rel="next" title="10.8. Asymmetric encryption" href="pke.html" />
+ <link rel="prev" title="10.6. Key derivation" href="kdf.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
@@ -40,105 +41,131 @@
<div class="body" role="main">
<div class="section" id="asymmetric-signature">
-<span id="sign"></span><h1>Asymmetric signature</h1>
+<span id="sign"></span><h1>10.7. Asymmetric signature</h1>
<div class="section" id="asymmetric-signature-algorithms">
-<span id="sign-algorithms"></span><h2>Asymmetric signature algorithms</h2>
+<span id="sign-algorithms"></span><h2>10.7.1. Asymmetric signature algorithms</h2>
<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN">
<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code> (macro)</h3>
-<p>RSA PKCS#1 v1.5 signature with hashing.</p>
+<p>The RSA PKCS#1 v1.5 message signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN" title="PSA_ALG_RSA_PKCS1V15_SIGN">PSA_ALG_RSA_PKCS1V15_SIGN</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a usage policy.</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding RSA PKCS#1 v1.5 signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>This is the signature scheme defined by <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html">RFC 8017</a> (PKCS#1: RSA Cryptography Specifications) under the name RSASSA-PKCS1-v1_5.</p>
+<p>This algorithm can be used with both the message and hash signature functions.</p>
+<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
+<p>When used with <a class="reference internal" href="#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> or <a class="reference internal" href="#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>, the provided <code class="docutils literal"><span class="pre">hash</span></code> parameter is used as <em>H</em> from step 2 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>H</em> is usually the message digest, using the <code class="docutils literal"><span class="pre">hash_alg</span></code> hash algorithm.</p>
</div>
<div class="section" id="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">
<span id="c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code> (macro)</h3>
-<p>Raw PKCS#1 v1.5 signature.</p>
+<p>The raw RSA PKCS#1 v1.5 signature algorithm, without hashing.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000200))
+#define <a class="reference internal" href="#c.PSA_ALG_RSA_PKCS1V15_SIGN_RAW" title="PSA_ALG_RSA_PKCS1V15_SIGN_RAW">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000200)
</pre>
-<p>The input to this algorithm is the DigestInfo structure used by <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">RFC 8017 §9.2</a> (PKCS#1: RSA Cryptography Specifications), in steps 3–6.</p>
+<p>This algorithm can be only used with the <a class="reference internal" href="#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="#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> functions.</p>
+<p>This signature scheme is defined by <span><em>PKCS #1: RSA Cryptography Specifications Version 2.2</em> <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.2">§8.2</a> under the name RSASSA-PKCS1-v1_5.</p>
+<p>The <code class="docutils literal"><span class="pre">hash</span></code> parameter to <a class="reference internal" href="#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> or <a class="reference internal" href="#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> is used as <em>T</em> from step 3 onwards in the message encoding algorithm <code class="docutils literal"><span class="pre">EMSA-PKCS1-V1_5-ENCODE()</span></code> in <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-9.2">§9.2</a>. <em>T</em> is the DER encoding of the <em>DigestInfo</em> structure normally produced by step 2 in the message encoding algorithm.</p>
</div>
<div class="section" id="PSA_ALG_RSA_PSS">
<span id="c.PSA_ALG_RSA_PSS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code> (macro)</h3>
-<p>RSA PSS signature with hashing.</p>
+<p>The RSA PSS message signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_RSA_PSS" title="PSA_ALG_RSA_PSS">PSA_ALG_RSA_PSS</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a usage policy.</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding RSA PSS signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>This is the signature scheme defined by <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html">RFC 8017</a> (PKCS#1: RSA Cryptography Specifications) under the name RSASSA-PSS, with the message generation function MGF1, and with a salt length equal to the length of the hash. The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.</p>
+<p>This algorithm can be used with both the message and hash signature functions.</p>
+<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
+<p>This is the signature scheme defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#section-8.1">§8.1</a> under the name RSASSA-PSS, with the following options:</p>
+<ul class="simple">
+<li>The mask generation function is <em>MGF1</em> defined by <a class="reference internal" href="../../about.html#citation-rfc8017"><span class="cite">[RFC8017]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8017.html#appendix-B">Appendix B</a>.</li>
+<li>The salt length is equal to the length of the hash.</li>
+<li>The specified hash algorithm is used to hash the input message, to create the salted hash, and for the mask generation.</li>
+</ul>
</div>
<div class="section" id="PSA_ALG_ECDSA">
<span id="c.PSA_ALG_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code> (macro)</h3>
-<p>ECDSA signature with hashing.</p>
+<p>The randomized ECDSA signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA">PSA_ALG_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a usage policy.</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
-<p>The corresponding ECDSA signature algorithm.</p>
+<p>The corresponding randomized ECDSA signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>This is the <em>Elliptic Curve Digital Signature Algorithm (ECDSA)</em> defined by ANSI X9.62-2005, with a random per-message secret number (<em>k</em>).</p>
+<p>This algorithm can be used with both the message and hash signature functions.</p>
+<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
+<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
+</div>
+<p>This signature scheme is defined by <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="../../about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span>, and also by <span><em>Public Key Cryptography For The Financial Services Industry: The Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-x9-62"><span class="cite">[X9-62]</span></a></span>, with a random per-message secret number <em>k</em>.</p>
<p>The representation of the signature as a byte string consists of the concatenation of the signature values <em>r</em> and <em>s</em>. Each of <em>r</em> and <em>s</em> is encoded as an <em>N</em>-octet string, where <em>N</em> is the length of the base point of the curve in octets. Each value is represented in big-endian order, with the most significant octet first.</p>
</div>
<div class="section" id="PSA_ALG_ECDSA_ANY">
<span id="c.PSA_ALG_ECDSA_ANY"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA_ANY</span></code> (macro)</h3>
-<p>ECDSA signature without hashing.</p>
+<p>The randomized ECDSA signature scheme, without hashing.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_ECDSA_ANY" title="PSA_ALG_ECDSA_ANY">PSA_ALG_ECDSA_ANY</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000600))
+#define <a class="reference internal" href="#c.PSA_ALG_ECDSA_ANY" title="PSA_ALG_ECDSA_ANY">PSA_ALG_ECDSA_ANY</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>) 0x06000600)
</pre>
-<p>This is the same signature scheme as <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>, but without specifying a hash algorithm. This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the left as required to fit the curve size.</p>
+<p>This algorithm can be only used with the <a class="reference internal" href="#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="#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> functions.</p>
+<p>This algorithm is randomized: each invocation returns a different, equally valid signature.</p>
+<p>This is the same signature scheme as <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>, but without specifying a hash algorithm, and skipping the message hashing operation.</p>
+<p>This algorithm is only recommended to sign or verify a sequence of bytes that are an already-calculated hash. Note that the input is padded with zeros on the left or truncated on the right as required to fit the curve size.</p>
</div>
<div class="section" id="PSA_ALG_DETERMINISTIC_ECDSA">
<span id="c.PSA_ALG_DETERMINISTIC_ECDSA"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code> (macro)</h3>
-<p>Deterministic ECDSA signature with hashing.</p>
+<p>Deterministic ECDSA signature scheme, with hashing.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA">PSA_ALG_DETERMINISTIC_ECDSA</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
-<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a usage policy.</dd>
+<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true). This includes <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> when specifying the algorithm in a key policy.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding deterministic ECDSA signature algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
<p class="rubric">Description</p>
-<p>This is the deterministic ECDSA signature scheme defined by <a class="reference external" href="https://tools.ietf.org/html/rfc6979.html">RFC 6979</a>.</p>
+<p>This algorithm can be used with both the message and hash signature functions.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p>When based on the same hash algorithm, the verification operations for <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> are identical. A signature created using <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>. Similarly, a signature created using <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a> can be verified with the same key using either <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a> or <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a>.</p>
+<p class="last">In particular, it is impossible to determine whether a signature was produced with deterministic ECDSA or with randomized ECDSA: it is only possible to verify that a signature was made with ECDSA with the private key corresponding to the public key used for the verification.</p>
+</div>
+<p>This is the deterministic ECDSA signature scheme defined by <span><em>Deterministic Usage of the Digital Signature Algorithm (DSA) and Elliptic Curve Digital Signature Algorithm (ECDSA)</em> <a class="reference internal" href="../../about.html#citation-rfc6979"><span class="cite">[RFC6979]</span></a></span>.</p>
<p>The representation of a signature is the same as with <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDSA()</span></code></a>.</p>
-<p>Note that when this algorithm is used for verification, signatures made with randomized ECDSA (<a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code>) with the same private key are accepted. In other words, <a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> differs from <a class="reference internal" href="#c.PSA_ALG_ECDSA" title="PSA_ALG_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> only for signature, not for verification.</p>
</div>
</div>
<div class="section" id="asymmetric-signature-functions">
-<h2>Asymmetric signature functions</h2>
+<h2>10.7.2. Asymmetric signature functions</h2>
<div class="section" id="psa_sign_message">
<span id="c.psa_sign_message"></span><h3><code class="docutils literal"><span class="pre">psa_sign_message</span></code> (function)</h3>
<p>Sign a message with a private key. For hash-and-sign algorithms, this includes the hashing step.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
uint8_t * signature,
@@ -148,7 +175,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../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>.</dd>
+<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.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>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
@@ -175,7 +202,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../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> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.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> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
@@ -205,15 +232,15 @@
<p class="rubric">Description</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
-<p class="last">To perform a multi-part hash-and-sign signature algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> and then pass the resulting hash to <a class="reference internal" href="#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>. <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
+<p class="last">To perform a multi-part hash-and-sign signature algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> and then pass the resulting hash to <a class="reference internal" href="#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>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
</div>
</div>
<div class="section" id="psa_verify_message">
<span id="c.psa_verify_message"></span><h3><code class="docutils literal"><span class="pre">psa_verify_message</span></code> (function)</h3>
<p>Verify the signature of a message with a public key, using a hash-and-sign verification algorithm.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message">psa_verify_message</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_message" title="psa_verify_message">psa_verify_message</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * input,
size_t input_length,
const uint8_t * signature,
@@ -222,7 +249,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
+<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_MESSAGE" title="PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">input</span></code></dt>
@@ -241,7 +268,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_MESSAGE" title="PSA_KEY_USAGE_VERIFY_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_MESSAGE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
<dd>The calculation was performed successfully, but the passed signature is not a valid signature.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -268,15 +295,15 @@
<p class="rubric">Description</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
-<p class="last">To perform a multi-part hash-and-sign signature verification algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> to hash the message and then pass the resulting hash to <a class="reference internal" href="#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>. <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
+<p class="last">To perform a multi-part hash-and-sign signature verification algorithm, first use a <a class="reference internal" href="hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> to hash the message and then pass the resulting hash to <a class="reference internal" href="#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>. <a class="reference internal" href="algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_GET_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> can be used to determine the hash algorithm to use.</p>
</div>
</div>
<div class="section" id="psa_sign_hash">
<span id="c.psa_sign_hash"></span><h3><code class="docutils literal"><span class="pre">psa_sign_hash</span></code> (function)</h3>
<p>Sign an already-calculated hash with a private key.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash">psa_sign_hash</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_sign_hash" title="psa_sign_hash">psa_sign_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * hash,
size_t hash_length,
uint8_t * signature,
@@ -286,7 +313,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a>.</dd>
+<dd>Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm that separates the hash and sign operations (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
@@ -313,7 +340,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_HASH" title="PSA_KEY_USAGE_SIGN_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">signature</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_SIGN_OUTPUT_SIZE" title="PSA_SIGN_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_SIGNATURE_MAX_SIZE" title="PSA_SIGNATURE_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
@@ -352,8 +379,8 @@
<span id="c.psa_verify_hash"></span><h3><code class="docutils literal"><span class="pre">psa_verify_hash</span></code> (function)</h3>
<p>Verify the signature of a hash or short message using a public key.</p>
<pre class="literal-block">
-<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash">psa_verify_hash</a>(<a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
- <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
+<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_verify_hash" title="psa_verify_hash">psa_verify_hash</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
+ <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
const uint8_t * hash,
size_t hash_length,
const uint8_t * signature,
@@ -362,7 +389,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
-<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a>.</dd>
+<dd>Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An asymmetric signature algorithm that separates the hash and sign operations (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="#c.PSA_ALG_IS_SIGN_HASH" title="PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true), that is compatible with the type of <code class="docutils literal"><span class="pre">key</span></code>.</dd>
<dt> <code class="docutils literal"><span class="pre">hash</span></code></dt>
@@ -381,7 +408,7 @@
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
-<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
+<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_VERIFY_HASH" title="PSA_KEY_USAGE_VERIFY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_VERIFY_HASH</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_SIGNATURE" title="PSA_ERROR_INVALID_SIGNATURE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></a></dt>
<dd>The calculation was performed successfully, but the passed signature is not a valid signature.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
@@ -415,7 +442,7 @@
</div>
</div>
<div class="section" id="support-macros">
-<h2>Support macros</h2>
+<h2>10.7.3. Support macros</h2>
<div class="section" id="PSA_ALG_IS_SIGN_MESSAGE">
<span id="c.PSA_ALG_IS_SIGN_MESSAGE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code> (macro)</h3>
<p>Whether the specified algorithm is a signature algorithm that can be used with <a class="reference internal" href="#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="#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>.</p>
@@ -425,7 +452,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign an already-calculated hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -439,7 +466,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can be used to sign a hash. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a signature algorithm that can only be used to sign a message. <code class="docutils literal"><span class="pre">0</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a signature algorithm. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -453,7 +480,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PKCS#1 v1.5 signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -468,7 +495,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an RSA PSS signature algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -483,7 +510,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -498,7 +525,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a deterministic ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -515,7 +542,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a randomized ECDSA algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise.</p>
@@ -532,7 +559,7 @@
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
-<dd>An algorithm identifier (value of type <a class="reference internal" href="../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>).</dd>
+<dd>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a hash-and-sign algorithm that signs exactly the hash value, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
@@ -541,14 +568,14 @@
</div>
<div class="section" id="PSA_ALG_ANY_HASH">
<span id="c.PSA_ALG_ANY_HASH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code> (macro)</h3>
-<p>In a hash-and-sign algorithm policy, allow any hash algorithm.</p>
+<p>When setting a hash-and-sign algorithm in a key policy, permit any hash algorithm.</p>
<pre class="literal-block">
-#define <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a> ((<a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x020000ff)
+#define <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x020000ff)
</pre>
-<p>This value can be used to form the algorithm usage field of a policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash.
-A signature algorithm policy created using this macro is a wildcard policy, and <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_WILDCARD" title="PSA_ALG_IS_WILDCARD"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD()</span></code></a> will return true.</p>
+<p>This value can be used to form the permitted algorithm attribute of a key policy for a signature algorithm that is parametrized by a hash. A key with this policy can then be used to perform operations using the same signature algorithm parametrized with any supported hash.
+A signature algorithm created using this macro is a wildcard algorithm, and <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_WILDCARD" title="PSA_ALG_IS_WILDCARD"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_IS_WILDCARD()</span></code></a> will return true.</p>
<p>This value must not be used to build other algorithms that are parametrized over a hash. For any valid use of this macro to build an algorithm <code class="docutils literal"><span class="pre">alg</span></code>, <a class="reference internal" href="#c.PSA_ALG_IS_HASH_AND_SIGN" title="PSA_ALG_IS_HASH_AND_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</p>
-<p>This value must not be used to build an algorithm specification to perform an operation. It is only valid to build policies.</p>
+<p>This value must not be used to build an algorithm specification to perform an operation. It is only valid for setting the permitted algorithm in a key policy.</p>
<p class="rubric">Usage</p>
<p>For example, suppose that <code class="docutils literal"><span class="pre">PSA_xxx_SIGNATURE</span></code> is one of the following macros:</p>
<ul class="simple">
@@ -558,11 +585,11 @@
<li><a class="reference internal" href="#c.PSA_ALG_DETERMINISTIC_ECDSA" title="PSA_ALG_DETERMINISTIC_ECDSA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code></a></li>
</ul>
<p>The following sequence of operations shows how <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a> can be used in a key policy:</p>
-<ul>
-<li><p class="first">Set the key usage field using <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a>, for example:</p>
+<ol class="arabic">
+<li><p class="first">Set the key usage flags using <a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code></a>, for example:</p>
<pre class="literal-block">
-<a class="reference internal" href="../keys/usage.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(&attributes, <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a>); // or VERIFY_MESSAGE
-<a class="reference internal" href="../keys/algorithms.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(&attributes, PSA_xxx_SIGNATURE(<a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a>));
+<a class="reference internal" href="../keys/policy.html#c.psa_set_key_usage_flags" title="psa_set_key_usage_flags">psa_set_key_usage_flags</a>(&attributes, <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE">PSA_KEY_USAGE_SIGN_MESSAGE</a>); // or VERIFY_MESSAGE
+<a class="reference internal" href="../keys/policy.html#c.psa_set_key_algorithm" title="psa_set_key_algorithm">psa_set_key_algorithm</a>(&attributes, PSA_xxx_SIGNATURE(<a class="reference internal" href="#c.PSA_ALG_ANY_HASH" title="PSA_ALG_ANY_HASH">PSA_ALG_ANY_HASH</a>));
</pre>
</li>
<li><p class="first">Import or generate key material.</p>
@@ -574,7 +601,7 @@
<a class="reference internal" href="#c.psa_sign_message" title="psa_sign_message">psa_sign_message</a>(key, PSA_xxx_SIGNATURE(<a class="reference internal" href="hashes.html#c.PSA_ALG_SHA3_256" title="PSA_ALG_SHA3_256">PSA_ALG_SHA3_256</a>), ...);
</pre>
</li>
-</ul>
+</ol>
</div>
<div class="section" id="PSA_SIGN_OUTPUT_SIZE">
<span id="c.PSA_SIGN_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code> (macro)</h3>
@@ -620,61 +647,51 @@
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
- <div class="sphinxsidebarwrapper">
- <h3><a href="../../index.html">Table Of Contents</a></h3>
- <ul>
-<li><a class="reference internal" href="#">Asymmetric signature</a><ul>
-<li><a class="reference internal" href="#asymmetric-signature-algorithms">Asymmetric signature algorithms</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_RSA_PKCS1V15_SIGN_RAW"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PKCS1V15_SIGN_RAW</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_RSA_PSS"><code class="docutils literal"><span class="pre">PSA_ALG_RSA_PSS</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_ECDSA_ANY"><code class="docutils literal"><span class="pre">PSA_ALG_ECDSA_ANY</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_DETERMINISTIC_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_DETERMINISTIC_ECDSA</span></code> (macro)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#asymmetric-signature-functions">Asymmetric signature functions</a><ul>
-<li><a class="reference internal" href="#psa_sign_message"><code class="docutils literal"><span class="pre">psa_sign_message</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_verify_message"><code class="docutils literal"><span class="pre">psa_verify_message</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_sign_hash"><code class="docutils literal"><span class="pre">psa_sign_hash</span></code> (function)</a></li>
-<li><a class="reference internal" href="#psa_verify_hash"><code class="docutils literal"><span class="pre">psa_verify_hash</span></code> (function)</a></li>
-</ul>
-</li>
-<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
-<li><a class="reference internal" href="#PSA_ALG_IS_SIGN_MESSAGE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_MESSAGE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_SIGN_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_SIGN_HASH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_RSA_PKCS1V15_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PKCS1V15_SIGN</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_RSA_PSS"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RSA_PSS</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDSA</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_DETERMINISTIC_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_IS_DETERMINISTIC_ECDSA</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_RANDOMIZED_ECDSA"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RANDOMIZED_ECDSA</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_IS_HASH_AND_SIGN"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH_AND_SIGN</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_ALG_ANY_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_ANY_HASH</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_SIGN_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGN_OUTPUT_SIZE</span></code> (macro)</a></li>
-<li><a class="reference internal" href="#PSA_SIGNATURE_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_SIGNATURE_MAX_SIZE</span></code> (macro)</a></li>
-</ul>
-</li>
-</ul>
-</li>
-</ul>
-<div class="relations">
-<h3>Related Topics</h3>
+ <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
+IHI 0086<br/>
+Non-confidential<br/>
+Version 1.0.1
+<span style="color: red; font-weight: bold;"></span>
<ul>
- <li><a href="../../index.html">Documentation overview</a><ul>
- <li><a href="index.html">Cryptographic operation reference</a><ul>
- <li>Previous: <a href="kdf.html" title="previous chapter">Key derivation</a></li>
- <li>Next: <a href="pke.html" title="next chapter">Asymmetric encryption</a></li>
- </ul></li>
- </ul></li>
+<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
-</div>
- <div role="note" aria-label="source link">
- <h3>This Page</h3>
- <ul class="this-page-menu">
- <li><a href="../../_sources/api/ops/sign.rst.txt"
- rel="nofollow">Show Source</a></li>
- </ul>
- </div>
+<ul class="current">
+<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
+<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
+<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
+<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
+<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
+<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
+<li class="toctree-l2 current"><a class="current reference internal" href="#">10.7. Asymmetric signature</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-algorithms">10.7.1. Asymmetric signature algorithms</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#asymmetric-signature-functions">10.7.2. Asymmetric signature functions</a></li>
+<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.7.3. Support macros</a></li>
+</ul>
+</li>
+<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
+<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
+<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
+</ul>
+</li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
+<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
+</ul>
+<ul>
+<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
+</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
@@ -690,15 +707,12 @@
<div class="clearer"></div>
</div>
<div class="footer">
- © 2019-2020, Arm Limited or its affiliates. All rights reserved.
+ © 2018-2020, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
- |
- <a href="../../_sources/api/ops/sign.rst.txt"
- rel="nofollow">Page source</a>
</div>