TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c2db5f0e443752021c73fb4440a339e2cbc10fb7 / . / docs / html / api / ops / ka.html
blob: afdf394b5bddb037ef656fa60fd53e3a335ec273 [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
4
5<html xmlns="http://www.w3.org/1999/xhtml">
6 <head>
7 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]8 <title>10.9. Key agreement &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]9 <link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
10 <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
11 <script type="text/javascript">
12 var DOCUMENTATION_OPTIONS = {
13 URL_ROOT: '../../',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]14 VERSION: '1.0.1',
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]17 HAS_SOURCE: false,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]18 SOURCELINK_SUFFIX: '.txt'
19 };
20 </script>
21 <script type="text/javascript" src="../../_static/jquery.js"></script>
22 <script type="text/javascript" src="../../_static/underscore.js"></script>
23 <script type="text/javascript" src="../../_static/doctools.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]24 <link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]25 <link rel="index" title="Index" href="../../genindex.html" />
26 <link rel="search" title="Search" href="../../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]27 <link rel="next" title="10.10. Other cryptographic services" href="rng.html" />
28 <link rel="prev" title="10.8. Asymmetric encryption" href="pke.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]29
30 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
31
32 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
33
34 </head>
35 <body>
36
37
38 <div class="document">
39 <div class="documentwrapper">
40 <div class="bodywrapper">
41 <div class="body" role="main">
42
43 <div class="section" id="key-agreement">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]44<span id="id1"></span><h1>10.9. Key agreement</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="key-agreement-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]46<span id="id2"></span><h2>10.9.1. Key agreement algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="PSA_ALG_KEY_AGREEMENT">
48<span id="c.PSA_ALG_KEY_AGREEMENT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</h3>
49<p>Macro to build a combined algorithm that chains a key agreement with a key derivation.</p>
50<pre class="literal-block">
51#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) \
52 <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
53</pre>
54<p class="rubric">Parameters</p>
55<dl class="docutils">
56<dt> <code class="docutils literal"><span class="pre">ka_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]57<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]58<dt> <code class="docutils literal"><span class="pre">kdf_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]59<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]60</dl>
61<p class="rubric">Returns</p>
62<p>The corresponding key agreement and derivation algorithm.</p>
63<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>
64<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]65<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]66<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>
67</div>
68<div class="section" id="PSA_ALG_FFDH">
69<span id="c.PSA_ALG_FFDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</h3>
70<p>The finite-field Diffie-Hellman (DH) key agreement algorithm.</p>
71<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]72#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)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]73</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]74<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>
75<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>
76<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>
77<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]78</div>
79<div class="section" id="PSA_ALG_ECDH">
80<span id="c.PSA_ALG_ECDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</h3>
81<p>The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.</p>
82<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]83#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)
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]84</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]85<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>
86<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]87<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]88<ul>
89<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]90<ul class="simple">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]91<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>
92<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>
93</ul>
94</li>
95<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>
96<ul class="simple">
97<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>
98<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>
99</ul>
100<div class="admonition note">
101<p class="first admonition-title">Note</p>
102<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>
103</div>
104</li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]105</ul>
106</div>
107</div>
108<div class="section" id="standalone-key-agreement">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]109<h2>10.9.2. Standalone key agreement</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]110<div class="section" id="psa_raw_key_agreement">
111<span id="c.psa_raw_key_agreement"></span><h3><code class="docutils literal"><span class="pre">psa_raw_key_agreement</span></code> (function)</h3>
112<p>Perform a key agreement and return the raw shared secret.</p>
113<pre class="literal-block">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]114<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,
115 <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]116 const uint8_t * peer_key,
117 size_t peer_key_length,
118 uint8_t * output,
119 size_t output_size,
120 size_t * output_length);
121</pre>
122<p class="rubric">Parameters</p>
123<dl class="docutils">
124<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
125<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>
126<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
127<dd>Identifier of the private key to use.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]128It 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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]129<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
130<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>
131<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
132<dd>Size of <code class="docutils literal"><span class="pre">peer_key</span></code> in bytes.</dd>
133<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]134<dd>Buffer where the raw shared secret is to be written.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]135<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
136<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes.
137This must be appropriate for the keys:</p>
138<ul class="last simple">
139<li>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"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">type</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">bits</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">type</span></code> is the type of <code class="docutils literal"><span class="pre">private_key</span></code> and <code class="docutils literal"><span class="pre">bits</span></code> is the bit-size of either <code class="docutils literal"><span class="pre">private_key</span></code> or the <code class="docutils literal"><span class="pre">peer_key</span></code>.</li>
140<li><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"><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.</li>
141</ul>
142</dd>
143<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
144<dd>On success, the number of bytes that make up the returned output.</dd>
145</dl>
146<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>
147<dl class="docutils">
148<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>
149<dd>Success.</dd>
150<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>
151<dd></dd>
152<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]153<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]154<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>
155<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a key agreement algorithm</dd>
156<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>
157<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>
158<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>
159<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small.
160<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"><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"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</dd>
161<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>
162<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a supported key agreement algorithm.</dd>
163<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>
164<dd></dd>
165<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>
166<dd></dd>
167<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>
168<dd></dd>
169<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>
170<dd></dd>
171<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
172<dd></dd>
173<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
174<dd></dd>
175<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>
176<dd></dd>
177<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>
178<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>
179</dl>
180<p class="rubric">Description</p>
181<div class="admonition warning">
182<p class="first admonition-title">Warning</p>
183<p class="last">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"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> and other functions from the key derivation interface.</p>
184</div>
185</div>
186</div>
187<div class="section" id="combining-key-agreement-and-key-derivation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]188<h2>10.9.3. Combining key agreement and key derivation</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]189<div class="section" id="psa_key_derivation_key_agreement">
190<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>
191<p>Perform a key agreement and use the shared secret as input to a key derivation.</p>
192<pre class="literal-block">
193<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,
194 <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^]195 <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]196 const uint8_t * peer_key,
197 size_t peer_key_length);
198</pre>
199<p class="rubric">Parameters</p>
200<dl class="docutils">
201<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]202<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]203<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
204<dd>Which step the input data is for.</dd>
205<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
206<dd>Identifier of the private key to use.
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]207It 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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]208<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
209<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>
210<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
211<dd>Size of <code class="docutils literal"><span class="pre">peer_key</span></code> in bytes.</dd>
212</dl>
213<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>
214<dl class="docutils">
215<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>
216<dd>Success.</dd>
217<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>
218<dd>The operation state is not valid for this key agreement <code class="docutils literal"><span class="pre">step</span></code>.</dd>
219<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>
220<dd></dd>
221<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]222<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]223<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>
224<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>
225<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>
226<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a key derivation algorithm.</dd>
227<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>
228<dd><code class="docutils literal"><span class="pre">step</span></code> does not allow an input resulting from a key agreement.</dd>
229<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>
230<dd></dd>
231<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>
232<dd></dd>
233<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>
234<dd></dd>
235<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>
236<dd></dd>
237<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
238<dd></dd>
239<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt>
240<dd></dd>
241<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>
242<dd></dd>
243<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>
244<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>
245</dl>
246<p class="rubric">Description</p>
247<p>A key agreement algorithm takes two inputs: a private key <code class="docutils literal"><span class="pre">private_key</span></code> a public key <code class="docutils literal"><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>
248<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"><span class="pre">psa_key_derivation_abort()</span></code></a>.</p>
249</div>
250</div>
251<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]252<h2>10.9.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]253<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_BASE">
254<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>
255<p>Get the raw key agreement algorithm from a full key agreement algorithm.</p>
256<pre class="literal-block">
257#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>
258</pre>
259<p class="rubric">Parameters</p>
260<dl class="docutils">
261<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]262<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]263</dl>
264<p class="rubric">Returns</p>
265<p>The underlying raw key agreement algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
266<p>Unspecified if <code class="docutils literal"><span class="pre">alg</span></code> is not a key agreement algorithm or if it is not supported by the implementation.</p>
267<p class="rubric">Description</p>
268<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"><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"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF()</span></code></a>.</p>
269</div>
270<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_KDF">
271<span id="c.PSA_ALG_KEY_AGREEMENT_GET_KDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF</span></code> (macro)</h3>
272<p>Get the key derivation algorithm used in a full key agreement algorithm.</p>
273<pre class="literal-block">
274#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>
275</pre>
276<p class="rubric">Parameters</p>
277<dl class="docutils">
278<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]279<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]280</dl>
281<p class="rubric">Returns</p>
282<p>The underlying key derivation algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
283<p>Unspecified if <code class="docutils literal"><span class="pre">alg</span></code> is not a key agreement algorithm or if it is not supported by the implementation.</p>
284<p class="rubric">Description</p>
285<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"><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"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a>.</p>
286</div>
287<div class="section" id="PSA_ALG_IS_RAW_KEY_AGREEMENT">
288<span id="c.PSA_ALG_IS_RAW_KEY_AGREEMENT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code> (macro)</h3>
289<p>Whether the specified algorithm is a raw key agreement algorithm.</p>
290<pre class="literal-block">
291#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>
292</pre>
293<p class="rubric">Parameters</p>
294<dl class="docutils">
295<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]296<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]297</dl>
298<p class="rubric">Returns</p>
299<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>
300<p class="rubric">Description</p>
301<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"><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"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a>.</p>
302<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"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a>.</p>
303</div>
304<div class="section" id="PSA_ALG_IS_FFDH">
305<span id="c.PSA_ALG_IS_FFDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_FFDH</span></code> (macro)</h3>
306<p>Whether the specified algorithm is a finite field Diffie-Hellman algorithm.</p>
307<pre class="literal-block">
308#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>
309</pre>
310<p class="rubric">Parameters</p>
311<dl class="docutils">
312<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]313<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]314</dl>
315<p class="rubric">Returns</p>
316<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>
317<p class="rubric">Description</p>
318<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>
319</div>
320<div class="section" id="PSA_ALG_IS_ECDH">
321<span id="c.PSA_ALG_IS_ECDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDH</span></code> (macro)</h3>
322<p>Whether the specified algorithm is an elliptic curve Diffie-Hellman algorithm.</p>
323<pre class="literal-block">
324#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>
325</pre>
326<p class="rubric">Parameters</p>
327<dl class="docutils">
328<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]329<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]330</dl>
331<p class="rubric">Returns</p>
332<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>
333<p class="rubric">Description</p>
334<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>
335</div>
336<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE">
337<span id="c.PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE</span></code> (macro)</h3>
338<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"><span class="pre">psa_raw_key_agreement()</span></code></a>.</p>
339<pre class="literal-block">
340#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) \
341 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
342</pre>
343<p class="rubric">Parameters</p>
344<dl class="docutils">
345<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
346<dd>A supported key type.</dd>
347<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
348<dd>The size of the key in bits.</dd>
349</dl>
350<p class="rubric">Returns</p>
351<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"><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"><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>
352<p class="rubric">Description</p>
353<p>This macro returns a compile-time constant if its arguments are compile-time constants.</p>
354<div class="admonition warning">
355<p class="first admonition-title">Warning</p>
356<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>
357</div>
358<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"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code></a>.</p>
359</div>
360<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE">
361<span id="c.PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
362<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"><span class="pre">psa_raw_key_agreement()</span></code></a>.</p>
363<pre class="literal-block">
364#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> \
365 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
366</pre>
367<p>This macro must expand to a compile-time constant integer.
368It 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>
369<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"><span class="pre">PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE()</span></code></a>.</p>
370</div>
371</div>
372</div>
373
374
375 </div>
376 </div>
377 </div>
378 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]379 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
380IHI 0086<br/>
381Non-confidential<br/>
382Version 1.0.1
383<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]384<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]385<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]386</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]387<ul class="current">
388<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
389<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
390<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
391<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
392<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
393<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
394<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
395<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
396<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
397<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
398<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
399<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
400<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
401<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
402<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
403<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
404<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
405<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
406<li class="toctree-l2 current"><a class="current reference internal" href="#">10.9. Key agreement</a><ul>
407<li class="toctree-l3"><a class="reference internal" href="#key-agreement-algorithms">10.9.1. Key agreement algorithms</a></li>
408<li class="toctree-l3"><a class="reference internal" href="#standalone-key-agreement">10.9.2. Standalone key agreement</a></li>
409<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>
410<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.9.4. Support macros</a></li>
411</ul>
412</li>
413<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
414</ul>
415</li>
416</ul>
417<ul>
418<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
419<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
420<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
421</ul>
422<ul>
423<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
424</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]425<div id="searchbox" style="display: none" role="search">
426 <h3>Quick search</h3>
427 <form class="search" action="../../search.html" method="get">
428 <div><input type="text" name="q" /></div>
429 <div><input type="submit" value="Go" /></div>
430 <input type="hidden" name="check_keywords" value="yes" />
431 <input type="hidden" name="area" value="default" />
432 </form>
433</div>
434<script type="text/javascript">$('#searchbox').show(0);</script>
435 </div>
436 </div>
437 <div class="clearer"></div>
438 </div>
439 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]440 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]441
442 |
443 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
444 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
445
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]446 </div>
447
448
449
450
451 </body>
452</html>