TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / b0dbbb12c1b13fc6b262fa0ad65089a997bcd0d1 / . / docs / 1.0.1 / html / api / ops / ka.html
blob: f3b2783d353daa248478d2f8b1e05b1cf5658bc0 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>10.9. Key agreement &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]10 <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../../_static/jquery.js"></script>
12 <script type="text/javascript" src="../../_static/underscore.js"></script>
13 <script type="text/javascript" src="../../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]14 <script type="text/javascript" src="../../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../../genindex.html" />
17 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="10.10. Other cryptographic services" href="rng.html" />
19 <link rel="prev" title="10.8. Asymmetric encryption" href="pke.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="key-agreement">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="id1"></span><h1>10.9. Key agreement</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="section" id="key-agreement-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39<span id="id2"></span><h2>10.9.1. Key agreement algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<div class="section" id="PSA_ALG_KEY_AGREEMENT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]41<span id="c.PSA_ALG_KEY_AGREEMENT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]42<p>Macro to build a combined algorithm that chains a key agreement with a key derivation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]43<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT">PSA_ALG_KEY_AGREEMENT</a>(ka_alg, kdf_alg) \
44 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]46<dl class="simple">
47<dt> <code class="docutils literal notranslate"><span class="pre">ka_alg</span></code></dt><dd><p>A key agreement algorithm (<code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">ka_alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
48</dd>
49<dt> <code class="docutils literal notranslate"><span class="pre">kdf_alg</span></code></dt><dd><p>A key derivation algorithm (<code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">kdf_alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
50</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]51</dl>
52<p class="rubric">Returns</p>
53<p>The corresponding key agreement and derivation algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]54<p>Unspecified if <code class="docutils literal notranslate"><span class="pre">ka_alg</span></code> is not a supported key agreement algorithm or <code class="docutils literal notranslate"><span class="pre">kdf_alg</span></code> is not a supported key derivation algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]55<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]56<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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
57<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 notranslate"><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 notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]58</div>
59<div class="section" id="PSA_ALG_FFDH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]60<span id="c.PSA_ALG_FFDH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]61<p>The finite-field Diffie-Hellman (DH) key agreement algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]62<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="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09010000)</pre>
63<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
64<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is used when providing the secret and peer keys to the operation.</p>
65<p>The shared secret produced by this key agreement algorithm is <code class="docutils literal notranslate"><span class="pre">g^{ab}</span></code> in big-endian format. It is <code class="docutils literal notranslate"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal notranslate"><span class="pre">m</span></code> is the size of the prime <code class="docutils literal notranslate"><span class="pre">p</span></code> in bits.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]66<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]67</div>
68<div class="section" id="PSA_ALG_ECDH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]69<span id="c.PSA_ALG_ECDH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]70<p>The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]71<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="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09020000)</pre>
72<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 notranslate"><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 notranslate"><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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
73<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is used when providing the secret and peer keys to the operation.</p>
74<p>The shared secret produced by key agreement is the x-coordinate of the shared secret point. It is always <code class="docutils literal notranslate"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal notranslate"><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 notranslate"><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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]75<ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]76<li><p>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 notranslate"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>), the shared secret is the x-coordinate of <code class="docutils literal notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]77<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]78<li><p>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 notranslate"><span class="pre">m</span></code> is 255.</p></li>
79<li><p>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 notranslate"><span class="pre">m</span></code> is 448.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]80</ul>
81</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]82<li><p>For Weierstrass curves (curve families <code class="docutils literal notranslate"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>) the shared secret is the x-coordinate of <code class="docutils literal notranslate"><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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]83<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]84<li><p>Over prime fields (curve families <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>), the bit size is <code class="docutils literal notranslate"><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 notranslate"><span class="pre">F_p</span></code>.</p></li>
85<li><p>Over binary fields (curve families <code class="docutils literal notranslate"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>), the bit size is <code class="docutils literal notranslate"><span class="pre">m</span></code> for the field <code class="docutils literal notranslate"><span class="pre">F_{2^m}</span></code>.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]86</ul>
87<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]88<p class="admonition-title">Note</p>
89<p>The cofactor Diffie-Hellman primitive is equivalent to the standard elliptic curve Diffie-Hellman calculation <code class="docutils literal notranslate"><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 notranslate"><span class="pre">h</span></code> is <code class="docutils literal notranslate"><span class="pre">1</span></code>. This is true for all curves in the <code class="docutils literal notranslate"><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 notranslate"><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 notranslate"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a> families.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]90</div>
91</li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]92</ul>
93</div>
94</div>
95<div class="section" id="standalone-key-agreement">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]96<h2>10.9.2. Standalone key agreement</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]97<div class="section" id="psa_raw_key_agreement">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]98<span id="c.psa_raw_key_agreement"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_raw_key_agreement</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]99<p>Perform a key agreement and return the raw shared secret.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]100<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="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]101 <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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]102 const uint8_t * peer_key,
103 size_t peer_key_length,
104 uint8_t * output,
105 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]106 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]107<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]108<dl class="simple">
109<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The key agreement algorithm to compute (<code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
110</dd>
111<dt> <code class="docutils literal notranslate"><span class="pre">private_key</span></code></dt><dd><p>Identifier of the private key to use.
112It 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 notranslate"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</p>
113</dd>
114<dt> <code class="docutils literal notranslate"><span class="pre">peer_key</span></code></dt><dd><p>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 notranslate"><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 notranslate"><span class="pre">psa_export_public_key()</span></code></a>.</p>
115</dd>
116<dt> <code class="docutils literal notranslate"><span class="pre">peer_key_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">peer_key</span></code> in bytes.</p>
117</dd>
118<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the raw shared secret is to be written.</p>
119</dd>
120<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]121This must be appropriate for the keys:</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]122<ul class="simple">
123<li><p>The required output size is <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">bits</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">private_key</span></code> and <code class="docutils literal notranslate"><span class="pre">bits</span></code> is the bit-size of either <code class="docutils literal notranslate"><span class="pre">private_key</span></code> or the <code class="docutils literal notranslate"><span class="pre">peer_key</span></code>.</p></li>
124<li><p><a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported raw key agreement algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]125</ul>
126</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]127<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the returned output.</p>
128</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]129</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]130<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
131<dl class="simple">
132<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
133</dd>
134<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
135<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</p>
136</dd>
137<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a key agreement algorithm</p>
138</dd>
139<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">private_key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>, or <code class="docutils literal notranslate"><span class="pre">peer_key</span></code> is not valid for <code class="docutils literal notranslate"><span class="pre">alg</span></code> or not compatible with <code class="docutils literal notranslate"><span class="pre">private_key</span></code>.</p>
140</dd>
141<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 notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer is too small.
142<a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
143</dd>
144<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported key agreement algorithm.</p>
145</dd>
146<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
147<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
148<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
149<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
150<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
151<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
152<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
153<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
154</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]155</dl>
156<p class="rubric">Description</p>
157<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]158<p class="admonition-title">Warning</p>
159<p>The raw result of a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases, and is not suitable for use as key material. Instead it is recommended that the result is used as input to a key derivation algorithm. To chain a key agreement with a key derivation, use <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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> and other functions from the key derivation interface.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]160</div>
161</div>
162</div>
163<div class="section" id="combining-key-agreement-and-key-derivation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]164<h2>10.9.3. Combining key agreement and key derivation</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]165<div class="section" id="psa_key_derivation_key_agreement">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]166<span id="c.psa_key_derivation_key_agreement"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_key_derivation_key_agreement</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]167<p>Perform a key agreement and use the shared secret as input to a key derivation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]168<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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]169 <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,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]170 <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,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]171 const uint8_t * peer_key,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]172 size_t peer_key_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]173<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]174<dl class="simple">
175<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_key_derivation_setup()</span></code></a> with a key agreement and derivation algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code> (<code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is false). The operation must be ready for an input of the type given by <code class="docutils literal notranslate"><span class="pre">step</span></code>.</p>
176</dd>
177<dt> <code class="docutils literal notranslate"><span class="pre">step</span></code></dt><dd><p>Which step the input data is for.</p>
178</dd>
179<dt> <code class="docutils literal notranslate"><span class="pre">private_key</span></code></dt><dd><p>Identifier of the private key to use.
180It 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 notranslate"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</p>
181</dd>
182<dt> <code class="docutils literal notranslate"><span class="pre">peer_key</span></code></dt><dd><p>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 notranslate"><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 notranslate"><span class="pre">psa_import_key</span></code></a><code class="docutils literal notranslate"><span class="pre">(...,</span> </code><code class="docutils literal notranslate"><span class="pre">peer_key</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">peer_key_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where with key attributes indicating the public key type corresponding to the type of <code class="docutils literal notranslate"><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 notranslate"><span class="pre">psa_export_public_key()</span></code></a>.</p>
183</dd>
184<dt> <code class="docutils literal notranslate"><span class="pre">peer_key_length</span></code></dt><dd><p>Size of <code class="docutils literal notranslate"><span class="pre">peer_key</span></code> in bytes.</p>
185</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]186</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]187<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
188<dl class="simple">
189<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
190</dd>
191<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid for this key agreement <code class="docutils literal notranslate"><span class="pre">step</span></code>.</p>
192</dd>
193<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
194<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>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 notranslate"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</p>
195</dd>
196<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">private_key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>, or <code class="docutils literal notranslate"><span class="pre">peer_key</span></code> is not valid for <code class="docutils literal notranslate"><span class="pre">alg</span></code> or not compatible with <code class="docutils literal notranslate"><span class="pre">private_key</span></code>.</p>
197</dd>
198<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a key derivation algorithm.</p>
199</dd>
200<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">step</span></code> does not allow an input resulting from a key agreement.</p>
201</dd>
202<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
203<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
204<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
205<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
206<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
207<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
208<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
209<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
210</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]211</dl>
212<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]213<p>A key agreement algorithm takes two inputs: a private key <code class="docutils literal notranslate"><span class="pre">private_key</span></code> a public key <code class="docutils literal notranslate"><span class="pre">peer_key</span></code>. The result of this function is passed as input to a key derivation. The output of this key derivation can be extracted by reading from the resulting operation to produce keys and other cryptographic material.</p>
214<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="kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]215</div>
216</div>
217<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]218<h2>10.9.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]219<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_BASE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]220<span id="c.PSA_ALG_KEY_AGREEMENT_GET_BASE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]221<p>Get the raw key agreement algorithm from a full key agreement algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]222<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_BASE" title="PSA_ALG_KEY_AGREEMENT_GET_BASE">PSA_ALG_KEY_AGREEMENT_GET_BASE</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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]223<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]224<dl class="simple">
225<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>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 notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
226</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]227</dl>
228<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]229<p>The underlying raw key agreement algorithm if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
230<p>Unspecified if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a key agreement algorithm or if it is not supported by the implementation.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]231<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]232<p>See also <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT()</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 notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]233</div>
234<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_KDF">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]235<span id="c.PSA_ALG_KEY_AGREEMENT_GET_KDF"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]236<p>Get the key derivation algorithm used in a full key agreement algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]237<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_KDF" title="PSA_ALG_KEY_AGREEMENT_GET_KDF">PSA_ALG_KEY_AGREEMENT_GET_KDF</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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]238<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]239<dl class="simple">
240<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>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 notranslate"><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 notranslate"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
241</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]242</dl>
243<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]244<p>The underlying key derivation algorithm if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
245<p>Unspecified if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a key agreement algorithm or if it is not supported by the implementation.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]246<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]247<p>See also <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a> and <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 notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]248</div>
249<div class="section" id="PSA_ALG_IS_RAW_KEY_AGREEMENT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]250<span id="c.PSA_ALG_IS_RAW_KEY_AGREEMENT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]251<p>Whether the specified algorithm is a raw key agreement algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]252<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_IS_RAW_KEY_AGREEMENT" title="PSA_ALG_IS_RAW_KEY_AGREEMENT">PSA_ALG_IS_RAW_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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]253<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]254<dl class="simple">
255<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_algorithm_t</span></code></a>).</p>
256</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]257</dl>
258<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]259<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a raw key agreement algorithm, <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]260<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]261<p>A raw key agreement algorithm is one that does not specify a key derivation function. Usually, raw key agreement algorithms are constructed directly with a <code class="docutils literal notranslate"><span class="pre">PSA_ALG_xxx</span></code> macro while non-raw key agreement algorithms are constructed with <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a>.</p>
262<p>The raw key agreement algorithm can be extracted from a full key agreement algorithm identifier 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 notranslate"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]263</div>
264<div class="section" id="PSA_ALG_IS_FFDH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]265<span id="c.PSA_ALG_IS_FFDH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_FFDH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]266<p>Whether the specified algorithm is a finite field Diffie-Hellman algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]267<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_IS_FFDH" title="PSA_ALG_IS_FFDH">PSA_ALG_IS_FFDH</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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]268<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]269<dl class="simple">
270<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_algorithm_t</span></code></a>).</p>
271</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]272</dl>
273<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]274<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a finite field Diffie-Hellman algorithm, <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]275<p class="rubric">Description</p>
276<p>This includes the raw finite field Diffie-Hellman algorithm as well as finite-field Diffie-Hellman followed by any supporter key derivation algorithm.</p>
277</div>
278<div class="section" id="PSA_ALG_IS_ECDH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]279<span id="c.PSA_ALG_IS_ECDH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_ECDH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]280<p>Whether the specified algorithm is an elliptic curve Diffie-Hellman algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]281<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_IS_ECDH" title="PSA_ALG_IS_ECDH">PSA_ALG_IS_ECDH</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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]282<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]283<dl class="simple">
284<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>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 notranslate"><span class="pre">psa_algorithm_t</span></code></a>).</p>
285</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]286</dl>
287<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]288<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is an elliptic curve Diffie-Hellman algorithm, <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]289<p class="rubric">Description</p>
290<p>This includes the raw elliptic curve Diffie-Hellman algorithm as well as elliptic curve Diffie-Hellman followed by any supporter key derivation algorithm.</p>
291</div>
292<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]293<span id="c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</span></code> (macro)</h3>
294<p>Sufficient output buffer size for <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_raw_key_agreement()</span></code></a>.</p>
295<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</a>(key_type, key_bits) \
296 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]297<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]298<dl class="simple">
299<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A supported key type.</p>
300</dd>
301<dt> <code class="docutils literal notranslate"><span class="pre">key_bits</span></code></dt><dd><p>The size of the key in bits.</p>
302</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]303</dl>
304<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]305<p>If the parameters are valid and supported, return a buffer size in bytes that guarantees that <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_raw_key_agreement()</span></code></a> 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 notranslate"><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 notranslate"><span class="pre">0</span></code>. If the parameters are not valid, the return value is unspecified.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]306<p class="rubric">Description</p>
307<p>This macro returns a compile-time constant if its arguments are compile-time constants.</p>
308<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]309<p class="admonition-title">Warning</p>
310<p>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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]311</div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]312<p>See also <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]313</div>
314<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]315<span id="c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
316<p>Maximum size of the output from <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_raw_key_agreement()</span></code></a>.</p>
317<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</a> \
318 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]319<p>This macro must expand to a compile-time constant integer.
320It is recommended that this value is the maximum size of the output any raw key agreement algorithm supported by the implementation, in bytes. The value must not be smaller than this maximum.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]321<p>See also <a class="reference internal" href="#c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE" title="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]322</div>
323</div>
324</div>
325
326
327 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]328
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]329 </div>
330 </div>
331 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]332 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
333IHI 0086<br/>
334Non-confidential<br/>
335Version 1.0.1
336<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]337<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]338<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]339</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]340<ul class="current">
341<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
342<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
343<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
344<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
345<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
346<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
347<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
348<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
349<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
350<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
351<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
352<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
353<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
354<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
355<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
356<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
357<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
358<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
359<li class="toctree-l2 current"><a class="current reference internal" href="#">10.9. Key agreement</a><ul>
360<li class="toctree-l3"><a class="reference internal" href="#key-agreement-algorithms">10.9.1. Key agreement algorithms</a></li>
361<li class="toctree-l3"><a class="reference internal" href="#standalone-key-agreement">10.9.2. Standalone key agreement</a></li>
362<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>
363<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.9.4. Support macros</a></li>
364</ul>
365</li>
366<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
367</ul>
368</li>
369</ul>
370<ul>
371<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
372<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
373<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
374</ul>
375<ul>
376<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
377</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]378<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]379 <h3 id="searchlabel">Quick search</h3>
380 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]381 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]382 <input type="text" name="q" aria-labelledby="searchlabel" />
383 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]384 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]385 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]386</div>
387<script type="text/javascript">$('#searchbox').show(0);</script>
388 </div>
389 </div>
390 <div class="clearer"></div>
391 </div>
392 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]393 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]394
395 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]396 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
397 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]398
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]399 </div>
400
401
402
403
404 </body>
405</html>