TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 882f7c72267ee598fd4f7c0d34b2c70760c76d8c / . / docs / 1.1.0 / html / api / ops / ka.html
blob: a7edfe61823b8135a42a54a85891ca158255b6c1 [file] [log] [blame]
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>10.9. Key agreement &#8212; PSA Crypto API 1.1.0 documentation</title>
<link rel="stylesheet" href="../../_static/alabaster.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.1.0',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: false,
SOURCELINK_SUFFIX: '.txt'
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="author" title="About these documents" href="../../about.html" />
<link rel="index" title="Index" href="../../genindex.html" />
<link rel="search" title="Search" href="../../search.html" />
<link rel="next" title="10.10. Other cryptographic services" href="rng.html" />
<link rel="prev" title="10.8. Asymmetric encryption" href="pke.html" />
<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
<meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
</head>
<body>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="key-agreement">
<span id="id1"></span><h1>10.9. Key agreement</h1>
<p>Two functions are provided for a Diffie-Hellman-style key agreement where each party combines its own private key with the peer’s public key.</p>
<ul class="simple">
<li>The recommended approach is to use a <a class="reference internal" href="kdf.html#kdf"><span class="std std-ref">key derivation operation</span></a> with the <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> input function, which calculates a shared secret for the key derivation function.</li>
<li>Where an application needs direct access to the shared secret, it can call <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> instead. Note that in general the shared secret is not directly suitable for use as a key because it is biased.</li>
</ul>
<div class="section" id="key-agreement-algorithms">
<span id="id2"></span><h2>10.9.1. Key agreement algorithms</h2>
<div class="section" id="PSA_ALG_FFDH">
<span id="c.PSA_ALG_FFDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_FFDH</span></code> (macro)</h3>
<p>The finite-field Diffie-Hellman (DH) key agreement algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_FFDH" title="PSA_ALG_FFDH">PSA_ALG_FFDH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09010000)
</pre>
<p>This algorithm can be used directly in a call to <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a>, or combined with a key derivation operation using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a> for use with <a class="reference internal" href="#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
<p>When used as a key’s permitted algorithm policy, the following uses are permitted:</p>
<ul class="simple">
<li>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>, with algorithm <a class="reference internal" href="#c.PSA_ALG_FFDH" title="PSA_ALG_FFDH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_FFDH</span></code></a>.</li>
<li>In 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>, with any combined key agreement and key derivation algorithm constructed with <a class="reference internal" href="#c.PSA_ALG_FFDH" title="PSA_ALG_FFDH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_FFDH</span></code></a>.</li>
</ul>
<p>When used as part of a multi-part key derivation operation, this implements a Diffie-Hellman key agreement scheme using a single Diffie-Hellman key-pair for each participant. This includes the <em>dhEphem</em>, <em>dhOneFlow</em>, and <em>dhStatic</em> schemes. The input step <a class="reference internal" href="kdf.html#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is used when providing the secret and peer keys to the operation.</p>
<p>The shared secret produced by this key agreement algorithm is <code class="docutils literal"><span class="pre">g^{ab}</span></code> in big-endian format. It is <code class="docutils literal"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal"><span class="pre">m</span></code> is the size of the prime <code class="docutils literal"><span class="pre">p</span></code> in bits.</p>
<p>This key agreement scheme is defined by <span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.7.1.1 under the name FFC DH.</p>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DH_KEY_PAIR" title="PSA_KEY_TYPE_DH_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DH_KEY_PAIR()</span></code></a></div>
</div>
</div>
<div class="section" id="PSA_ALG_ECDH">
<span id="c.PSA_ALG_ECDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_ECDH</span></code> (macro)</h3>
<p>The elliptic curve Diffie-Hellman (ECDH) key agreement algorithm.</p>
<pre class="literal-block">
#define <a class="reference internal" href="#c.PSA_ALG_ECDH" title="PSA_ALG_ECDH">PSA_ALG_ECDH</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x09020000)
</pre>
<p>This algorithm can be used directly in a call to <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a>, or combined with a key derivation operation using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT" title="PSA_ALG_KEY_AGREEMENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT()</span></code></a> for use with <a class="reference internal" href="#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
<p>When used as a key’s permitted algorithm policy, the following uses are permitted:</p>
<ul class="simple">
<li>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>, with algorithm <a class="reference internal" href="#c.PSA_ALG_ECDH" title="PSA_ALG_ECDH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDH</span></code></a>.</li>
<li>In 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>, with any combined key agreement and key derivation algorithm constructed with <a class="reference internal" href="#c.PSA_ALG_ECDH" title="PSA_ALG_ECDH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_ECDH</span></code></a>.</li>
</ul>
<p>When used as part of a multi-part key derivation operation, this implements a Diffie-Hellman key agreement scheme using a single elliptic curve key-pair for each participant. This includes the <em>Ephemeral unified model</em>, the <em>Static unified model</em>, and the <em>One-pass Diffie-Hellman</em> schemes. The input step <a class="reference internal" href="kdf.html#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is used when providing the secret and peer keys to the operation.</p>
<p>The shared secret produced by key agreement is the x-coordinate of the shared secret point. It is always <code class="docutils literal"><span class="pre">ceiling(m</span> <span class="pre">/</span> <span class="pre">8)</span></code> bytes long where <code class="docutils literal"><span class="pre">m</span></code> is the bit size associated with the curve, i.e. the bit size of the order of the curve’s coordinate field. When <code class="docutils literal"><span class="pre">m</span></code> is not a multiple of 8, the byte containing the most significant bit of the shared secret is padded with zero bits. The byte order is either little-endian or big-endian depending on the curve type.</p>
<ul>
<li><p class="first">For Montgomery curves (curve family <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>), the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in little-endian byte order.</p>
<ul class="simple">
<li>For Curve25519, this is the X25519 function defined in <span><em>Curve25519: new Diffie-Hellman speed records</em> <a class="reference internal" href="../../about.html#citation-curve25519"><span class="cite">[Curve25519]</span></a></span>. The bit size <code class="docutils literal"><span class="pre">m</span></code> is 255.</li>
<li>For Curve448, this is the X448 function defined in <span><em>Ed448-Goldilocks, a new elliptic curve</em> <a class="reference internal" href="../../about.html#citation-curve448"><span class="cite">[Curve448]</span></a></span>. The bit size <code class="docutils literal"><span class="pre">m</span></code> is 448.</li>
</ul>
</li>
<li><p class="first">For Weierstrass curves (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a> and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>) the shared secret is the x-coordinate of <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">h</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">h</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> in big-endian byte order. This is the Elliptic Curve Cryptography Cofactor Diffie-Hellman primitive defined by <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="../../about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span> §3.3.2 as, and also as ECC CDH by <span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.7.1.2.</p>
<ul class="simple">
<li>Over prime fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a> and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a>), the bit size is <code class="docutils literal"><span class="pre">m</span> <span class="pre">=</span> <span class="pre">ceiling(log_2(p))</span></code> for the field <code class="docutils literal"><span class="pre">F_p</span></code>.</li>
<li>Over binary fields (curve families <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code>), the bit size is <code class="docutils literal"><span class="pre">m</span></code> for the field <code class="docutils literal"><span class="pre">F_{2^m}</span></code>.</li>
</ul>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">The cofactor Diffie-Hellman primitive is equivalent to the standard elliptic curve Diffie-Hellman calculation <code class="docutils literal"><span class="pre">Z</span> <span class="pre">=</span> <span class="pre">d_A</span> <span class="pre">Q_B</span> <span class="pre">=</span> <span class="pre">d_B</span> <span class="pre">Q_A</span></code> (<a class="reference internal" href="../../about.html#citation-sec1"><span class="cite psa_c psa_c-cite">[SEC1]</span></a> §3.3.1) for curves where the cofactor <code class="docutils literal"><span class="pre">h</span></code> is <code class="docutils literal"><span class="pre">1</span></code>. This is true for all curves in the <code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code>, <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_BRAINPOOL_P_R1" title="PSA_ECC_FAMILY_BRAINPOOL_P_R1"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_BRAINPOOL_P_R1</span></code></a>, and <a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_FRP" title="PSA_ECC_FAMILY_FRP"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_FRP</span></code></a> families.</p>
</div>
</li>
</ul>
<p class="rubric">Compatible key types</p>
<div class="line-block">
<div class="line"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">family</span></code><code class="docutils literal"><span class="pre">)</span></code></div>
</div>
<p>where <code class="docutils literal"><span class="pre">family</span></code> is a Weierstrass or Montgomery Elliptic curve family. That is, one of the following values:</p>
<ul class="simple">
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECT_XX</span></code></li>
<li><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_SECP_XX</span></code></li>
<li><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></li>
<li><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></li>
<li><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></li>
</ul>
</div>
<div class="section" id="PSA_ALG_KEY_AGREEMENT">
<span id="c.PSA_ALG_KEY_AGREEMENT"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT</span></code> (macro)</h3>
<p>Macro to build a combined algorithm that chains a key agreement with a key derivation.</p>
<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) \
<em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">ka_alg</span></code></dt>
<dd>A key agreement algorithm: a 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">ka_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">kdf_alg</span></code></dt>
<dd>A key derivation algorithm: a 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_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">kdf_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The corresponding key agreement and derivation algorithm.</p>
<p>Unspecified if <code class="docutils literal"><span class="pre">ka_alg</span></code> is not a supported key agreement algorithm or <code class="docutils literal"><span class="pre">kdf_alg</span></code> is not a supported key derivation algorithm.</p>
<p class="rubric">Description</p>
<p>A combined key agreement algorithm is used with a multi-part key derivation operation, using a call to <a class="reference internal" href="#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
<p>The component parts of a key agreement algorithm can be extracted using <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_BASE" title="PSA_ALG_KEY_AGREEMENT_GET_BASE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE()</span></code></a> and <a class="reference internal" href="#c.PSA_ALG_KEY_AGREEMENT_GET_KDF" title="PSA_ALG_KEY_AGREEMENT_GET_KDF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_KDF()</span></code></a>.</p>
<p class="rubric">Compatible key types</p>
<p>The resulting combined key agreement algorithm is compatible with the same key types as the raw key agreement algorithm used to construct it.</p>
</div>
</div>
<div class="section" id="standalone-key-agreement">
<h2>10.9.2. Standalone key agreement</h2>
<div class="section" id="psa_raw_key_agreement">
<span id="c.psa_raw_key_agreement"></span><h3><code class="docutils literal"><span class="pre">psa_raw_key_agreement</span></code> (function)</h3>
<p>Perform a key agreement and return the raw shared secret.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_raw_key_agreement" title="psa_raw_key_agreement">psa_raw_key_agreement</a>(<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
const uint8_t * peer_key,
size_t peer_key_length,
uint8_t * output,
size_t output_size,
size_t * output_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>The key agreement algorithm to compute: a 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="#c.PSA_ALG_IS_RAW_KEY_AGREEMENT" title="PSA_ALG_IS_RAW_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_RAW_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
<dd>Identifier of the private key to use.
It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
<dd>Public key of the peer. The peer key must be in the same format that <a class="reference internal" href="../keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> accepts for the public key type corresponding to the type of <code class="docutils literal"><span class="pre">private_key</span></code>. 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>, 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 ECC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of <a class="reference internal" href="../keys/management.html#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
<dd>Size of <code class="docutils literal"><span class="pre">peer_key</span></code> in bytes.</dd>
<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
<dd>Buffer where the raw shared secret is to be written.</dd>
<dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt>
<dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes.
This must be appropriate for the keys:</p>
<ul class="last simple">
<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>
<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>
</ul>
</dd>
<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
<dd>On success, the number of bytes that make up the returned output.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.
The first <code class="docutils literal"><span class="pre">(*output_length)</span></code> bytes of <code class="docutils literal"><span class="pre">output</span></code> contain the raw shared secret.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd>The library requires initializing by a call to <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>.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag, or it does not permit the requested algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt>
<dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small.
<a class="reference internal" href="#c.PSA_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 a sufficient buffer size.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not a key agreement algorithm.</li>
<li><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>.</li>
<li><code class="docutils literal"><span class="pre">peer_key</span></code> is not a valid public key corresponding to <code class="docutils literal"><span class="pre">private_key</span></code>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a key agreement algorithm.</li>
<li><code class="docutils literal"><span class="pre">private_key</span></code> is not supported for use with <code class="docutils literal"><span class="pre">alg</span></code>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<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>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<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>
</div>
</div>
</div>
<div class="section" id="combining-key-agreement-and-key-derivation">
<h2>10.9.3. Combining key agreement and key derivation</h2>
<div class="section" id="psa_key_derivation_key_agreement">
<span id="c.psa_key_derivation_key_agreement"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_key_agreement</span></code> (function)</h3>
<p>Perform a key agreement and use the shared secret as input to a key derivation.</p>
<pre class="literal-block">
<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement">psa_key_derivation_key_agreement</a>(<a class="reference internal" href="kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
<a class="reference internal" href="kdf.html#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> private_key,
const uint8_t * peer_key,
size_t peer_key_length);
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
<dd><p class="first">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>: a 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 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.</p>
<p class="last">The operation must be ready for an input of the type given by <code class="docutils literal"><span class="pre">step</span></code>.</p>
</dd>
<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
<dd>Which step the input data is for.</dd>
<dt> <code class="docutils literal"><span class="pre">private_key</span></code></dt>
<dd>Identifier of the private key to use.
It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key</span></code></dt>
<dd>Public key of the peer. The peer key must be in the same format that <a class="reference internal" href="../keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a> accepts for the public key type corresponding to the type of <code class="docutils literal"><span class="pre">private_key</span></code>. 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>, 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 ECC keys, this means that peer_key is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of <a class="reference internal" href="../keys/management.html#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>.</dd>
<dt> <code class="docutils literal"><span class="pre">peer_key_length</span></code></dt>
<dd>Size of <code class="docutils literal"><span class="pre">peer_key</span></code> in bytes.</dd>
</dl>
<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal"><span class="pre">psa_status_t</span></code></a></p>
<dl class="docutils">
<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></a></dt>
<dd>Success.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li>The operation state is not valid for this key agreement <code class="docutils literal"><span class="pre">step</span></code>.</li>
<li>The library requires initializing by a call to <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>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> is not a valid key identifier.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> 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 operation’s algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt>
<dd><p class="first">The following conditions can result in this error:</p>
<ul class="last simple">
<li>The operation’s algorithm is not a key agreement algorithm.</li>
<li><code class="docutils literal"><span class="pre">step</span></code> does not allow an input resulting from a key agreement.</li>
<li><code class="docutils literal"><span class="pre">private_key</span></code> is not compatible with the operation’s algorithm.</li>
<li><code class="docutils literal"><span class="pre">peer_key</span></code> is not a valid public key corresponding to <code class="docutils literal"><span class="pre">private_key</span></code>.</li>
</ul>
</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt>
<dd><code class="docutils literal"><span class="pre">private_key</span></code> is not supported for use with the operation’s algorithm.</dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt>
<dd></dd>
<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>
<dd></dd>
<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt>
<dd></dd>
</dl>
<p class="rubric">Description</p>
<p>A key agreement algorithm takes two inputs: a private key <code class="docutils literal"><span class="pre">private_key</span></code>, and a public key <code class="docutils literal"><span class="pre">peer_key</span></code>. The result of this function is passed as input to the key derivation operation. The output of this key derivation can be extracted by reading from the resulting operation to produce keys and other cryptographic material.</p>
<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="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>
</div>
</div>
<div class="section" id="support-macros">
<h2>10.9.4. Support macros</h2>
<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_BASE">
<span id="c.PSA_ALG_KEY_AGREEMENT_GET_BASE"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_KEY_AGREEMENT_GET_BASE</span></code> (macro)</h3>
<p>Get the raw key agreement algorithm from a full key agreement algorithm.</p>
<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>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>A key agreement algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The underlying raw key agreement algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
<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>
<p class="rubric">Description</p>
<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>
</div>
<div class="section" id="PSA_ALG_KEY_AGREEMENT_GET_KDF">
<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>
<p>Get the key derivation algorithm used in a full key agreement algorithm.</p>
<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>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>A key agreement algorithm: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a> such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_AGREEMENT" title="PSA_ALG_IS_KEY_AGREEMENT"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_AGREEMENT</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd>
</dl>
<p class="rubric">Returns</p>
<p>The underlying key derivation algorithm if <code class="docutils literal"><span class="pre">alg</span></code> is a key agreement algorithm.</p>
<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>
<p class="rubric">Description</p>
<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>
</div>
<div class="section" id="PSA_ALG_IS_RAW_KEY_AGREEMENT">
<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>
<p>Whether the specified algorithm is a raw key agreement algorithm.</p>
<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>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a raw key agreement algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p>
<p class="rubric">Description</p>
<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>
<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>
</div>
<div class="section" id="PSA_ALG_IS_FFDH">
<span id="c.PSA_ALG_IS_FFDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_FFDH</span></code> (macro)</h3>
<p>Whether the specified algorithm is a finite field Diffie-Hellman algorithm.</p>
<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>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a finite field Diffie-Hellman algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
<p class="rubric">Description</p>
<p>This includes the raw finite field Diffie-Hellman algorithm as well as finite-field Diffie-Hellman followed by any supported key derivation algorithm.</p>
</div>
<div class="section" id="PSA_ALG_IS_ECDH">
<span id="c.PSA_ALG_IS_ECDH"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_ECDH</span></code> (macro)</h3>
<p>Whether the specified algorithm is an elliptic curve Diffie-Hellman algorithm.</p>
<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>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
<dd>An algorithm identifier: a value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>.</dd>
</dl>
<p class="rubric">Returns</p>
<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an elliptic curve Diffie-Hellman algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key agreement algorithm identifier.</p>
<p class="rubric">Description</p>
<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>
</div>
<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE">
<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>
<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>
<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) \
<em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p class="rubric">Parameters</p>
<dl class="docutils">
<dt> <code class="docutils literal"><span class="pre">key_type</span></code></dt>
<dd>A supported key type.</dd>
<dt> <code class="docutils literal"><span class="pre">key_bits</span></code></dt>
<dd>The size of the key in bits.</dd>
</dl>
<p class="rubric">Returns</p>
<p>A sufficient output buffer size for the specified key type and size. An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a key type and size that it recognizes, but does not support. If the parameters are not valid, the return value is unspecified.</p>
<p class="rubric">Description</p>
<p>If the size of the output buffer is at least this large, it is guaranteed 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 due to an insufficient buffer size. The actual size of the output might be smaller in any given call.</p>
<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>
</div>
<div class="section" id="PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE">
<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>
<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>, for any of the supported key types and key agreement algorithms.</p>
<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> \
<em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
</pre>
<p>If the size of the output buffer is at least this large, it is guaranteed 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 due to an insufficient buffer size.</p>
<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>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
IHI 0086<br/>
Non-confidential<br/>
Version 1.1.0
<span style="color: red; font-weight: bold;"></span>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../about.html">About this document</a></li>
</ul>
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests (Hashes)</a></li>
<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
<li class="toctree-l2 current"><a class="current reference internal" href="#">10.9. Key agreement</a><ul>
<li class="toctree-l3"><a class="reference internal" href="#key-agreement-algorithms">10.9.1. Key agreement algorithms</a></li>
<li class="toctree-l3"><a class="reference internal" href="#standalone-key-agreement">10.9.2. Standalone key agreement</a></li>
<li class="toctree-l3"><a class="reference internal" href="#combining-key-agreement-and-key-derivation">10.9.3. Combining key agreement and key derivation</a></li>
<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.9.4. Support macros</a></li>
</ul>
</li>
<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
</ul>
</li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/encodings.html">Algorithm and key type encoding</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/sra.html">Security Risk Assessment</a></li>
<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
</ul>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<div><input type="text" name="q" /></div>
<div><input type="submit" value="Go" /></div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
&copy; 2018-2022, Arm Limited or its affiliates. All rights reserved.
|
Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
&amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
</div>
</body>
</html>