TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / 0f4df8f3e48921cf9577526366e94a6f0f3ec37c / . / docs / html / api / ops / kdf.html
blob: 0fa88a6b154bdc474d3204fe772c3e723aae69e7 [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" />
8 <title>Key derivation &#8212; PSA Crypto API 1.0.0 documentation</title>
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: '../../',
14 VERSION: '1.0.0',
15 COLLAPSE_INDEX: false,
16 FILE_SUFFIX: '.html',
17 HAS_SOURCE: true,
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>
24 <link rel="index" title="Index" href="../../genindex.html" />
25 <link rel="search" title="Search" href="../../search.html" />
26 <link rel="next" title="Asymmetric signature" href="sign.html" />
27 <link rel="prev" title="Authenticated encryption with associated data (AEAD)" href="aead.html" />
28
29 <link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
30
31 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
32
33 </head>
34 <body>
35
36
37 <div class="document">
38 <div class="documentwrapper">
39 <div class="bodywrapper">
40 <div class="body" role="main">
41
42 <div class="section" id="key-derivation">
43<span id="kdf"></span><h1>Key derivation</h1>
44<div class="section" id="key-derivation-algorithms">
45<span id="id1"></span><h2>Key derivation algorithms</h2>
46<div class="section" id="PSA_ALG_HKDF">
47<span id="c.PSA_ALG_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</h3>
48<p>Macro to build an HKDF algorithm.</p>
49<pre class="literal-block">
50#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>
51</pre>
52<p class="rubric">Parameters</p>
53<dl class="docutils">
54<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
55<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
56</dl>
57<p class="rubric">Returns</p>
58<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>
59<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
60<p class="rubric">Description</p>
61<p>This key derivation algorithm uses the following inputs:</p>
62<ul class="simple">
63<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>
64<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>
65<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>
66</ul>
67<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>
68</div>
69<div class="section" id="PSA_ALG_TLS12_PRF">
70<span id="c.PSA_ALG_TLS12_PRF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</h3>
71<p>Macro to build a TLS-1.2 PRF algorithm.</p>
72<pre class="literal-block">
73#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>
74</pre>
75<p class="rubric">Parameters</p>
76<dl class="docutils">
77<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
78<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
79</dl>
80<p class="rubric">Returns</p>
81<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>
82<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
83<p class="rubric">Description</p>
84<p>TLS 1.2 uses a custom pseudorandom function (PRF) for key schedule, specified in <a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">RFC 5246 §5</a>. It is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
85<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
86<ul class="simple">
87<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>
88<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>
89<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>
90</ul>
91<p>For the application to TLS-1.2 key expansion:</p>
92<ul class="simple">
93<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>
94<li>The label is <code class="docutils literal"><span class="pre">&quot;key</span> <span class="pre">expansion&quot;</span></code>.</li>
95</ul>
96</div>
97<div class="section" id="PSA_ALG_TLS12_PSK_TO_MS">
98<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>
99<p>Macro to build a TLS-1.2 PSK-to-MasterSecret algorithm.</p>
100<pre class="literal-block">
101#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>
102</pre>
103<p class="rubric">Parameters</p>
104<dl class="docutils">
105<dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt>
106<dd>A hash algorithm (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_HASH" title="PSA_ALG_IS_HASH"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">hash_alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
107</dl>
108<p class="rubric">Returns</p>
109<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>
110<p>Unspecified if <code class="docutils literal"><span class="pre">hash_alg</span></code> is not a supported hash algorithm.</p>
111<p class="rubric">Description</p>
112<p>In a pure-PSK handshake in TLS 1.2, the master secret (MS) is derived from the pre-shared key (PSK) through the application of padding (<a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-2">RFC 4279 §2</a>) and the TLS-1.2 PRF (<a class="reference external" href="https://tools.ietf.org/html/rfc5246.html#section-5">RFC 5246 §5</a>). The latter is based on HMAC and can be used with either SHA-256 or SHA-384.</p>
113<p>This key derivation algorithm uses the following inputs, which must be passed in the order given here:</p>
114<ul class="simple">
115<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>
116<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>
117<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>
118</ul>
119<p>For the application to TLS-1.2:</p>
120<ul class="simple">
121<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>
122<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>
123</ul>
124</div>
125</div>
126<div class="section" id="input-step-types">
127<h2>Input step types</h2>
128<div class="section" id="psa_key_derivation_step_t">
129<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>
130<p>Encoding of the step of a key derivation.</p>
131<pre class="literal-block">
132typedef 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>;
133</pre>
134</div>
135<div class="section" id="PSA_KEY_DERIVATION_INPUT_SECRET">
136<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>
137<p>A secret input for key derivation.</p>
138<pre class="literal-block">
139#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>
140</pre>
141<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>
142<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>
143</div>
144<div class="section" id="PSA_KEY_DERIVATION_INPUT_LABEL">
145<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>
146<p>A label for key derivation.</p>
147<pre class="literal-block">
148#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>
149</pre>
150<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>
151</div>
152<div class="section" id="PSA_KEY_DERIVATION_INPUT_CONTEXT">
153<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>
154<p>A context for key derivation.</p>
155<pre class="literal-block">
156#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>
157</pre>
158<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>
159</div>
160<div class="section" id="PSA_KEY_DERIVATION_INPUT_SALT">
161<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>
162<p>A salt for key derivation.</p>
163<pre class="literal-block">
164#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>
165</pre>
166<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>
167</div>
168<div class="section" id="PSA_KEY_DERIVATION_INPUT_INFO">
169<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>
170<p>An information string for key derivation.</p>
171<pre class="literal-block">
172#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>
173</pre>
174<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>
175</div>
176<div class="section" id="PSA_KEY_DERIVATION_INPUT_SEED">
177<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>
178<p>A seed for key derivation.</p>
179<pre class="literal-block">
180#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>
181</pre>
182<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>
183</div>
184</div>
185<div class="section" id="key-derivation-functions">
186<h2>Key derivation functions</h2>
187<div class="section" id="psa_key_derivation_operation_t">
188<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>
189<p>The type of the state object for key derivation operations.</p>
190<pre class="literal-block">
191typedef <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>;
192</pre>
193<p>Before calling any function on a key derivation operation object, the application must initialize it by any of the following means:</p>
194<ul>
195<li><p class="first">Set the object to all-bits-zero, for example:</p>
196<pre class="literal-block">
197<a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation;
198memset(&amp;operation, 0, sizeof(operation));
199</pre>
200</li>
201<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>
202<pre class="literal-block">
203static <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> operation;
204</pre>
205</li>
206<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>
207<pre class="literal-block">
208<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>;
209</pre>
210</li>
211<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>
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;
214operation = <a class="reference internal" href="#c.psa_key_derivation_operation_init" title="psa_key_derivation_operation_init">psa_key_derivation_operation_init</a>();
215</pre>
216</li>
217</ul>
218<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>
219</div>
220<div class="section" id="PSA_KEY_DERIVATION_OPERATION_INIT">
221<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>
222<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>
223<pre class="literal-block">
224#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>
225</pre>
226</div>
227<div class="section" id="psa_key_derivation_operation_init">
228<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>
229<p>Return an initial value for a key derivation operation object.</p>
230<pre class="literal-block">
231<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);
232</pre>
233<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>
234</div>
235<div class="section" id="psa_key_derivation_setup">
236<span id="c.psa_key_derivation_setup"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_setup</span></code> (function)</h3>
237<p>Set up a key derivation operation.</p>
238<pre class="literal-block">
239<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,
240 <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);
241</pre>
242<p class="rubric">Parameters</p>
243<dl class="docutils">
244<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
245<dd>The key derivation operation object to set up. It must have been initialized but not set up yet.</dd>
246<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
247<dd>The key derivation algorithm to compute (<code class="docutils literal"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="../keys/algorithms.html#c.PSA_ALG_IS_KEY_DERIVATION" title="PSA_ALG_IS_KEY_DERIVATION"><code class="docutils literal"><span class="pre">PSA_ALG_IS_KEY_DERIVATION</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true).</dd>
248</dl>
249<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>
250<dl class="docutils">
251<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>
252<dd>Success.</dd>
253<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>
254<dd><code class="docutils literal"><span class="pre">alg</span></code> is not a key derivation algorithm.</dd>
255<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>
256<dd><code class="docutils literal"><span class="pre">alg</span></code> is not supported or is not a key derivation algorithm.</dd>
257<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>
258<dd></dd>
259<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>
260<dd></dd>
261<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>
262<dd></dd>
263<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>
264<dd></dd>
265<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>
266<dd></dd>
267<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>
268<dd></dd>
269<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>
270<dd></dd>
271<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>
272<dd>The operation state is not valid: it must be inactive.</dd>
273<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>
274<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>
275</dl>
276<p class="rubric">Description</p>
277<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>
278<p>To derive a key:</p>
279<ol class="arabic simple">
280<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>
281<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>
282<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>
283<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>
284<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>
285<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>
286</ol>
287<p>If this function returns an error, the key derivation operation object is not changed.</p>
288<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>
289<p>Implementations must reject an attempt to derive a key of size <code class="docutils literal"><span class="pre">0</span></code>.</p>
290</div>
291<div class="section" id="psa_key_derivation_get_capacity">
292<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>
293<p>Retrieve the current capacity of a key derivation operation.</p>
294<pre class="literal-block">
295<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,
296 size_t * capacity);
297</pre>
298<p class="rubric">Parameters</p>
299<dl class="docutils">
300<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
301<dd>The operation to query.</dd>
302<dt> <code class="docutils literal"><span class="pre">capacity</span></code></dt>
303<dd>On success, the capacity of the operation.</dd>
304</dl>
305<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>
306<dl class="docutils">
307<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>
308<dd></dd>
309<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>
310<dd></dd>
311<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>
312<dd>The operation state is not valid: it must be active.</dd>
313<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>
314<dd></dd>
315<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>
316<dd></dd>
317<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>
318<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>
319</dl>
320<p class="rubric">Description</p>
321<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>
322<ul class="simple">
323<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>
324<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>
325</ul>
326</div>
327<div class="section" id="psa_key_derivation_set_capacity">
328<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>
329<p>Set the maximum capacity of a key derivation operation.</p>
330<pre class="literal-block">
331<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,
332 size_t capacity);
333</pre>
334<p class="rubric">Parameters</p>
335<dl class="docutils">
336<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
337<dd>The key derivation operation object to modify.</dd>
338<dt> <code class="docutils literal"><span class="pre">capacity</span></code></dt>
339<dd>The new capacity of the operation. It must be less or equal to the operation’s current capacity.</dd>
340</dl>
341<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>
342<dl class="docutils">
343<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>
344<dd></dd>
345<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>
346<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>
347<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>
348<dd>The operation state is not valid: it must be active.</dd>
349<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>
350<dd></dd>
351<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>
352<dd></dd>
353<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>
354<dd></dd>
355<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>
356<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>
357</dl>
358<p class="rubric">Description</p>
359<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>
360</div>
361<div class="section" id="psa_key_derivation_input_bytes">
362<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>
363<p>Provide an input for key derivation or key agreement.</p>
364<pre class="literal-block">
365<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,
366 <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
367 const uint8_t * data,
368 size_t data_length);
369</pre>
370<p class="rubric">Parameters</p>
371<dl class="docutils">
372<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
373<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>
374<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
375<dd>Which step the input data is for.</dd>
376<dt> <code class="docutils literal"><span class="pre">data</span></code></dt>
377<dd>Input data to use.</dd>
378<dt> <code class="docutils literal"><span class="pre">data_length</span></code></dt>
379<dd>Size of the <code class="docutils literal"><span class="pre">data</span></code> buffer in bytes.</dd>
380</dl>
381<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>
382<dl class="docutils">
383<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>
384<dd>Success.</dd>
385<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>
386<dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd>
387<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>
388<dd><code class="docutils literal"><span class="pre">step</span></code> does not allow direct inputs.</dd>
389<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>
390<dd></dd>
391<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>
392<dd></dd>
393<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>
394<dd></dd>
395<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>
396<dd></dd>
397<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>
398<dd></dd>
399<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>
400<dd></dd>
401<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>
402<dd></dd>
403<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>
404<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>.</dd>
405<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>
406<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>
407</dl>
408<p class="rubric">Description</p>
409<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>
410<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>
411<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>
412</div>
413<div class="section" id="psa_key_derivation_input_key">
414<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>
415<p>Provide an input for key derivation in the form of a key.</p>
416<pre class="literal-block">
417<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,
418 <a class="reference internal" href="#c.psa_key_derivation_step_t" title="psa_key_derivation_step_t">psa_key_derivation_step_t</a> step,
419 <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key);
420</pre>
421<p class="rubric">Parameters</p>
422<dl class="docutils">
423<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
424<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>
425<dt> <code class="docutils literal"><span class="pre">step</span></code></dt>
426<dd>Which step the input data is for.</dd>
427<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
428<dd>Identifier of the key. It must have an appropriate type for <code class="docutils literal"><span class="pre">step</span></code> and must allow the usage <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a>.</dd>
429</dl>
430<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>
431<dl class="docutils">
432<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>
433<dd>Success.</dd>
434<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>
435<dd></dd>
436<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>
437<dd>The key does not have the <a class="reference internal" href="../keys/usage.html#c.PSA_KEY_USAGE_DERIVE" title="PSA_KEY_USAGE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code></a> flag.</dd>
438<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>
439<dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd>
440<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>
441<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>
442<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>
443<dd></dd>
444<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>
445<dd></dd>
446<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>
447<dd></dd>
448<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>
449<dd></dd>
450<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>
451<dd></dd>
452<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>
453<dd></dd>
454<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>
455<dd></dd>
456<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>
457<dd>The operation state is not valid for this input <code class="docutils literal"><span class="pre">step</span></code>.</dd>
458<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>
459<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>
460</dl>
461<p class="rubric">Description</p>
462<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>
463<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>
464<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>
465</div>
466<div class="section" id="psa_key_derivation_output_bytes">
467<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>
468<p>Read some data from a key derivation operation.</p>
469<pre class="literal-block">
470<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,
471 uint8_t * output,
472 size_t output_length);
473</pre>
474<p class="rubric">Parameters</p>
475<dl class="docutils">
476<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
477<dd>The key derivation operation object to read from.</dd>
478<dt> <code class="docutils literal"><span class="pre">output</span></code></dt>
479<dd>Buffer where the output will be written.</dd>
480<dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt>
481<dd>Number of bytes to output.</dd>
482</dl>
483<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>
484<dl class="docutils">
485<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>
486<dd></dd>
487<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>
488<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>
489<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>
490<dd>The operation state is not valid: it must be active and completed all required input steps.</dd>
491<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>
492<dd></dd>
493<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>
494<dd></dd>
495<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>
496<dd></dd>
497<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>
498<dd></dd>
499<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>
500<dd></dd>
501<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>
502<dd></dd>
503<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>
504<dd></dd>
505<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>
506<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>
507</dl>
508<p class="rubric">Description</p>
509<p>This function calculates output bytes from a key derivation algorithm and return those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.</p>
510<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>
511</div>
512<div class="section" id="psa_key_derivation_output_key">
513<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>
514<p>Derive a key from an ongoing key derivation operation.</p>
515<pre class="literal-block">
516<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,
517 <a class="reference internal" href="#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t">psa_key_derivation_operation_t</a> * operation,
518 <a class="reference internal" href="../keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> * key);
519</pre>
520<p class="rubric">Parameters</p>
521<dl class="docutils">
522<dt> <code class="docutils literal"><span class="pre">attributes</span></code></dt>
523<dd>The attributes for the new key.</dd>
524<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
525<dd>The key derivation operation object to read from.</dd>
526<dt> <code class="docutils literal"><span class="pre">key</span></code></dt>
527<dd>On success, an identifier for the newly created key. <a class="reference internal" href="../keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a> on failure.</dd>
528</dl>
529<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>
530<dl class="docutils">
531<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>
532<dd>Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.</dd>
533<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>
534<dd>This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.</dd>
535<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>
536<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>
537<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>
538<dd>The key type or key size is not supported, either by the implementation in general or in this particular location.</dd>
539<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>
540<dd>The provided key attributes are not valid for the operation.</dd>
541<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>
542<dd>The <a class="reference internal" href="#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> input was not provided through a key.</dd>
543<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>
544<dd>The operation state is not valid: it must be active and completed all required input steps.</dd>
545<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>
546<dd></dd>
547<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>
548<dd></dd>
549<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>
550<dd></dd>
551<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>
552<dd></dd>
553<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>
554<dd></dd>
555<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>
556<dd></dd>
557<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>
558<dd></dd>
559<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>
560<dd></dd>
561<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>
562<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>
563</dl>
564<p class="rubric">Description</p>
565<p>This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, usage policy, type and size are taken from <code class="docutils literal"><span class="pre">attributes</span></code>.</p>
566<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>
567<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>
568<p>How much output is produced and consumed from the operation, and how the key is derived, depends on the key type:</p>
569<ul>
570<li><p class="first">For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling <a class="reference internal" href="#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> and passing the resulting output to <a class="reference internal" href="../keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>. However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly <code class="docutils literal"><span class="pre">(bits/8)</span></code> bytes from the operation. The following key types defined in this specification follow this scheme:</p>
571<ul class="simple">
572<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_AES</span></code></a>;</li>
573<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a>;</li>
574<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CAMELLIA" title="PSA_KEY_TYPE_CAMELLIA"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_CAMELLIA</span></code></a>;</li>
575<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DERIVE" title="PSA_KEY_TYPE_DERIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DERIVE</span></code></a>;</li>
576<li><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_HMAC" title="PSA_KEY_TYPE_HMAC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_HMAC</span></code></a>.</li>
577</ul>
578</li>
579<li><p class="first">For ECC keys on a Montgomery elliptic curve (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a><code class="docutils literal"><span class="pre">)</span></code>), this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:</p>
580<ul class="simple">
581<li>Curve25519 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 255 bits): draw a 32-byte string and process it as specified in <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">RFC 7748 §5</a>.</li>
582<li>Curve448 (<a class="reference internal" href="../keys/types.html#c.PSA_ECC_FAMILY_MONTGOMERY" title="PSA_ECC_FAMILY_MONTGOMERY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ECC_FAMILY_MONTGOMERY</span></code></a>, 448 bits): draw a 56-byte string and process it as specified in <a class="reference external" href="https://tools.ietf.org/html/rfc7748.html#section-5">RFC 7748 §5</a>.</li>
583</ul>
584</li>
585<li><p class="first">For key types for which the key is represented by a single sequence of <code class="docutils literal"><span class="pre">bits</span></code> bits with constraints as to which bit sequences are acceptable, this function draws a byte string of length <code class="docutils literal"><span class="pre">ceiling(bits/8)</span></code> bytes. If the resulting byte string is acceptable, it becomes the key, otherwise the drawn bytes are discarded. This process is repeated until an acceptable byte string is drawn. The byte string drawn from the operation is interpreted as specified for the output produced by <a class="reference internal" href="../keys/management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a>. The following key types defined in this specification follow this scheme:</p>
586<ul>
587<li><p class="first"><a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DES" title="PSA_KEY_TYPE_DES"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_DES</span></code></a>. Force-set the parity bits, but discard forbidden weak keys. For 2-key and 3-key triple-DES, the three keys are generated successively. For example, for 3-key triple-DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.</p>
588</li>
589<li><p class="first">Finite-field Diffie-Hellman keys (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_DH_KEY_PAIR" title="PSA_KEY_TYPE_DH_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_DH_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">dh_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">dh_family</span></code> designates any Diffie-Hellman family) and ECC keys on a Weierstrass elliptic curve (<a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ECC_KEY_PAIR" title="PSA_KEY_TYPE_ECC_KEY_PAIR"><code class="docutils literal"><span class="pre">PSA_KEY_TYPE_ECC_KEY_PAIR</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">ecc_family</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">ecc_family</span></code> designates a Weierstrass curve family). For these key types, interpret the byte string as integer in big-endian order. Discard it if it is not in the range [0, <em>N</em> - 2] where <em>N</em> is the boundary of the private key domain: <em>N</em> is the prime <em>p</em> for Diffie-Hellman, or the order of the curve’s base point for ECC. Add <code class="docutils literal"><span class="pre">1</span></code> to the resulting integer and use this as the private key <em>x</em>.</p>
590<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>
591<ul class="simple">
592<li><a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-56Ar3"><em>NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography</em></a> (NIST SP 800-56A) §5.6.1.1.4 for Diffie-Hellman keys.</li>
593<li><a class="reference external" href="https://doi.org/10.6028/NIST.SP.800-56Ar3">NIST SP 800-56A</a> §5.6.1.2.2 or <a class="reference external" href="https://doi.org/10.6028/NIST.FIPS.186-4"><em>FIPS Publication 186-4: Digital Signature Standard (DSS)</em></a> (FIPS 186-4) §B.4.2 for elliptic curve keys.</li>
594</ul>
595</li>
596</ul>
597</li>
598<li><p class="first">For other key types, including <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_RSA_KEY_PAIR" title="PSA_KEY_TYPE_RSA_KEY_PAIR"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_TYPE_RSA_KEY_PAIR</span></code></a>, the way in which the operation output is consumed is implementation-defined.</p>
599</li>
600</ul>
601<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>
602<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>
603</div>
604<div class="section" id="psa_key_derivation_abort">
605<span id="c.psa_key_derivation_abort"></span><h3><code class="docutils literal"><span class="pre">psa_key_derivation_abort</span></code> (function)</h3>
606<p>Abort a key derivation operation.</p>
607<pre class="literal-block">
608<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);
609</pre>
610<p class="rubric">Parameters</p>
611<dl class="docutils">
612<dt> <code class="docutils literal"><span class="pre">operation</span></code></dt>
613<dd>The operation to abort.</dd>
614</dl>
615<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>
616<dl class="docutils">
617<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>
618<dd></dd>
619<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>
620<dd></dd>
621<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>
622<dd></dd>
623<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>
624<dd></dd>
625<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>
626<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>
627</dl>
628<p class="rubric">Description</p>
629<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>
630<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>
631<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>
632</div>
633</div>
634<div class="section" id="support-macros">
635<h2>Support macros</h2>
636<div class="section" id="PSA_ALG_IS_HKDF">
637<span id="c.PSA_ALG_IS_HKDF"></span><h3><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</h3>
638<p>Whether the specified algorithm is an HKDF algorithm.</p>
639<pre class="literal-block">
640#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>
641</pre>
642<p class="rubric">Parameters</p>
643<dl class="docutils">
644<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
645<dd>An algorithm identifier (value of type <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
646</dl>
647<p class="rubric">Returns</p>
648<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>
649<p class="rubric">Description</p>
650<p>HKDF is a family of key derivation algorithms that are based on a hash function and the HMAC construction.</p>
651</div>
652<div class="section" id="PSA_ALG_IS_TLS12_PRF">
653<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>
654<p>Whether the specified algorithm is a TLS-1.2 PRF algorithm.</p>
655<pre class="literal-block">
656#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>
657</pre>
658<p class="rubric">Parameters</p>
659<dl class="docutils">
660<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
661<dd>An algorithm identifier (value of type <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
662</dl>
663<p class="rubric">Returns</p>
664<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>
665</div>
666<div class="section" id="PSA_ALG_IS_TLS12_PSK_TO_MS">
667<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>
668<p>Whether the specified algorithm is a TLS-1.2 PSK to MS algorithm.</p>
669<pre class="literal-block">
670#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>
671</pre>
672<p class="rubric">Parameters</p>
673<dl class="docutils">
674<dt> <code class="docutils literal"><span class="pre">alg</span></code></dt>
675<dd>An algorithm identifier (value of type <a class="reference internal" href="../keys/attributes.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_algorithm_t</span></code></a>).</dd>
676</dl>
677<p class="rubric">Returns</p>
678<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>
679</div>
680<div class="section" id="PSA_KEY_DERIVATION_UNLIMITED_CAPACITY">
681<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>
682<p>Use the maximum possible capacity for a key derivation operation.</p>
683<pre class="literal-block">
684#define <a class="reference internal" href="#c.PSA_KEY_DERIVATION_UNLIMITED_CAPACITY" title="PSA_KEY_DERIVATION_UNLIMITED_CAPACITY">PSA_KEY_DERIVATION_UNLIMITED_CAPACITY</a> \
685 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em>
686</pre>
687<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>
688</div>
689<div class="section" id="PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE">
690<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>
691<p>This macro returns the maximum supported length of the PSK for the TLS-1.2 PSK-to-MS key derivation.</p>
692<pre class="literal-block">
693#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>
694</pre>
695<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>
696<p>Quoting <a class="reference external" href="https://tools.ietf.org/html/rfc4279.html#section-5.3">RFC 4279 §5.3</a>:</p>
697<blockquote>
698<div>TLS implementations supporting these ciphersuites MUST support arbitrary PSK identities up to 128 octets in length, and arbitrary PSKs up to 64 octets in length. Supporting longer identities and keys is RECOMMENDED.</div></blockquote>
699<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>
700</div>
701</div>
702</div>
703
704
705 </div>
706 </div>
707 </div>
708 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
709 <div class="sphinxsidebarwrapper">
710 <h3><a href="../../index.html">Table Of Contents</a></h3>
711 <ul>
712<li><a class="reference internal" href="#">Key derivation</a><ul>
713<li><a class="reference internal" href="#key-derivation-algorithms">Key derivation algorithms</a><ul>
714<li><a class="reference internal" href="#PSA_ALG_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_HKDF</span></code> (macro)</a></li>
715<li><a class="reference internal" href="#PSA_ALG_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PRF</span></code> (macro)</a></li>
716<li><a class="reference internal" href="#PSA_ALG_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
717</ul>
718</li>
719<li><a class="reference internal" href="#input-step-types">Input step types</a><ul>
720<li><a class="reference internal" href="#psa_key_derivation_step_t"><code class="docutils literal"><span class="pre">psa_key_derivation_step_t</span></code> (type)</a></li>
721<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SECRET"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> (macro)</a></li>
722<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_LABEL"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_LABEL</span></code> (macro)</a></li>
723<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_CONTEXT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_CONTEXT</span></code> (macro)</a></li>
724<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SALT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SALT</span></code> (macro)</a></li>
725<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_INFO"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code> (macro)</a></li>
726<li><a class="reference internal" href="#PSA_KEY_DERIVATION_INPUT_SEED"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SEED</span></code> (macro)</a></li>
727</ul>
728</li>
729<li><a class="reference internal" href="#key-derivation-functions">Key derivation functions</a><ul>
730<li><a class="reference internal" href="#psa_key_derivation_operation_t"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code> (type)</a></li>
731<li><a class="reference internal" href="#PSA_KEY_DERIVATION_OPERATION_INIT"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code> (macro)</a></li>
732<li><a class="reference internal" href="#psa_key_derivation_operation_init"><code class="docutils literal"><span class="pre">psa_key_derivation_operation_init</span></code> (function)</a></li>
733<li><a class="reference internal" href="#psa_key_derivation_setup"><code class="docutils literal"><span class="pre">psa_key_derivation_setup</span></code> (function)</a></li>
734<li><a class="reference internal" href="#psa_key_derivation_get_capacity"><code class="docutils literal"><span class="pre">psa_key_derivation_get_capacity</span></code> (function)</a></li>
735<li><a class="reference internal" href="#psa_key_derivation_set_capacity"><code class="docutils literal"><span class="pre">psa_key_derivation_set_capacity</span></code> (function)</a></li>
736<li><a class="reference internal" href="#psa_key_derivation_input_bytes"><code class="docutils literal"><span class="pre">psa_key_derivation_input_bytes</span></code> (function)</a></li>
737<li><a class="reference internal" href="#psa_key_derivation_input_key"><code class="docutils literal"><span class="pre">psa_key_derivation_input_key</span></code> (function)</a></li>
738<li><a class="reference internal" href="#psa_key_derivation_output_bytes"><code class="docutils literal"><span class="pre">psa_key_derivation_output_bytes</span></code> (function)</a></li>
739<li><a class="reference internal" href="#psa_key_derivation_output_key"><code class="docutils literal"><span class="pre">psa_key_derivation_output_key</span></code> (function)</a></li>
740<li><a class="reference internal" href="#psa_key_derivation_abort"><code class="docutils literal"><span class="pre">psa_key_derivation_abort</span></code> (function)</a></li>
741</ul>
742</li>
743<li><a class="reference internal" href="#support-macros">Support macros</a><ul>
744<li><a class="reference internal" href="#PSA_ALG_IS_HKDF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_HKDF</span></code> (macro)</a></li>
745<li><a class="reference internal" href="#PSA_ALG_IS_TLS12_PRF"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PRF</span></code> (macro)</a></li>
746<li><a class="reference internal" href="#PSA_ALG_IS_TLS12_PSK_TO_MS"><code class="docutils literal"><span class="pre">PSA_ALG_IS_TLS12_PSK_TO_MS</span></code> (macro)</a></li>
747<li><a class="reference internal" href="#PSA_KEY_DERIVATION_UNLIMITED_CAPACITY"><code class="docutils literal"><span class="pre">PSA_KEY_DERIVATION_UNLIMITED_CAPACITY</span></code> (macro)</a></li>
748<li><a class="reference internal" href="#PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE"><code class="docutils literal"><span class="pre">PSA_TLS12_PSK_TO_MS_PSK_MAX_SIZE</span></code> (macro)</a></li>
749</ul>
750</li>
751</ul>
752</li>
753</ul>
754<div class="relations">
755<h3>Related Topics</h3>
756<ul>
757 <li><a href="../../index.html">Documentation overview</a><ul>
758 <li><a href="index.html">Cryptographic operation reference</a><ul>
759 <li>Previous: <a href="aead.html" title="previous chapter">Authenticated encryption with associated data (AEAD)</a></li>
760 <li>Next: <a href="sign.html" title="next chapter">Asymmetric signature</a></li>
761 </ul></li>
762 </ul></li>
763</ul>
764</div>
765 <div role="note" aria-label="source link">
766 <h3>This Page</h3>
767 <ul class="this-page-menu">
768 <li><a href="../../_sources/api/ops/kdf.rst.txt"
769 rel="nofollow">Show Source</a></li>
770 </ul>
771 </div>
772<div id="searchbox" style="display: none" role="search">
773 <h3>Quick search</h3>
774 <form class="search" action="../../search.html" method="get">
775 <div><input type="text" name="q" /></div>
776 <div><input type="submit" value="Go" /></div>
777 <input type="hidden" name="check_keywords" value="yes" />
778 <input type="hidden" name="area" value="default" />
779 </form>
780</div>
781<script type="text/javascript">$('#searchbox').show(0);</script>
782 </div>
783 </div>
784 <div class="clearer"></div>
785 </div>
786 <div class="footer">
787 &copy; 2019-2020, Arm Limited or its affiliates. All rights reserved.
788
789 |
790 Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a>
791 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a>
792
793 |
794 <a href="../../_sources/api/ops/kdf.rst.txt"
795 rel="nofollow">Page source</a>
796 </div>
797
798
799
800
801 </body>
802</html>