TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / c2db5f0e443752021c73fb4440a339e2cbc10fb7 / . / docs / html / api / ops / kdf.html
blob: 38371cce6eaa3ee88d7f88b86224756fb7d9a978 [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.6. Key derivation &#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.7. Asymmetric signature" href="sign.html" />
28 <link rel="prev" title="10.5. Authenticated encryption with associated data (AEAD)" href="aead.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-derivation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]44<span id="kdf"></span><h1>10.6. Key derivation</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="key-derivation-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]46<span id="id1"></span><h2>10.6.1. Key derivation algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="PSA_ALG_HKDF">
48<span id="c.PSA_ALG_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</h3>
49<p>Macro to build an HKDF algorithm.</p>
50<pre class="literal-block">
51#define <a class="reference internal" href="#c.PSA_ALG_HKDF" title="PSA_ALG_HKDF">PSA_ALG_HKDF</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
52</pre>
53<p class="rubric">Parameters</p>
54<dl class="docutils">
55<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]56<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]57</dl>
58<p class="rubric">Returns</p>
59<p>The corresponding HKDF algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_HKDF" title="PSA_ALG_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> is HKDF using HMAC-SHA-256.</p>
60<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
61<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]62<p>This is the HMAC-based Extract-and-Expand Key Derivation Function (HKDF) specified by <span><em>HMAC-based Extract-and-Expand Key Derivation Function (HKDF)</em> <a class="reference internal" href="../../about.html#citation-rfc5869"><span class="cite">[RFC5869]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]63<p>This key derivation algorithm uses the following inputs:</p>
64<ul class="simple">
65<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SALT" title="PSA_KEY_DERIVATION_INPUT_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code></a> is the salt used in the “extract” step. It is optional; if omitted, the derivation uses an empty salt.</li>
66<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is the secret key used in the “extract” step.</li>
67<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> is the info string used in the “expand” step.</li>
68</ul>
69<p>If <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SALT" title="PSA_KEY_DERIVATION_INPUT_SALT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code></a> is provided, it must be before <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a>. <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> can be provided at any time after setup and before starting to generate output.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]70<p>Each input may only be passed once.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]71</div>
72<div class="section" id="PSA_ALG_TLS12_PRF">
73<span id="c.PSA_ALG_TLS12_PRF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</h3>
74<p>Macro to build a TLS-1.2 PRF algorithm.</p>
75<pre class="literal-block">
76#define <a class="reference internal" href="#c.PSA_ALG_TLS12_PRF" title="PSA_ALG_TLS12_PRF">PSA_ALG_TLS12_PRF</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
77</pre>
78<p class="rubric">Parameters</p>
79<dl class="docutils">
80<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]81<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]82</dl>
83<p class="rubric">Returns</p>
84<p>The corresponding TLS-1.2 PRF algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_TLS12_PRF" title="PSA_ALG_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> represents the TLS 1.2 PRF using HMAC-SHA-256.</p>
85<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
86<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]87<p>TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in <span><em>The Transport Layer Security (TLS) Protocol Version 1.2</em> <a class="reference internal" href="../../about.html#citation-rfc5246"><span class="cite">[RFC5246]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">§5</a>. It is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]88<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
89<ul class="simple">
90<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SEED" title="PSA_KEY_DERIVATION_INPUT_SEED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code></a> is the seed.</li>
91<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is the secret key.</li>
92<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_LABEL" title="PSA_KEY_DERIVATION_INPUT_LABEL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code></a> is the label.</li>
93</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]94<p>Each input may only be passed once.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]95<p>For the application to TLS-1.2 key expansion:</p>
96<ul class="simple">
97<li>The seed is the concatenation of <code class="docutils literal"><span class="pre">ServerHello.Random</span> <span class="pre">+</span> <span class="pre">ClientHello.Random</span></code>.</li>
98<li>The label is <code class="docutils literal"><span class="pre">&quot;key</span> <span class="pre">expansion&quot;</span></code>.</li>
99</ul>
100</div>
101<div class="section" id="PSA_ALG_TLS12_PSK_TO_MS">
102<span id="c.PSA_ALG_TLS12_PSK_TO_MS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code> (macro)</h3>
103<p>Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.</p>
104<pre class="literal-block">
105#define <a class="reference internal" href="#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS">PSA_ALG_TLS12_PSK_TO_MS</a>(hash_alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em>
106</pre>
107<p class="rubric">Parameters</p>
108<dl class="docutils">
109<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]110<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]111</dl>
112<p class="rubric">Returns</p>
113<p>The corresponding TLS-1.2 PSK to MS algorithm. For example, <a class="reference internal" href="#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="hashes.html#c.PSA_ALG_SHA_256" title="PSA_ALG_SHA_256"><code class="docutils literal"><span class="pre">PSA_ALG_SHA_256</span></code></a><code class="docutils literal"><span class="pre">)</span></code> represents the TLS-1.2 PSK to MasterSecret derivation PRF using HMAC-SHA-256.</p>
114<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
115<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]116<p>In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK) through the application of padding (<span><em>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</em> <a class="reference internal" href="../../about.html#citation-rfc4279"><span class="cite">[RFC4279]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-2">§2</a>) and the TLS-1.2 PRF (<span><em>The Transport Layer Security (TLS) Protocol Version 1.2</em> <a class="reference internal" href="../../about.html#citation-rfc5246"><span class="cite">[RFC5246]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">§5</a>). The latter is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]117<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
118<ul class="simple">
119<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SEED" title="PSA_KEY_DERIVATION_INPUT_SEED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code></a> is the seed.</li>
120<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> is the PSK. The PSK must not be larger than <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code></a>.</li>
121<li><a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_LABEL" title="PSA_KEY_DERIVATION_INPUT_LABEL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code></a> is the label.</li>
122</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]123<p>Each input may only be passed once.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]124<p>For the application to TLS-1.2:</p>
125<ul class="simple">
126<li>The seed, which is forwarded to the TLS-1.2 PRF, is the concatenation of the <code class="docutils literal"><span class="pre">ClientHello.Random</span> <span class="pre">+</span> <span class="pre">ServerHello.Random</span></code>.</li>
127<li>The label is <code class="docutils literal"><span class="pre">&quot;master</span> <span class="pre">secret&quot;</span></code> or <code class="docutils literal"><span class="pre">&quot;extended</span> <span class="pre">master</span> <span class="pre">secret&quot;</span></code>.</li>
128</ul>
129</div>
130</div>
131<div class="section" id="input-step-types">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]132<h2>10.6.2. Input step types</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]133<div class="section" id="psa_key_derivation_step_t">
134<span id="c.psa_key_derivation_step_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_step_t</span></code> (type)</h3>
135<p>Encoding of the step of a key derivation.</p>
136<pre class="literal-block">
137typedef uint16_t <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a>;
138</pre>
139</div>
140<div class="section" id="PSA_KEY_DERIVATION_INPUT_SECRET">
141<span id="c.PSA_KEY_DERIVATION_INPUT_SECRET"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> (macro)</h3>
142<p>A secret input for key derivation.</p>
143<pre class="literal-block">
144#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET">PSA_KEY_DERIVATION_INPUT_SECRET</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
145</pre>
146<p>This is typically a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DERIVE" title="PSA_KEY_TYPE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DERIVE</span></code></a> passed to <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a>, or the shared secret resulting from a key agreement obtained via <a class="reference internal" href="ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a>.</p>
147<p>The secret can also be a direct input passed to <a class="reference internal" href="#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a>. In this case, the derivation operation cannot be used to derive keys: the operation will only allow <a class="reference internal" href="#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a>, not <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a>.</p>
148</div>
149<div class="section" id="PSA_KEY_DERIVATION_INPUT_LABEL">
150<span id="c.PSA_KEY_DERIVATION_INPUT_LABEL"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code> (macro)</h3>
151<p>A label for key derivation.</p>
152<pre class="literal-block">
153#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_LABEL" title="PSA_KEY_DERIVATION_INPUT_LABEL">PSA_KEY_DERIVATION_INPUT_LABEL</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
154</pre>
155<p>This is typically a direct input. It can also be a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RAW_DATA" title="PSA_KEY_TYPE_RAW_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RAW_DATA</span></code></a>.</p>
156</div>
157<div class="section" id="PSA_KEY_DERIVATION_INPUT_CONTEXT">
158<span id="c.PSA_KEY_DERIVATION_INPUT_CONTEXT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_CONTEXT</span></code> (macro)</h3>
159<p>A context for key derivation.</p>
160<pre class="literal-block">
161#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_CONTEXT" title="PSA_KEY_DERIVATION_INPUT_CONTEXT">PSA_KEY_DERIVATION_INPUT_CONTEXT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
162</pre>
163<p>This is typically a direct input. It can also be a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RAW_DATA" title="PSA_KEY_TYPE_RAW_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RAW_DATA</span></code></a>.</p>
164</div>
165<div class="section" id="PSA_KEY_DERIVATION_INPUT_SALT">
166<span id="c.PSA_KEY_DERIVATION_INPUT_SALT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code> (macro)</h3>
167<p>A salt for key derivation.</p>
168<pre class="literal-block">
169#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SALT" title="PSA_KEY_DERIVATION_INPUT_SALT">PSA_KEY_DERIVATION_INPUT_SALT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
170</pre>
171<p>This is typically a direct input. It can also be a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RAW_DATA" title="PSA_KEY_TYPE_RAW_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RAW_DATA</span></code></a>.</p>
172</div>
173<div class="section" id="PSA_KEY_DERIVATION_INPUT_INFO">
174<span id="c.PSA_KEY_DERIVATION_INPUT_INFO"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code> (macro)</h3>
175<p>An information string for key derivation.</p>
176<pre class="literal-block">
177#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO">PSA_KEY_DERIVATION_INPUT_INFO</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
178</pre>
179<p>This is typically a direct input. It can also be a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RAW_DATA" title="PSA_KEY_TYPE_RAW_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RAW_DATA</span></code></a>.</p>
180</div>
181<div class="section" id="PSA_KEY_DERIVATION_INPUT_SEED">
182<span id="c.PSA_KEY_DERIVATION_INPUT_SEED"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code> (macro)</h3>
183<p>A seed for key derivation.</p>
184<pre class="literal-block">
185#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SEED" title="PSA_KEY_DERIVATION_INPUT_SEED">PSA_KEY_DERIVATION_INPUT_SEED</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
186</pre>
187<p>This is typically a direct input. It can also be a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RAW_DATA" title="PSA_KEY_TYPE_RAW_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RAW_DATA</span></code></a>.</p>
188</div>
189</div>
190<div class="section" id="key-derivation-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]191<h2>10.6.3. Key derivation functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]192<div class="section" id="psa_key_derivation_operation_t">
193<span id="c.psa_key_derivation_operation_t"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code> (type)</h3>
194<p>The type of the state object for key derivation operations.</p>
195<pre class="literal-block">
196typedef <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a>;
197</pre>
198<p>Before calling any function on a key derivation operation object, the application must initialize it by any of the following means:</p>
199<ul>
200<li><p class="first">Set the object to all-bits-zero, for example:</p>
201<pre class="literal-block">
202<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation;
203memset(&amp;operation, 0, sizeof(operation));
204</pre>
205</li>
206<li><p class="first">Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
207<pre class="literal-block">
208static <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation;
209</pre>
210</li>
211<li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>, for example:</p>
212<pre class="literal-block">
213<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation = <a class="reference internal" href="#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT">PSA_KEY_DERIVATION_OPERATION_INIT</a>;
214</pre>
215</li>
216<li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_key_derivation_operation_init" title="psa_key_derivation_operation_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_operation_init()</span></code></a> to the object, for example:</p>
217<pre class="literal-block">
218<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation;
219operation = <a class="reference internal" href="#c.psa_key_derivation_operation_init" title="psa_key_derivation_operation_init">psa_key_derivation_operation_init</a>();
220</pre>
221</li>
222</ul>
223<p>This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.</p>
224</div>
225<div class="section" id="PSA_KEY_DERIVATION_OPERATION_INIT">
226<span id="c.PSA_KEY_DERIVATION_OPERATION_INIT"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code> (macro)</h3>
227<p>This macro returns a suitable initializer for a key derivation operation object of type <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a>.</p>
228<pre class="literal-block">
229#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT">PSA_KEY_DERIVATION_OPERATION_INIT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
230</pre>
231</div>
232<div class="section" id="psa_key_derivation_operation_init">
233<span id="c.psa_key_derivation_operation_init"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_operation_init</span></code> (function)</h3>
234<p>Return an initial value for a key derivation operation object.</p>
235<pre class="literal-block">
236<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> <a class="reference internal" href="#c.psa_key_derivation_operation_init" title="psa_key_derivation_operation_init">psa_key_derivation_operation_init</a>(void);
237</pre>
238<p class="rubric">Returns: <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a></p>
239</div>
240<div class="section" id="psa_key_derivation_setup">
241<span id="c.psa_key_derivation_setup"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_setup</span></code> (function)</h3>
242<p>Set up a key derivation operation.</p>
243<pre class="literal-block">
244<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_setup" title="psa_key_derivation_setup">psa_key_derivation_setup</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]245 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]246</pre>
247<p class="rubric">Parameters</p>
248<dl class="docutils">
249<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
250<dd>The key derivation operation object to set up. It must have been initialized but not set up yet.</dd>
251<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]252<dd>The key derivation algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]253</dl>
254<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>
255<dl class="docutils">
256<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>
257<dd>Success.</dd>
258<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>
259<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a key derivation algorithm.</dd>
260<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>
261<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a key derivation algorithm.</dd>
262<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>
263<dd></dd>
264<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>
265<dd></dd>
266<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>
267<dd></dd>
268<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>
269<dd></dd>
270<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>
271<dd></dd>
272<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>
273<dd></dd>
274<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>
275<dd></dd>
276<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>
277<dd>The operation state is not valid: it must be inactive.</dd>
278<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>
279<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>
280</dl>
281<p class="rubric">Description</p>
282<p>A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material.</p>
283<p>To derive a key:</p>
284<ol class="arabic simple">
285<li>Start with an initialized object of type <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a>.</li>
286<li>Call <a class="reference internal" href="#c.psa_key_derivation_setup" title="psa_key_derivation_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_setup()</span></code></a> to select the algorithm.</li>
287<li>Provide the inputs for the key derivation by calling <a class="reference internal" href="#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> or <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> as appropriate. Which inputs are needed, in what order, whether keys are permitted, and what type of keys depends on the algorithm.</li>
288<li>Optionally set the operation’s maximum capacity with <a class="reference internal" href="#c.psa_key_derivation_set_capacity" title="psa_key_derivation_set_capacity"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_set_capacity()</span></code></a>. This can be done before, in the middle of, or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity.</li>
289<li>To derive a key, call <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a>. To derive a byte string for a different purpose, call <a class="reference internal" href="#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a>. Successive calls to these functions use successive output bytes calculated by the key derivation algorithm.</li>
290<li>Clean up the key derivation operation object with <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a>.</li>
291</ol>
292<p>If this function returns an error, the key derivation operation object is not changed.</p>
293<p>If an error occurs at any step after a call to <a class="reference internal" href="#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>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a>.</p>
294<p>Implementations must reject an attempt to derive a key of size <code class="docutils literal"><span class="pre">0</span></code>.</p>
295</div>
296<div class="section" id="psa_key_derivation_get_capacity">
297<span id="c.psa_key_derivation_get_capacity"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_get_capacity</span></code> (function)</h3>
298<p>Retrieve the current capacity of a key derivation operation.</p>
299<pre class="literal-block">
300<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_get_capacity" title="psa_key_derivation_get_capacity">psa_key_derivation_get_capacity</a>(const <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
301 size_t * capacity);
302</pre>
303<p class="rubric">Parameters</p>
304<dl class="docutils">
305<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
306<dd>The operation to query.</dd>
307<dt> <code class="docutils literal"><span class="pre">capacity</span></code></dt>
308<dd>On success, the capacity of the operation.</dd>
309</dl>
310<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>
311<dl class="docutils">
312<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>
313<dd></dd>
314<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>
315<dd></dd>
316<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>
317<dd>The operation state is not valid: it must be active.</dd>
318<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>
319<dd></dd>
320<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>
321<dd></dd>
322<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>
323<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>
324</dl>
325<p class="rubric">Description</p>
326<p>The capacity of a key derivation is the maximum number of bytes that it can return. Reading <em>N</em> bytes of output from a key derivation operation reduces its capacity by at least <em>N</em>. The capacity can be reduced by more than <em>N</em> in the following situations:</p>
327<ul class="simple">
328<li>Calling <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> can reduce the capacity by more than the key size, depending on the type of key being generated. See <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> for details of the key derivation process.</li>
329<li>When the <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a> object is operating as a deterministic random bit generator (DBRG), which reduces capacity in whole blocks, even when less than a block is read.</li>
330</ul>
331</div>
332<div class="section" id="psa_key_derivation_set_capacity">
333<span id="c.psa_key_derivation_set_capacity"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_set_capacity</span></code> (function)</h3>
334<p>Set the maximum capacity of a key derivation operation.</p>
335<pre class="literal-block">
336<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_set_capacity" title="psa_key_derivation_set_capacity">psa_key_derivation_set_capacity</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
337 size_t capacity);
338</pre>
339<p class="rubric">Parameters</p>
340<dl class="docutils">
341<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
342<dd>The key derivation operation object to modify.</dd>
343<dt> <code class="docutils literal"><span class="pre">capacity</span></code></dt>
344<dd>The new capacity of the operation. It must be less or equal to the operation’s current capacity.</dd>
345</dl>
346<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>
347<dl class="docutils">
348<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>
349<dd></dd>
350<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>
351<dd><code class="docutils literal"><span class="pre">capacity</span></code> is larger than the operation’s current capacity. In this case, the operation object remains valid and its capacity remains unchanged.</dd>
352<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>
353<dd>The operation state is not valid: it must be active.</dd>
354<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>
355<dd></dd>
356<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>
357<dd></dd>
358<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>
359<dd></dd>
360<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>
361<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>
362</dl>
363<p class="rubric">Description</p>
364<p>The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.</p>
365</div>
366<div class="section" id="psa_key_derivation_input_bytes">
367<span id="c.psa_key_derivation_input_bytes"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_input_bytes</span></code> (function)</h3>
368<p>Provide an input for key derivation or key agreement.</p>
369<pre class="literal-block">
370<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes">psa_key_derivation_input_bytes</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
371 <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
372 const uint8_t * data,
373 size_t data_length);
374</pre>
375<p class="rubric">Parameters</p>
376<dl class="docutils">
377<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
378<dd>The key derivation operation object to use. It must have been set up with <a class="reference internal" href="#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> and must not have produced any output yet.</dd>
379<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
380<dd>Which step the input data is for.</dd>
381<dt> <code class="docutils literal"><span class="pre">data</span></code></dt>
382<dd>Input data to use.</dd>
383<dt> <code class="docutils literal"><span class="pre">data_length</span></code></dt>
384<dd>Size of the <code class="docutils literal"><span class="pre">data</span></code> buffer in bytes.</dd>
385</dl>
386<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>
387<dl class="docutils">
388<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>
389<dd>Success.</dd>
390<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>
391<dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd>
392<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>
393<dd><code class="docutils literal"><span class="pre">step</span></code> does not allow direct inputs.</dd>
394<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>
395<dd></dd>
396<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>
397<dd></dd>
398<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>
399<dd></dd>
400<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>
401<dd></dd>
402<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>
403<dd></dd>
404<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>
405<dd></dd>
406<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>
407<dd></dd>
408<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]409<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>. This can happen if the application provides a step out of order or repeats a step that may not be repeated.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]410<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>
411<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>
412</dl>
413<p class="rubric">Description</p>
414<p>Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.</p>
415<p>This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which is normally in a key object, call <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> instead of this function. Refer to the documentation of individual step types (<code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_xxx</span></code> values of type <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_step_t</span></code></a>) for more information.</p>
416<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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>
417</div>
418<div class="section" id="psa_key_derivation_input_key">
419<span id="c.psa_key_derivation_input_key"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_input_key</span></code> (function)</h3>
420<p>Provide an input for key derivation in the form of a key.</p>
421<pre class="literal-block">
422<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key">psa_key_derivation_input_key</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
423 <a class="reference internal" href="#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^]424 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]425</pre>
426<p class="rubric">Parameters</p>
427<dl class="docutils">
428<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
429<dd>The key derivation operation object to use. It must have been set up with <a class="reference internal" href="#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> and must not have produced any output yet.</dd>
430<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
431<dd>Which step the input data is for.</dd>
432<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]433<dd>Identifier of the key. It must have an appropriate type for <code class="docutils literal"><span class="pre">step</span></code> and must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]434</dl>
435<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>
436<dl class="docutils">
437<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>
438<dd>Success.</dd>
439<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>
440<dd></dd>
441<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^]442<dd>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]443<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>
444<dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd>
445<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>
446<dd><code class="docutils literal"><span class="pre">step</span></code> does not allow key inputs of the given type or does not allow key inputs at all.</dd>
447<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>
448<dd></dd>
449<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>
450<dd></dd>
451<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>
452<dd></dd>
453<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>
454<dd></dd>
455<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>
456<dd></dd>
457<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>
458<dd></dd>
459<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>
460<dd></dd>
461<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]462<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>. This can happen if the application provides a step out of order or repeats a step that may not be repeated.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]463<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>
464<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>
465</dl>
466<p class="rubric">Description</p>
467<p>Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.</p>
468<p>This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call <a class="reference internal" href="#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> instead of this function. Refer to the documentation of individual step types (<code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_xxx</span></code> values of type <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_step_t</span></code></a>) for more information.</p>
469<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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>
470</div>
471<div class="section" id="psa_key_derivation_output_bytes">
472<span id="c.psa_key_derivation_output_bytes"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_output_bytes</span></code> (function)</h3>
473<p>Read some data from a key derivation operation.</p>
474<pre class="literal-block">
475<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes">psa_key_derivation_output_bytes</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
476 uint8_t * output,
477 size_t output_length);
478</pre>
479<p class="rubric">Parameters</p>
480<dl class="docutils">
481<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
482<dd>The key derivation operation object to read from.</dd>
483<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
484<dd>Buffer where the output will be written.</dd>
485<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
486<dd>Number of bytes to output.</dd>
487</dl>
488<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>
489<dl class="docutils">
490<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>
491<dd></dd>
492<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a></dt>
493<dd>The operation’s capacity was less than <code class="docutils literal"><span class="pre">output_length</span></code> bytes. Note that in this case, no output is written to the output buffer. The operation’s capacity is set to <code class="docutils literal"><span class="pre">0</span></code>, thus subsequent calls to this function will not succeed, even with a smaller output buffer.</dd>
494<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>
495<dd>The operation state is not valid: it must be active and completed all required input steps.</dd>
496<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>
497<dd></dd>
498<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>
499<dd></dd>
500<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>
501<dd></dd>
502<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>
503<dd></dd>
504<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>
505<dd></dd>
506<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>
507<dd></dd>
508<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>
509<dd></dd>
510<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>
511<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>
512</dl>
513<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]514<p>This function calculates output bytes from a key derivation algorithm and returns those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]515<p>If this function returns an error status other than <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a>, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a>.</p>
516</div>
517<div class="section" id="psa_key_derivation_output_key">
518<span id="c.psa_key_derivation_output_key"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_output_key</span></code> (function)</h3>
519<p>Derive a key from an ongoing key derivation operation.</p>
520<pre class="literal-block">
521<a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key">psa_key_derivation_output_key</a>(const <a class="reference internal" href="../keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t">psa_key_attributes_t</a> * attributes,
522 <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]523 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]524</pre>
525<p class="rubric">Parameters</p>
526<dl class="docutils">
527<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]528<dd><p class="first">The attributes for the new key.
529This function uses the attributes as follows:</p>
530<ul class="simple">
531<li>The key type is required. It cannot be an asymmetric public key.</li>
532<li>The key size is required. It must be a valid size for the key type.</li>
533<li>The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see <a class="reference internal" href="../keys/policy.html#permitted-algorithms"><span class="secref">Permitted algorithms</span></a>.</li>
534<li>The key usage flags define what operations are permitted with the key, see <a class="reference internal" href="../keys/policy.html#key-usage-flags"><span class="secref">Key usage flags</span></a>.</li>
535<li>The key lifetime and identifier are required for a persistent key.</li>
536</ul>
537<div class="last admonition note">
538<p class="first admonition-title">Note</p>
539<p class="last">This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling <a class="reference internal" href="../keys/attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_get_key_attributes()</span></code></a> with the key’s identifier.</p>
540</div>
541</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]542<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
543<dd>The key derivation operation object to read from.</dd>
544<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]545<dd>On success, an identifier for the newly created key. <a class="reference internal" href="../keys/ids.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]546</dl>
547<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>
548<dl class="docutils">
549<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>
550<dd>Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.</dd>
551<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_ALREADY_EXISTS" title="PSA_ERROR_ALREADY_EXISTS"><code class="docutils literal"><span class="pre">PSA_ERROR_ALREADY_EXISTS</span></code></a></dt>
552<dd>This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.</dd>
553<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a></dt>
554<dd>There was not enough data to create the desired key. Note that in this case, no output is written to the output buffer. The operation’s capacity is set to <code class="docutils literal"><span class="pre">0</span></code>, thus subsequent calls to this function will not succeed, even with a smaller output buffer.</dd>
555<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>
556<dd>The key type or key size is not supported, either by the implementation in general or in this particular location.</dd>
557<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>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]558<dd>The key attributes, as a whole, are invalid.</dd>
559<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>
560<dd>The key type is an asymmetric public key type.</dd>
561<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>
562<dd>The key size is not a valid size for the key type.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]563<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^]564<dd>The <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> input was neither provided through a key nor the result of a key agreement.</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]565<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>
566<dd>The operation state is not valid: it must be active and completed all required input steps.</dd>
567<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>
568<dd></dd>
569<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_STORAGE" title="PSA_ERROR_INSUFFICIENT_STORAGE"><code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_STORAGE</span></code></a></dt>
570<dd></dd>
571<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>
572<dd></dd>
573<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>
574<dd></dd>
575<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>
576<dd></dd>
577<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>
578<dd></dd>
579<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>
580<dd></dd>
581<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>
582<dd></dd>
583<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>
584<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>
585</dl>
586<p class="rubric">Description</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]587<p>This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, policy, type and size are taken from <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]588<p>If the key derivation’s output is viewed as a stream of bytes, this function consumes the required number of bytes from the stream. The operation’s capacity decreases by the number of bytes used to derive the key.</p>
589<p>If this function returns an error status other than <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_DATA" title="PSA_ERROR_INSUFFICIENT_DATA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_DATA</span></code></a>, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]590<p>How much output is produced and consumed from the operation, and how the key is derived, depends on the key type. <span><a class="reference internal" href="#std-key-derivation"><span class="numref">Table 5</span></a></span> describes the required key derivation procedures for standard key derivation algorithms. Implementations can use other methods for implementation-specific algorithms.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]591<p>In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by the number of bytes read.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]592<table border="1" class="colwidths-given longtable docutils align-right" id="std-key-derivation">
593<caption><span class="caption-number">Table 5 </span><span class="caption-text">Standard key derivation process</span></caption>
594<colgroup>
595<col width="29%" />
596<col width="71%" />
597</colgroup>
598<thead valign="bottom">
599<tr class="row-odd"><th class="head">Key type</th>
600<th class="head">Key type details and derivation procedure</th>
601</tr>
602</thead>
603<tbody valign="top">
604<tr class="row-even"><td><p class="first">AES</p>
605<p>ARC4</p>
606<p>CAMELLIA</p>
607<p>ChaCha20</p>
608<p>SM4</p>
609<p>Secrets for derivation</p>
610<p class="last">HMAC</p>
611</td>
612<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a></p>
613<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a></p>
614<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a></p>
615<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a></p>
616<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_SM4" title="PSA_KEY_TYPE_SM4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_SM4</span></code></a></p>
617<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DERIVE" title="PSA_KEY_TYPE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DERIVE</span></code></a></p>
618<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_HMAC" title="PSA_KEY_TYPE_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_HMAC</span></code></a></p>
619<p class="last">For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling <a class="reference internal" href="#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> and passing the resulting output to <a class="reference internal" href="../keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly <code class="docutils literal"><span class="pre">(bits/8)</span></code> bytes from the operation.</p>
620</td>
621</tr>
622<tr class="row-odd"><td>DES</td>
623<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 64 bits.</p>
624<p>This function generates a key using the following process:</p>
625<ol class="last arabic simple">
626<li>Draw an 8-byte string.</li>
627<li>Set/clear the parity bits in each byte.</li>
628<li>If the result is a forbidden weak key, discard the result and return to step 1.</li>
629<li>Output the string.</li>
630</ol>
631</td>
632</tr>
633<tr class="row-even"><td><p class="first">2-key 3DES</p>
634<p class="last">3-key 3DES</p>
635</td>
636<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 192 bits.</p>
637<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>, 128 bits.</p>
638<p>The two or three keys are generated by repeated application of the process used to generate a DES key.</p>
639<p class="last">For example, for 3-key 3DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.</p>
640</td>
641</tr>
642<tr class="row-odd"><td><p class="first">Finite-field Diffie-Hellman keys</p>
643<p class="last">ECC keys on a Weierstrass elliptic curve</p>
644</td>
645<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DH_KEY_PAIR" title="PSA_KEY_TYPE_DH_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_DH_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">dh_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">dh_family</span></code> designates any Diffie-Hellman family.</p>
646<p><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ecc_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">ecc_family</span></code> designates a Weierstrass curve family.</p>
647<p>These key types require the generation of a private key which is an integer in the range [1, <em>N</em> - 1], where <em>N</em> is the boundary of the private key domain: <em>N</em> is the prime <em>p</em> for Diffie-Hellman, or the order of the curve’s base point for ECC.</p>
648<p>Let <code class="docutils literal"><span class="pre">m</span></code> be the bit size of <em>N</em>, such that <code class="docutils literal"><span class="pre">2^m</span></code> &gt; <em>N</em> &gt;= <code class="docutils literal"><span class="pre">2^(m-1)</span></code>. This function generates the private key using the following process:</p>
649<ol class="arabic simple">
650<li>Draw a byte string of length <code class="docutils literal"><span class="pre">ceiling(m/8)</span></code> bytes.</li>
651<li>If <code class="docutils literal"><span class="pre">m</span></code> is not a multiple of <code class="docutils literal"><span class="pre">8</span></code>, set the most significant <code class="docutils literal"><span class="pre">(8</span> <span class="pre">*</span> <span class="pre">ceiling(m/8)</span> <span class="pre">-</span> <span class="pre">m)</span></code> bits of the first byte in the string to zero.</li>
652<li>Convert the string to integer <em>k</em> by decoding it as a big-endian byte string.</li>
653<li>If <em>k</em> &gt; <em>N</em> - <code class="docutils literal"><span class="pre">2</span></code>, discard the result and return to step 1.</li>
654<li>Output <em>k</em> + <code class="docutils literal"><span class="pre">1</span></code> as the private key.</li>
655</ol>
656<p>This method allows compliance to NIST standards, specifically the methods titled <em>Key-Pair Generation by Testing Candidates</em> in the following publications:</p>
657<ul class="last simple">
658<li><span><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em> <a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a></span> §5.6.1.1.4 for Diffie-Hellman keys.</li>
659<li><a class="reference internal" href="../../about.html#citation-sp800-56a"><span class="cite">[SP800-56A]</span></a> §5.6.1.2.2 or <span><em>FIPS Publication 186-4: Digital Signature Standard (DSS)</em> <a class="reference internal" href="../../about.html#citation-fips186-4"><span class="cite">[FIPS186-4]</span></a></span> §B.4.2 for elliptic curve keys.</li>
660</ul>
661</td>
662</tr>
663<tr class="row-even"><td>ECC keys on a Montgomery elliptic curve</td>
664<td><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a><code class="docutils literal"><span class="pre">)</span></code></p>
665<p>This function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:</p>
666<ul class="last simple">
667<li>Curve25519 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 255 bits): draw a 32-byte string and process it as specified in <span><em>Elliptic Curves for Security</em> <a class="reference internal" href="../../about.html#citation-rfc7748"><span class="cite">[RFC7748]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">§5</a>.</li>
668<li>Curve448 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 448 bits): draw a 56-byte string and process it as specified in <a class="reference internal" href="../../about.html#citation-rfc7748"><span class="cite">[RFC7748]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">§5</a>.</li>
669</ul>
670</td>
671</tr>
672<tr class="row-odd"><td><em>Other key types</em></td>
673<td><p class="first">This includes <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>.</p>
674<p class="last">The way in which the operation output is consumed is implementation-defined.</p>
675</td>
676</tr>
677</tbody>
678</table>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]679<p>For algorithms that take an input step <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a>, the input to that step must be provided with <a class="reference internal" href="#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a>. Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.</p>
680</div>
681<div class="section" id="psa_key_derivation_abort">
682<span id="c.psa_key_derivation_abort"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_abort</span></code> (function)</h3>
683<p>Abort a key derivation operation.</p>
684<pre class="literal-block">
685<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_abort" title="psa_key_derivation_abort">psa_key_derivation_abort</a>(<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation);
686</pre>
687<p class="rubric">Parameters</p>
688<dl class="docutils">
689<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
690<dd>The operation to abort.</dd>
691</dl>
692<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>
693<dl class="docutils">
694<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>
695<dd></dd>
696<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>
697<dd></dd>
698<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>
699<dd></dd>
700<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>
701<dd></dd>
702<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>
703<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>
704</dl>
705<p class="rubric">Description</p>
706<p>Aborting an operation frees all associated resources except for the <code class="docutils literal"><span class="pre">operation</span></code> object itself. Once aborted, the operation object can be reused for another operation by calling <a class="reference internal" href="#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> again.</p>
707<p>This function can be called at any time after the operation object has been initialized as described in <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a>.</p>
708<p>In particular, it is valid to call <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> twice, or to call <a class="reference internal" href="#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> on an operation that has not been set up.</p>
709</div>
710</div>
711<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]712<h2>10.6.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]713<div class="section" id="PSA_ALG_IS_HKDF">
714<span id="c.PSA_ALG_IS_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</h3>
715<p>Whether the specified algorithm is an HKDF algorithm.</p>
716<pre class="literal-block">
717#define <a class="reference internal" href="#c.PSA_ALG_IS_HKDF" title="PSA_ALG_IS_HKDF">PSA_ALG_IS_HKDF</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>
718</pre>
719<p class="rubric">Parameters</p>
720<dl class="docutils">
721<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]722<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]723</dl>
724<p class="rubric">Returns</p>
725<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is an HKDF algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
726<p class="rubric">Description</p>
727<p>HKDF is a family of key derivation algorithms that are based on a hash function and the HMAC construction.</p>
728</div>
729<div class="section" id="PSA_ALG_IS_TLS12_PRF">
730<span id="c.PSA_ALG_IS_TLS12_PRF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PRF</span></code> (macro)</h3>
731<p>Whether the specified algorithm is a TLS-1.2 PRF algorithm.</p>
732<pre class="literal-block">
733#define <a class="reference internal" href="#c.PSA_ALG_IS_TLS12_PRF" title="PSA_ALG_IS_TLS12_PRF">PSA_ALG_IS_TLS12_PRF</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>
734</pre>
735<p class="rubric">Parameters</p>
736<dl class="docutils">
737<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]738<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]739</dl>
740<p class="rubric">Returns</p>
741<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a TLS-1.2 PRF algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
742</div>
743<div class="section" id="PSA_ALG_IS_TLS12_PSK_TO_MS">
744<span id="c.PSA_ALG_IS_TLS12_PSK_TO_MS"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PSK_TO_MS</span></code> (macro)</h3>
745<p>Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.</p>
746<pre class="literal-block">
747#define <a class="reference internal" href="#c.PSA_ALG_IS_TLS12_PSK_TO_MS" title="PSA_ALG_IS_TLS12_PSK_TO_MS">PSA_ALG_IS_TLS12_PSK_TO_MS</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>
748</pre>
749<p class="rubric">Parameters</p>
750<dl class="docutils">
751<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]752<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]753</dl>
754<p class="rubric">Returns</p>
755<p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a TLS-1.2 PSK to MS algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported key derivation algorithm identifier.</p>
756</div>
757<div class="section" id="PSA_KEY_DERIVATION_UNLIMITED_CAPACITY">
758<span id="c.PSA_KEY_DERIVATION_UNLIMITED_CAPACITY"></span><h3><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_UNLIMITED_CAPACITY</span></code> (macro)</h3>
759<p>Use the maximum possible capacity for a key derivation operation.</p>
760<pre class="literal-block">
761#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_UNLIMITED_CAPACITY" title="PSA_KEY_DERIVATION_UNLIMITED_CAPACITY">PSA_KEY_DERIVATION_UNLIMITED_CAPACITY</a> \
762 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
763</pre>
764<p>Use this value as the capacity argument when setting up a key derivation to specify that the operation will use the maximum possible capacity. The value of the maximum possible capacity depends on the key derivation algorithm.</p>
765</div>
766<div class="section" id="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE">
767<span id="c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"></span><h3><code class="docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code> (macro)</h3>
768<p>This macro returns the maximum supported length of the PSK for the TLS-1.2 PSK-to-MS key derivation.</p>
769<pre class="literal-block">
770#define <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
771</pre>
772<p>This implementation-defined value specifies the maximum length for the PSK input used with a <a class="reference internal" href="#c.PSA_ALG_TLS12_PSK_TO_MS" title="PSA_ALG_TLS12_PSK_TO_MS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS()</span></code></a> key agreement algorithm.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]773<p>Quoting <span><em>Pre-Shared Key Ciphersuites for Transport Layer Security (TLS)</em> <a class="reference internal" href="../../about.html#citation-rfc4279"><span class="cite">[RFC4279]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-5.3">§5.3</a>:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]774<blockquote>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]775<div>TLS implementations supporting these cipher suites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.</div></blockquote>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]776<p>Therefore, it is recommended that implementations define <a class="reference internal" href="#c.PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE" title="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code></a> with a value greater than or equal to <code class="docutils literal"><span class="pre">64</span></code>.</p>
777</div>
778</div>
779</div>
780
781
782 </div>
783 </div>
784 </div>
785 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]786 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
787IHI 0086<br/>
788Non-confidential<br/>
789Version 1.0.1
790<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]791<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]792<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]793</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]794<ul class="current">
795<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
796<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
797<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
798<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
799<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
800<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
801<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
802<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
803<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
804<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
805<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
806<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
807<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
808<li class="toctree-l2"><a class="reference internal" href="ciphers.html">10.4. Unauthenticated ciphers</a></li>
809<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
810<li class="toctree-l2 current"><a class="current reference internal" href="#">10.6. Key derivation</a><ul>
811<li class="toctree-l3"><a class="reference internal" href="#key-derivation-algorithms">10.6.1. Key derivation algorithms</a></li>
812<li class="toctree-l3"><a class="reference internal" href="#input-step-types">10.6.2. Input step types</a></li>
813<li class="toctree-l3"><a class="reference internal" href="#key-derivation-functions">10.6.3. Key derivation functions</a></li>
814<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.6.4. Support macros</a></li>
815</ul>
816</li>
817<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
818<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
819<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
820<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
821</ul>
822</li>
823</ul>
824<ul>
825<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
826<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
827<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
828</ul>
829<ul>
830<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
831</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]832<div id="searchbox" style="display: none" role="search">
833 <h3>Quick search</h3>
834 <form class="search" action="../../search.html" method="get">
835 <div><input type="text" name="q" /></div>
836 <div><input type="submit" value="Go" /></div>
837 <input type="hidden" name="check_keywords" value="yes" />
838 <input type="hidden" name="area" value="default" />
839 </form>
840</div>
841<script type="text/javascript">$('#searchbox').show(0);</script>
842 </div>
843 </div>
844 <div class="clearer"></div>
845 </div>
846 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame^]847 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]848
849 |
850 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
851 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
852
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]853 </div>
854
855
856
857
858 </body>
859</html>