| |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" |
| "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> |
| <title>2. Password-authenticated key exchange (PAKE) — PSA Crypto API PAKE Extension 1.1 PAKE Extension.0-bet.0 documentation</title> |
| <link rel="stylesheet" href="_static/alabaster.css" type="text/css" /> |
| <link rel="stylesheet" href="_static/pygments.css" type="text/css" /> |
| <script type="text/javascript"> |
| var DOCUMENTATION_OPTIONS = { |
| URL_ROOT: './', |
| VERSION: '1.1 PAKE Extension.0-bet.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: false, |
| SOURCELINK_SUFFIX: '.txt' |
| }; |
| </script> |
| <script type="text/javascript" src="_static/jquery.js"></script> |
| <script type="text/javascript" src="_static/underscore.js"></script> |
| <script type="text/javascript" src="_static/doctools.js"></script> |
| <link rel="author" title="About these documents" href="about.html" /> |
| <link rel="index" title="Index" href="genindex.html" /> |
| <link rel="search" title="Search" href="search.html" /> |
| <link rel="next" title="Example header file" href="example_header.html" /> |
| <link rel="prev" title="1. Introduction" href="intro.html" /> |
| |
| <link rel="stylesheet" href="_static/custom.css" type="text/css" /> |
| |
| <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" /> |
| |
| </head> |
| <body> |
| |
| |
| <div class="document"> |
| <div class="documentwrapper"> |
| <div class="bodywrapper"> |
| <div class="body" role="main"> |
| |
| <div class="section" id="password-authenticated-key-exchange-pake"> |
| <h1>2. Password-authenticated key exchange (PAKE)</h1> |
| <p>This is a proposed PAKE interface for <span><em>PSA Cryptography API</em> <a class="reference internal" href="about.html#citation-psa-crypt"><span class="cite">[PSA-CRYPT]</span></a></span>. |
| It is not part of the official PSA Cryptography API yet.</p> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p class="last">The content of this specification is not part of the stable PSA Cryptography API and may change substantially from version to version.</p> |
| </div> |
| <div class="section" id="algorithm-encoding"> |
| <h2>2.1. Algorithm encoding</h2> |
| <p>A new algorithm category is added for PAKE algorithms. The algorithm category table in <a class="reference internal" href="about.html#citation-psa-crypt"><span class="cite psa_c psa_c-cite">[PSA-CRYPT]</span></a> Appendix B is extended with the information in <span><a class="reference internal" href="#table-pake-algorithm-category"><span class="numref">Table 1</span></a></span>.</p> |
| <table border="1" class="colwidths-auto docutils align-left" id="table-pake-algorithm-category"> |
| <caption><span class="caption-number">Table 1 </span><span class="caption-text">New algorithm identifier categories</span></caption> |
| <thead valign="bottom"> |
| <tr class="row-odd"><th class="head">Algorithm category</th> |
| <th class="head">CAT</th> |
| <th class="head">Category details</th> |
| </tr> |
| </thead> |
| <tbody valign="top"> |
| <tr class="row-even"><td>PAKE</td> |
| <td><code class="docutils literal"><span class="pre">0x0A</span></code></td> |
| <td>See <a class="reference internal" href="#pake-encoding"><span class="secref">PAKE algorithm encoding</span></a></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="section" id="pake-algorithm-encoding"> |
| <span id="pake-encoding"></span><h3>2.1.1. PAKE algorithm encoding</h3> |
| <p>The algorithm identifier for PAKE algorithms defined in this specification are encoded as shown in <span><a class="reference internal" href="#fig-pake-encoding"><span class="numref">Figure 1</span></a></span>.</p> |
| <div class="figure" id="fig-pake-encoding"> |
| <img alt="_images/pake_encoding.svg" src="_images/pake_encoding.svg" /><p class="caption"><span class="caption-number">Figure 1 </span><span class="caption-text">PAKE algorithm encoding</span></p> |
| </div> |
| <p>The defined values for PAKE-TYPE are shown in <span><a class="reference internal" href="#table-pake-type"><span class="numref">Table 2</span></a></span>.</p> |
| <table border="1" class="colwidths-auto docutils align-left" id="table-pake-type"> |
| <caption><span class="caption-number">Table 2 </span><span class="caption-text">PAKE algorithm sub-type values</span></caption> |
| <thead valign="bottom"> |
| <tr class="row-odd"><th class="head">PAKE algorithm</th> |
| <th class="head">PAKE-TYPE</th> |
| <th class="head">Algorithm identifier</th> |
| <th class="head">Algorithm value</th> |
| </tr> |
| </thead> |
| <tbody valign="top"> |
| <tr class="row-even"><td>J-PAKE</td> |
| <td><code class="docutils literal"><span class="pre">0x01</span></code></td> |
| <td><a class="reference internal" href="#c.PSA_ALG_JPAKE" title="PSA_ALG_JPAKE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_JPAKE</span></code></a></td> |
| <td><code class="docutils literal"><span class="pre">0x0A000100</span></code></td> |
| </tr> |
| </tbody> |
| </table> |
| </div> |
| </div> |
| <div class="section" id="changes-and-additions-to-the-programming-api"> |
| <h2>2.2. Changes and additions to the Programming API</h2> |
| <div class="section" id="pake-algorithms"> |
| <span id="id1"></span><h3>2.2.1. PAKE algorithms</h3> |
| <div class="section" id="PSA_ALG_IS_PAKE"> |
| <span id="c.PSA_ALG_IS_PAKE"></span><h4><code class="docutils literal"><span class="pre">PSA_ALG_IS_PAKE</span></code> (macro)</h4> |
| <p>Whether the specified algorithm is a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_IS_PAKE" title="PSA_ALG_IS_PAKE">PSA_ALG_IS_PAKE</a>(alg) <em><a class="reference internal" href="specdef_values.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>An algorithm identifier: a value of type <code class="xref any docutils literal"><span class="pre">psa_algorithm_t</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p><code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is a password-authenticated key exchange (PAKE) algorithm, <code class="docutils literal"><span class="pre">0</span></code> otherwise. |
| This macro can return either <code class="docutils literal"><span class="pre">0</span></code> or <code class="docutils literal"><span class="pre">1</span></code> if <code class="docutils literal"><span class="pre">alg</span></code> is not a supported algorithm identifier.</p> |
| </div> |
| <div class="section" id="PSA_ALG_JPAKE"> |
| <span id="c.PSA_ALG_JPAKE"></span><h4><code class="docutils literal"><span class="pre">PSA_ALG_JPAKE</span></code> (macro)</h4> |
| <p>The Password-authenticated key exchange by juggling (J-PAKE) algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_ALG_JPAKE" title="PSA_ALG_JPAKE">PSA_ALG_JPAKE</a> ((psa_algorithm_t)0x0a000100) |
| </pre> |
| <p>This is J-PAKE as defined by <span><em>J-PAKE: Password-Authenticated Key Exchange by Juggling</em> <a class="reference internal" href="about.html#citation-rfc8236"><span class="cite">[RFC8236]</span></a></span>, instantiated with the following parameters:</p> |
| <ul class="simple"> |
| <li>The group can be either an elliptic curve or defined over a finite field.</li> |
| <li>Schnorr NIZK proof as defined by <span><em>Schnorr Non-interactive Zero-Knowledge Proof</em> <a class="reference internal" href="about.html#citation-rfc8235"><span class="cite">[RFC8235]</span></a></span>, using the same group as the J-PAKE algorithm.</li> |
| <li>A cryptographic hash function.</li> |
| </ul> |
| <p>To select these parameters and set up the cipher suite, initialize a <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code></a> object, and call the following functions in any order:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> cipher_suite = <a class="reference internal" href="#c.PSA_PAKE_CIPHER_SUITE_INIT" title="PSA_PAKE_CIPHER_SUITE_INIT">PSA_PAKE_CIPHER_SUITE_INIT</a>; |
| |
| <a class="reference internal" href="#c.psa_pake_cs_set_algorithm" title="psa_pake_cs_set_algorithm">psa_pake_cs_set_algorithm</a>(cipher_suite, <a class="reference internal" href="#c.PSA_ALG_JPAKE" title="PSA_ALG_JPAKE">PSA_ALG_JPAKE</a>); |
| <a class="reference internal" href="#c.psa_pake_cs_set_primitive" title="psa_pake_cs_set_primitive">psa_pake_cs_set_primitive</a>(cipher_suite, |
| <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE">PSA_PAKE_PRIMITIVE</a>(type, family, bits)); |
| <a class="reference internal" href="#c.psa_pake_cs_set_hash" title="psa_pake_cs_set_hash">psa_pake_cs_set_hash</a>(cipher_suite, hash); |
| </pre> |
| <p>More information on selecting a specific Elliptic curve or Diffie-Hellman field is provided with the <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE_TYPE_ECC" title="PSA_PAKE_PRIMITIVE_TYPE_ECC"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_ECC</span></code></a> and <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE_TYPE_DH" title="PSA_PAKE_PRIMITIVE_TYPE_DH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_DH</span></code></a> constants.</p> |
| <p>The J-PAKE operation follows the protocol shown in <span><a class="reference internal" href="#fig-jpake"><span class="numref">Figure 2</span></a></span>.</p> |
| <div class="figure" id="fig-jpake"> |
| <img alt="_images/j-pake.svg" src="_images/j-pake.svg" /><p class="caption"><span class="caption-number">Figure 2 </span><span class="caption-text">The J-PAKE protocol.</span></p> |
| <div class="legend"> |
| The variable names <em>x1</em>, <em>g1</em>, and so on, are taken from the finite field implementation of J-PAKE in <a class="reference internal" href="about.html#citation-rfc8236"><span class="cite">[RFC8236]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8236.html#section-2">§2</a>. Details of the computation for the key shares and zero-knowledge proofs are in <a class="reference internal" href="about.html#citation-rfc8236"><span class="cite">[RFC8236]</span></a> and <a class="reference internal" href="about.html#citation-rfc8235"><span class="cite">[RFC8235]</span></a>.</div> |
| </div> |
| <p>J-PAKE does not assign roles to the participants, so it is not necessary to call <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a>.</p> |
| <p>J-PAKE requires both an application and a peer identity. If the peer identity provided to <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_peer()</span></code></a> does not match the data received from the peer, then the call to <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a> for the <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_STEP_ZK_PROOF</span></code></a> step will fail with <code class="xref any docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code>.</p> |
| <p>The following steps demonstrate the application code for ‘User’ in <span><a class="reference internal" href="#fig-jpake"><span class="numref">Figure 2</span></a></span>. |
| The input and output steps must be carried out in exactly the same sequence as shown.</p> |
| <ol class="arabic"> |
| <li><p class="first">To prepare a J-Pake operation, initialize and set up a <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_operation_t</span></code></a> object by calling the following functions:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> jpake = <a class="reference internal" href="#c.PSA_PAKE_OPERATION_INIT" title="PSA_PAKE_OPERATION_INIT">PSA_PAKE_OPERATION_INIT</a>; |
| |
| <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup">psa_pake_setup</a>(&jpake, &cipher_suite); |
| <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user">psa_pake_set_user</a>(&jpake, ...); |
| <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer">psa_pake_set_peer</a>(&jpake, ...); |
| <a class="reference internal" href="#c.psa_pake_set_password_key" title="psa_pake_set_password_key">psa_pake_set_password_key</a>(&jpake, ...); |
| </pre> |
| <p>The password is provided as a key. |
| This can be the password text itself, in an agreed character encoding, or some value derived from the password as required by a higher level protocol.</p> |
| <p>The key material is used as an array of bytes, which is converted to an integer as described in <span><em>SEC 1: Elliptic Curve Cryptography</em> <a class="reference internal" href="about.html#citation-sec1"><span class="cite">[SEC1]</span></a></span> §2.3.8, before reducing it modulo <em>q</em>. |
| Here, <em>q</em> is the order of the group defined by the cipher-suite primitive. |
| <a class="reference internal" href="#c.psa_pake_set_password_key" title="psa_pake_set_password_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_password_key()</span></code></a> will return an error if the result of the conversion and reduction is <code class="docutils literal"><span class="pre">0</span></code>.</p> |
| </li> |
| </ol> |
| <p>After setup, the key exchange flow for J-PAKE is as follows:</p> |
| <ol class="arabic" start="2"> |
| <li><p class="first">To get the first round data that needs to be sent to the peer, call:</p> |
| <pre class="literal-block"> |
| // Get g1 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Get V1, the ZKP public key for x1 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Get r1, the ZKP proof for x1 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| // Get g2 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Get V2, the ZKP public key for x2 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Get r2, the ZKP proof for x2 |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| </pre> |
| </li> |
| <li><p class="first">To provide the first round data received from the peer to the operation, call:</p> |
| <pre class="literal-block"> |
| // Set g3 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Set V3, the ZKP public key for x3 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Set r3, the ZKP proof for x3 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| // Set g4 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Set V4, the ZKP public key for x4 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Set r4, the ZKP proof for x4 |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| </pre> |
| </li> |
| <li><p class="first">To get the second round data that needs to be sent to the peer, call:</p> |
| <pre class="literal-block"> |
| // Get A |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Get V5, the ZKP public key for x2*s |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Get r5, the ZKP proof for x2*s |
| <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| </pre> |
| </li> |
| <li><p class="first">To provide the second round data received from the peer to the operation call:</p> |
| <pre class="literal-block"> |
| // Set B |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a>, ...); |
| // Set V6, the ZKP public key for x4*s |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a>, ...); |
| // Set r6, the ZKP proof for x4*s |
| <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(&jpake, <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a>, ...); |
| </pre> |
| </li> |
| <li><p class="first">To use the shared secret, set up a key derivation operation and transfer the computed value:</p> |
| <pre class="literal-block"> |
| // Set up the KDF |
| psa_key_derivation_operation_t kdf = PSA_KEY_DERIVATION_OPERATION_INIT; |
| psa_key_derivation_setup(&kdf, ...); |
| psa_key_derivation_input_bytes(&kdf, PSA_KEY_DERIVATION_INPUT_CONTEXT, ...); |
| psa_key_derivation_input_bytes(&kdf, PSA_KEY_DERIVATION_INPUT_LABEL, ...); |
| |
| // Get Ka=Kb=K |
| <a class="reference internal" href="#c.psa_pake_get_implicit_key" title="psa_pake_get_implicit_key">psa_pake_get_implicit_key</a>(&jpake, &kdf) |
| </pre> |
| </li> |
| </ol> |
| <p>For more information about the format of the values which are passed for each step, see <a class="reference internal" href="#pake-steps"><span class="secref">PAKE step types</span></a>.</p> |
| <p>If the verification of a Zero-knowledge proof provided by the peer fails, then the corresponding call to <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a> for the <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_STEP_ZK_PROOF</span></code></a> step will return <code class="xref any docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code>.</p> |
| <div class="admonition warning"> |
| <p class="first admonition-title">Warning</p> |
| <p>At the end of this sequence there is a cryptographic guarantee that only a peer that used the same password is able to compute the same key. |
| But there is no guarantee that the peer is the participant it claims to be, or that the peer used the same password during the exchange.</p> |
| <p>At this point, authentication is implicit — material encrypted or authenticated using the computed key can only be decrypted or verified by someone with the same key. |
| The peer is not authenticated at this point, and no action should be taken by the application which assumes that the peer is authenticated, for example, by accessing restricted files.</p> |
| <p class="last">To make the authentication explicit, there are various methods to confirm that both parties have the same key. See <a class="reference internal" href="about.html#citation-rfc8236"><span class="cite">[RFC8236]</span></a> <a class="reference external" href="https://tools.ietf.org/html/rfc8236.html#section-5">§5</a> for two examples.</p> |
| </div> |
| <p class="rubric">Compatible key types</p> |
| <div class="line-block"> |
| <div class="line"><code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD</span></code></div> |
| <div class="line"><code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD_HASH</span></code></div> |
| </div> |
| </div> |
| </div> |
| <div class="section" id="pake-primitives"> |
| <span id="pake-primitive"></span><h3>2.2.2. PAKE primitives</h3> |
| <p>A PAKE algorithm specifies a sequence of interactions between the participants. |
| Many PAKE algorithms are designed to allow different cryptographic primitives to be used for the key establishment operation, so long as all the participants are using the same underlying cryptography.</p> |
| <p>The cryptographic primitive for a PAKE operation is specified using a <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a> value, which can be constructed using the <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a> macro, or can be provided as a numerical constant value.</p> |
| <p>A PAKE primitive is required when constructing a PAKE cipher-suite object, <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code></a>, which fully specifies the PAKE operation to be carried out.</p> |
| <div class="section" id="psa_pake_primitive_type_t"> |
| <span id="c.psa_pake_primitive_type_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_primitive_type_t</span></code> (type)</h4> |
| <p>Encoding of the type of the PAKE’s primitive.</p> |
| <pre class="literal-block"> |
| typedef uint8_t <a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t">psa_pake_primitive_type_t</a>; |
| </pre> |
| <p>The range of PAKE primitive type values is divided as follows:</p> |
| <dl class="docutils"> |
| <dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x00</span></code></dt> |
| <dd>Reserved as an invalid primitive type.</dd> |
| <dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x01</span></code><code class="docutils literal"> <span class="pre">–</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">x7f</span></code></dt> |
| <dd>Specification-defined primitive type. |
| Primitive types defined by this standard always have bit 7 clear. |
| Unallocated primitive type values in this range are reserved for future use.</dd> |
| <dt><code class="docutils literal"><span class="pre">0</span></code><code class="docutils literal"><span class="pre">x80</span></code><code class="docutils literal"> <span class="pre">–</span> <span class="pre">0</span></code><code class="docutils literal"><span class="pre">xff</span></code></dt> |
| <dd>Implementation-defined primitive type. |
| Implementations that define additional primitive types must use an encoding with bit 7 set.</dd> |
| </dl> |
| <p>For specification-defined primitive types, see the documentation of individual <code class="docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_XXX</span></code> constants.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_PRIMITIVE_TYPE_ECC"> |
| <span id="c.PSA_PAKE_PRIMITIVE_TYPE_ECC"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_ECC</span></code> (macro)</h4> |
| <p>The PAKE primitive type indicating the use of elliptic curves.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE_TYPE_ECC" title="PSA_PAKE_PRIMITIVE_TYPE_ECC">PSA_PAKE_PRIMITIVE_TYPE_ECC</a> ((<a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t">psa_pake_primitive_type_t</a>)0x01) |
| </pre> |
| <p>The values of the <code class="docutils literal"><span class="pre">family</span></code> and <code class="docutils literal"><span class="pre">bits</span></code> components of the PAKE primitive identify a specific elliptic curve, using the same mapping that is used for ECC keys. |
| See the definition of <code class="docutils literal"><span class="pre">psa_ecc_family_t</span></code>. |
| Here <code class="docutils literal"><span class="pre">family</span></code> and <code class="docutils literal"><span class="pre">bits</span></code> refer to the values used to construct the PAKE primitive using <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| <p>Input and output during the operation can involve group elements and scalar values:</p> |
| <ul class="simple"> |
| <li>The format for group elements is the same as that for public keys on the specific Elliptic curve. |
| For more information, consult the documentation of <code class="xref any docutils literal"><span class="pre">psa_export_public_key()</span></code>.</li> |
| <li>The format for scalars is the same as that for private keys on the specific Elliptic curve. |
| For more information, consult the documentation of <code class="xref any docutils literal"><span class="pre">psa_export_key()</span></code>.</li> |
| </ul> |
| </div> |
| <div class="section" id="PSA_PAKE_PRIMITIVE_TYPE_DH"> |
| <span id="c.PSA_PAKE_PRIMITIVE_TYPE_DH"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_DH</span></code> (macro)</h4> |
| <p>The PAKE primitive type indicating the use of Diffie-Hellman groups.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE_TYPE_DH" title="PSA_PAKE_PRIMITIVE_TYPE_DH">PSA_PAKE_PRIMITIVE_TYPE_DH</a> ((<a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t">psa_pake_primitive_type_t</a>)0x02) |
| </pre> |
| <p>The values of the <code class="docutils literal"><span class="pre">family</span></code> and <code class="docutils literal"><span class="pre">bits</span></code> components of the PAKE primitive identify a specific Diffie-Hellman group, using the same mapping that is used for Diffie-Hellman keys. |
| See the definition of <code class="docutils literal"><span class="pre">psa_dh_family_t</span></code>. |
| Here <code class="docutils literal"><span class="pre">family</span></code> and <code class="docutils literal"><span class="pre">bits</span></code> refer to the values used to construct the PAKE primitive using <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| <p>Input and output during the operation can involve group elements and scalar values:</p> |
| <ul class="simple"> |
| <li>The format for group elements is the same as that for public keys in the specific Diffie-Hellman group. |
| For more information, consult the documentation of <code class="xref any docutils literal"><span class="pre">psa_export_public_key()</span></code>.</li> |
| <li>The format for scalars is the same as that for private keys in the specific Diffie-Hellman group. |
| For more information, consult the documentation of <code class="xref any docutils literal"><span class="pre">psa_export_key()</span></code>.</li> |
| </ul> |
| </div> |
| <div class="section" id="psa_pake_family_t"> |
| <span id="c.psa_pake_family_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_family_t</span></code> (type)</h4> |
| <p>Encoding of the family of the primitive associated with the PAKE.</p> |
| <pre class="literal-block"> |
| typedef uint8_t <a class="reference internal" href="#c.psa_pake_family_t" title="psa_pake_family_t">psa_pake_family_t</a>; |
| </pre> |
| <p>For more information see the documentation of individual <code class="docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE_TYPE_XXX</span></code> constants.</p> |
| </div> |
| <div class="section" id="psa_pake_primitive_t"> |
| <span id="c.psa_pake_primitive_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_primitive_t</span></code> (type)</h4> |
| <p>Encoding of the primitive associated with the PAKE.</p> |
| <pre class="literal-block"> |
| typedef uint32_t <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t">psa_pake_primitive_t</a>; |
| </pre> |
| <p>PAKE primitive values are constructed using <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| <div class="rationale admonition docutils container"> |
| <p class="admonition-title"><strong>Rationale</strong></p> |
| <p>An integral type is required for <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a> to enable values of this type to be compile-time-constants. This allows them to be used in <code class="docutils literal"><span class="pre">case</span></code> statements, and used to calculate static buffer sizes with <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_SIZE" title="PSA_PAKE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_SIZE()</span></code></a> and <a class="reference internal" href="#c.PSA_PAKE_INPUT_SIZE" title="PSA_PAKE_INPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_INPUT_SIZE()</span></code></a>.</p> |
| </div> |
| </div> |
| <div class="section" id="PSA_PAKE_PRIMITIVE"> |
| <span id="c.PSA_PAKE_PRIMITIVE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE</span></code> (macro)</h4> |
| <p>Construct a PAKE primitive from type, family and bit-size.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE">PSA_PAKE_PRIMITIVE</a>(pake_type, pake_family, pake_bits) \ |
| <em><a class="reference internal" href="specdef_values.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">pake_type</span></code></dt> |
| <dd>The type of the primitive: a value of type <a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_type_t</span></code></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">pake_family</span></code></dt> |
| <dd>The family of the primitive. |
| The type and interpretation of this parameter depends on <code class="docutils literal"><span class="pre">pake_type</span></code>. |
| For more information, consult the documentation of individual <a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_type_t</span></code></a> constants.</dd> |
| <dt> <code class="docutils literal"><span class="pre">pake_bits</span></code></dt> |
| <dd>The bit-size of the primitive: a value of type <code class="docutils literal"><span class="pre">size_t</span></code>. |
| The interpretation of this parameter depends on <code class="docutils literal"><span class="pre">family</span></code>. |
| For more information, consult the documentation of individual <a class="reference internal" href="#c.psa_pake_primitive_type_t" title="psa_pake_primitive_type_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_type_t</span></code></a> constants.</dd> |
| </dl> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a></p> |
| <p>The constructed primitive value. |
| Return <code class="docutils literal"><span class="pre">0</span></code> if the requested primitive can’t be encoded as <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a>.</p> |
| </div> |
| </div> |
| <div class="section" id="pake-cipher-suites"> |
| <span id="pake-cipher-suite"></span><h3>2.2.3. PAKE cipher suites</h3> |
| <p>A PAKE algorithm uses a specific cryptographic primitive for key establishment, specified using a <a class="reference internal" href="#pake-primitive"><span class="std std-ref">PAKE primitive</span></a>. PAKE algorithms also require a cryptographic hash algorithm, which is agreed between the participants.</p> |
| <p>The <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code></a> object is used to fully specify a PAKE operation, combining the PAKE algorithm, the PAKE primitive, the hash or any other algorithm that parametrises the PAKE in question.</p> |
| <p>A PAKE cipher suite is required when setting up a PAKE operation in <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_setup()</span></code></a>.</p> |
| <div class="section" id="psa_pake_cipher_suite_t"> |
| <span id="c.psa_pake_cipher_suite_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code> (type)</h4> |
| <p>The type of an object describing a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| typedef <em>/* implementation-defined type */</em> <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>; |
| </pre> |
| <p>This is the object that represents the cipher suite used for a PAKE algorithm. The PAKE cipher suite specifies the PAKE algorithm, and the options selected for that algorithm. The cipher suite includes the following attributes:</p> |
| <ul class="simple"> |
| <li>The PAKE algorithm itself.</li> |
| <li>The PAKE primitive, which identifies the prime order group used for the key exchange operation. See <a class="reference internal" href="#pake-primitive"><span class="secref">PAKE primitives</span></a>.</li> |
| <li>The hash algorithm to use in the operation.</li> |
| </ul> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p>Implementations are recommended to define the cipher-suite object as a simple data structure, with fields corresponding to the individual cipher suite attributes. In such an implementation, each function <code class="docutils literal"><span class="pre">psa_pake_cs_set_xxx()</span></code> sets a field and the corresponding function <code class="docutils literal"><span class="pre">psa_pake_cs_get_xxx()</span></code> retrieves the value of the field.</p> |
| <p class="last">An implementations can report attribute values that are equivalent to the original one, but have a different encoding. For example, an implementation can use a more compact representation for attributes where many bit-patterns are invalid or not supported, and store all values that it does not support as a special marker value. In such an implementation, after setting an invalid value, the corresponding get function returns an invalid value which might not be the one that was originally stored.</p> |
| </div> |
| <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> |
| <p>Before calling any function on a PAKE cipher suite object, the application must initialize it by any of the following means:</p> |
| <ul> |
| <li><p class="first">Set the object to all-bits-zero, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> cipher_suite; |
| memset(&cipher_suite, 0, sizeof(cipher_suite)); |
| </pre> |
| </li> |
| <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> |
| <pre class="literal-block"> |
| static <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> cipher_suite; |
| </pre> |
| </li> |
| <li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_PAKE_CIPHER_SUITE_INIT" title="PSA_PAKE_CIPHER_SUITE_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_CIPHER_SUITE_INIT</span></code></a>, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> cipher_suite = <a class="reference internal" href="#c.PSA_PAKE_CIPHER_SUITE_INIT" title="PSA_PAKE_CIPHER_SUITE_INIT">PSA_PAKE_CIPHER_SUITE_INIT</a>; |
| </pre> |
| </li> |
| <li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_pake_cipher_suite_init" title="psa_pake_cipher_suite_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_cipher_suite_init()</span></code></a> to the object, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> cipher_suite; |
| cipher_suite = <a class="reference internal" href="#c.psa_pake_cipher_suite_init" title="psa_pake_cipher_suite_init">psa_pake_cipher_suite_init</a>(); |
| </pre> |
| </li> |
| </ul> |
| </div> |
| <div class="section" id="PSA_PAKE_CIPHER_SUITE_INIT"> |
| <span id="c.PSA_PAKE_CIPHER_SUITE_INIT"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_CIPHER_SUITE_INIT</span></code> (macro)</h4> |
| <p>This macro returns a suitable initializer for a PAKE cipher suite object of type <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_CIPHER_SUITE_INIT" title="PSA_PAKE_CIPHER_SUITE_INIT">PSA_PAKE_CIPHER_SUITE_INIT</a> <em>/* implementation-defined value */</em> |
| </pre> |
| </div> |
| <div class="section" id="psa_pake_cipher_suite_init"> |
| <span id="c.psa_pake_cipher_suite_init"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cipher_suite_init</span></code> (function)</h4> |
| <p>Return an initial value for a PAKE cipher suite object.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> <a class="reference internal" href="#c.psa_pake_cipher_suite_init" title="psa_pake_cipher_suite_init">psa_pake_cipher_suite_init</a>(void); |
| </pre> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t"><code class="docutils literal"><span class="pre">psa_pake_cipher_suite_t</span></code></a></p> |
| </div> |
| <div class="section" id="psa_pake_cs_get_algorithm"> |
| <span id="c.psa_pake_cs_get_algorithm"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_get_algorithm</span></code> (function)</h4> |
| <p>Retrieve the PAKE algorithm from a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| psa_algorithm_t <a class="reference internal" href="#c.psa_pake_cs_get_algorithm" title="psa_pake_cs_get_algorithm">psa_pake_cs_get_algorithm</a>(const <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to query.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_algorithm_t</span></code></p> |
| <p>The PAKE algorithm stored in the cipher suite object.</p> |
| <p class="rubric">Description</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_pake_cs_set_algorithm"> |
| <span id="c.psa_pake_cs_set_algorithm"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_set_algorithm</span></code> (function)</h4> |
| <p>Declare the PAKE algorithm for the cipher suite.</p> |
| <pre class="literal-block"> |
| void <a class="reference internal" href="#c.psa_pake_cs_set_algorithm" title="psa_pake_cs_set_algorithm">psa_pake_cs_set_algorithm</a>(<a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite, |
| psa_algorithm_t alg); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to write to.</dd> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>The PAKE algorithm to write: a value of type <code class="xref any docutils literal"><span class="pre">psa_algorithm_t</span></code> such that <a class="reference internal" href="#c.PSA_ALG_IS_PAKE" title="PSA_ALG_IS_PAKE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_PAKE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p> |
| <p class="rubric">Description</p> |
| <p>This function overwrites any PAKE algorithm previously set in <code class="docutils literal"><span class="pre">cipher_suite</span></code>.</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_pake_cs_get_primitive"> |
| <span id="c.psa_pake_cs_get_primitive"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_get_primitive</span></code> (function)</h4> |
| <p>Retrieve the primitive from a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t">psa_pake_primitive_t</a> <a class="reference internal" href="#c.psa_pake_cs_get_primitive" title="psa_pake_cs_get_primitive">psa_pake_cs_get_primitive</a>(const <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to query.</dd> |
| </dl> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a></p> |
| <p>The primitive stored in the cipher suite object.</p> |
| <p class="rubric">Description</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_pake_cs_set_primitive"> |
| <span id="c.psa_pake_cs_set_primitive"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_set_primitive</span></code> (function)</h4> |
| <p>Declare the primitive for a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| void <a class="reference internal" href="#c.psa_pake_cs_set_primitive" title="psa_pake_cs_set_primitive">psa_pake_cs_set_primitive</a>(<a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite, |
| <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t">psa_pake_primitive_t</a> primitive); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to write to.</dd> |
| <dt> <code class="docutils literal"><span class="pre">primitive</span></code></dt> |
| <dd>The PAKE primitive to write: a value of type <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a>. |
| If this is <code class="docutils literal"><span class="pre">0</span></code>, the primitive type in <code class="docutils literal"><span class="pre">cipher_suite</span></code> becomes unspecified.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p> |
| <p class="rubric">Description</p> |
| <p>This function overwrites any primitive previously set in <code class="docutils literal"><span class="pre">cipher_suite</span></code>.</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_pake_cs_get_hash"> |
| <span id="c.psa_pake_cs_get_hash"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_get_hash</span></code> (function)</h4> |
| <p>Retrieve the hash algorithm from a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t">psa_pake_primitive_t</a> <a class="reference internal" href="#c.psa_pake_cs_get_hash" title="psa_pake_cs_get_hash">psa_pake_cs_get_hash</a>(const <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to query.</dd> |
| </dl> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a></p> |
| <p>The hash algorithm stored in the cipher suite object. |
| The return value is <code class="xref any docutils literal"><span class="pre">PSA_ALG_NONE</span></code> if the PAKE is not parametrized by a hash algorithm, or if the hash algorithm is not set.</p> |
| <p class="rubric">Description</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| <div class="section" id="psa_pake_cs_set_hash"> |
| <span id="c.psa_pake_cs_set_hash"></span><h4><code class="docutils literal"><span class="pre">psa_pake_cs_set_hash</span></code> (function)</h4> |
| <p>Declare the hash algorithm for a PAKE cipher suite.</p> |
| <pre class="literal-block"> |
| void <a class="reference internal" href="#c.psa_pake_cs_set_hash" title="psa_pake_cs_set_hash">psa_pake_cs_set_hash</a>(<a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a>* cipher_suite, |
| psa_algorithm_t hash_alg); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite object to write to.</dd> |
| <dt> <code class="docutils literal"><span class="pre">hash_alg</span></code></dt> |
| <dd>The hash algorithm to write: a value of type <code class="xref any docutils literal"><span class="pre">psa_algorithm_t</span></code> such that <code class="docutils literal"><span class="pre">PSA_ALG_IS_HASH</span></code><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. |
| If this is <code class="xref any docutils literal"><span class="pre">PSA_ALG_NONE</span></code>, the hash algorithm in <code class="docutils literal"><span class="pre">cipher_suite</span></code> becomes unspecified.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">void</span></code></p> |
| <p class="rubric">Description</p> |
| <p>This function overwrites any hash algorithm previously set in <code class="docutils literal"><span class="pre">cipher_suite</span></code>.</p> |
| <p>The documentation of individual PAKE algorithms specifies which hash algorithms are compatible, or if no hash algorithm is required.</p> |
| <div class="admonition-implementation-note admonition"> |
| <p class="first admonition-title">Implementation note</p> |
| <p class="last">This is a simple accessor function that is not required to validate its inputs. It can be efficiently implemented as a <code class="docutils literal"><span class="pre">static</span> <span class="pre">inline</span></code> function or a function-like macro.</p> |
| </div> |
| </div> |
| </div> |
| <div class="section" id="pake-roles"> |
| <span id="id2"></span><h3>2.2.4. PAKE roles</h3> |
| <p>Some PAKE algorithms need to know which role each participant is taking in the algorithm. For example:</p> |
| <ul class="simple"> |
| <li>Augmented PAKE algorithms typically have a client and a server participant.</li> |
| <li>Some symmetric PAKE algorithms need to assign an order to the participants.</li> |
| </ul> |
| <div class="section" id="psa_pake_role_t"> |
| <span id="c.psa_pake_role_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_role_t</span></code> (type)</h4> |
| <p>Encoding of the application role in a PAKE algorithm.</p> |
| <pre class="literal-block"> |
| typedef uint8_t <a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>; |
| </pre> |
| <p>This type is used to encode the application’s role in the algorithm being executed. |
| For more information see the documentation of individual PAKE role constants.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_ROLE_NONE"> |
| <span id="c.PSA_PAKE_ROLE_NONE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_ROLE_NONE</span></code> (macro)</h4> |
| <p>A value to indicate no role in a PAKE algorithm.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_ROLE_NONE" title="PSA_PAKE_ROLE_NONE">PSA_PAKE_ROLE_NONE</a> ((<a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>)0x00) |
| </pre> |
| <p>This value can be used in a call to <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a> for symmetric PAKE algorithms which do not assign roles.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_ROLE_FIRST"> |
| <span id="c.PSA_PAKE_ROLE_FIRST"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_ROLE_FIRST</span></code> (macro)</h4> |
| <p>The first peer in a balanced PAKE.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_ROLE_FIRST" title="PSA_PAKE_ROLE_FIRST">PSA_PAKE_ROLE_FIRST</a> ((<a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>)0x01) |
| </pre> |
| <p>Although balanced PAKE algorithms are symmetric, some of them need the peers to be ordered for the transcript calculations. |
| If the algorithm does not need a specific ordering, then either do not call <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a>, or use <a class="reference internal" href="#c.PSA_PAKE_ROLE_NONE" title="PSA_PAKE_ROLE_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_ROLE_NONE</span></code></a> as the role parameter.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_ROLE_SECOND"> |
| <span id="c.PSA_PAKE_ROLE_SECOND"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_ROLE_SECOND</span></code> (macro)</h4> |
| <p>The second peer in a balanced PAKE.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_ROLE_SECOND" title="PSA_PAKE_ROLE_SECOND">PSA_PAKE_ROLE_SECOND</a> ((<a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>)0x02) |
| </pre> |
| <p>Although balanced PAKE algorithms are symmetric, some of them need the peers to be ordered for the transcript calculations. |
| If the algorithm does not need a specific ordering, then either do not call <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a>, or use <a class="reference internal" href="#c.PSA_PAKE_ROLE_NONE" title="PSA_PAKE_ROLE_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_ROLE_NONE</span></code></a> as the role parameter.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_ROLE_CLIENT"> |
| <span id="c.PSA_PAKE_ROLE_CLIENT"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_ROLE_CLIENT</span></code> (macro)</h4> |
| <p>The client in an augmented PAKE.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_ROLE_CLIENT" title="PSA_PAKE_ROLE_CLIENT">PSA_PAKE_ROLE_CLIENT</a> ((<a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>)0x11) |
| </pre> |
| <p>Augmented PAKE algorithms need to differentiate between client and server.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_ROLE_SERVER"> |
| <span id="c.PSA_PAKE_ROLE_SERVER"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_ROLE_SERVER</span></code> (macro)</h4> |
| <p>The server in an augmented PAKE.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_ROLE_SERVER" title="PSA_PAKE_ROLE_SERVER">PSA_PAKE_ROLE_SERVER</a> ((<a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a>)0x12) |
| </pre> |
| <p>Augmented PAKE algorithms need to differentiate between client and server.</p> |
| </div> |
| </div> |
| <div class="section" id="pake-step-types"> |
| <span id="pake-steps"></span><h3>2.2.5. PAKE step types</h3> |
| <div class="section" id="psa_pake_step_t"> |
| <span id="c.psa_pake_step_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_step_t</span></code> (type)</h4> |
| <p>Encoding of input and output steps for a PAKE algorithm.</p> |
| <pre class="literal-block"> |
| typedef uint8_t <a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a>; |
| </pre> |
| <p>Some PAKE algorithms need to exchange more data than a single key share. |
| This type encodes additional input and output steps for such algorithms.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_STEP_KEY_SHARE"> |
| <span id="c.PSA_PAKE_STEP_KEY_SHARE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_STEP_KEY_SHARE</span></code> (macro)</h4> |
| <p>The key share being sent to or received from the peer.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE">PSA_PAKE_STEP_KEY_SHARE</a> ((<a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a>)0x01) |
| </pre> |
| <p>The format for both input and output using this step is the same as the format for public keys on the group specified by the PAKE operation’s primitive.</p> |
| <p>The public key formats are defined in the documentation for <code class="xref any docutils literal"><span class="pre">psa_export_public_key()</span></code>.</p> |
| <p>For information regarding how the group is determined, consult the documentation <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_STEP_ZK_PUBLIC"> |
| <span id="c.PSA_PAKE_STEP_ZK_PUBLIC"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_STEP_ZK_PUBLIC</span></code> (macro)</h4> |
| <p>A Schnorr NIZKP public key.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PUBLIC" title="PSA_PAKE_STEP_ZK_PUBLIC">PSA_PAKE_STEP_ZK_PUBLIC</a> ((<a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a>)0x02) |
| </pre> |
| <p>This is the ephemeral public key in the Schnorr Non-Interactive Zero-Knowledge Proof, this is the value denoted by <em>V</em> in <a class="reference internal" href="about.html#citation-rfc8235"><span class="cite">[RFC8235]</span></a>.</p> |
| <p>The format for both input and output at this step is the same as that for public keys on the group specified by the PAKE operation’s primitive.</p> |
| <p>For more information on the format, consult the documentation of <code class="xref any docutils literal"><span class="pre">psa_export_public_key()</span></code>.</p> |
| <p>For information regarding how the group is determined, consult the documentation <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_STEP_ZK_PROOF"> |
| <span id="c.PSA_PAKE_STEP_ZK_PROOF"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_STEP_ZK_PROOF</span></code> (macro)</h4> |
| <p>A Schnorr NIZKP proof.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF">PSA_PAKE_STEP_ZK_PROOF</a> ((<a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a>)0x03) |
| </pre> |
| <p>This is the proof in the Schnorr Non-Interactive Zero-Knowledge Proof, this is the value denoted by <em>r</em> in <a class="reference internal" href="about.html#citation-rfc8235"><span class="cite">[RFC8235]</span></a>.</p> |
| <p>Both for input and output, the value at this step is an integer less than the order of the group specified by the PAKE operation’s primitive. |
| The format depends on the group as well:</p> |
| <ul class="simple"> |
| <li>For Montgomery curves, the encoding is little endian.</li> |
| <li>For other Elliptic curves, and for Diffie-Hellman groups, the encoding is big endian. See <a class="reference internal" href="about.html#citation-sec1"><span class="cite">[SEC1]</span></a> §2.3.8.</li> |
| </ul> |
| <p>In both cases leading zeroes are allowed as long as the length in bytes does not exceed the byte length of the group order.</p> |
| <p>For information regarding how the group is determined, consult the documentation <a class="reference internal" href="#c.PSA_PAKE_PRIMITIVE" title="PSA_PAKE_PRIMITIVE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_PRIMITIVE()</span></code></a>.</p> |
| </div> |
| </div> |
| <div class="section" id="multi-part-pake-operations"> |
| <span id="pake-operation"></span><h3>2.2.6. Multi-part PAKE operations</h3> |
| <div class="section" id="psa_pake_operation_t"> |
| <span id="c.psa_pake_operation_t"></span><h4><code class="docutils literal"><span class="pre">psa_pake_operation_t</span></code> (type)</h4> |
| <p>The type of the state object for PAKE operations.</p> |
| <pre class="literal-block"> |
| typedef <em>/* implementation-defined type */</em> <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a>; |
| </pre> |
| <p>Before calling any function on a PAKE operation object, the application must initialize it by any of the following means:</p> |
| <ul> |
| <li><p class="first">Set the object to all-bits-zero, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> operation; |
| memset(&operation, 0, sizeof(operation)); |
| </pre> |
| </li> |
| <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> |
| <pre class="literal-block"> |
| static <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> operation; |
| </pre> |
| </li> |
| <li><p class="first">Initialize the object to the initializer <a class="reference internal" href="#c.PSA_PAKE_OPERATION_INIT" title="PSA_PAKE_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OPERATION_INIT</span></code></a>, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> operation = <a class="reference internal" href="#c.PSA_PAKE_OPERATION_INIT" title="PSA_PAKE_OPERATION_INIT">PSA_PAKE_OPERATION_INIT</a>; |
| </pre> |
| </li> |
| <li><p class="first">Assign the result of the function <a class="reference internal" href="#c.psa_pake_cipher_suite_init" title="psa_pake_cipher_suite_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_cipher_suite_init()</span></code></a> to the object, for example:</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> operation; |
| operation = <a class="reference internal" href="#c.psa_pake_operation_init" title="psa_pake_operation_init">psa_pake_operation_init</a>(); |
| </pre> |
| </li> |
| </ul> |
| <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> |
| </div> |
| <div class="section" id="PSA_PAKE_OPERATION_INIT"> |
| <span id="c.PSA_PAKE_OPERATION_INIT"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_OPERATION_INIT</span></code> (macro)</h4> |
| <p>This macro returns a suitable initializer for a PAKE operation object of type <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_operation_t</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_OPERATION_INIT" title="PSA_PAKE_OPERATION_INIT">PSA_PAKE_OPERATION_INIT</a> <em>/* implementation-defined value */</em> |
| </pre> |
| </div> |
| <div class="section" id="psa_pake_operation_init"> |
| <span id="c.psa_pake_operation_init"></span><h4><code class="docutils literal"><span class="pre">psa_pake_operation_init</span></code> (function)</h4> |
| <p>Return an initial value for a PAKE operation object.</p> |
| <pre class="literal-block"> |
| <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> <a class="reference internal" href="#c.psa_pake_operation_init" title="psa_pake_operation_init">psa_pake_operation_init</a>(void); |
| </pre> |
| <p class="rubric">Returns: <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="docutils literal"><span class="pre">psa_pake_operation_t</span></code></a></p> |
| </div> |
| <div class="section" id="psa_pake_setup"> |
| <span id="c.psa_pake_setup"></span><h4><code class="docutils literal"><span class="pre">psa_pake_setup</span></code> (function)</h4> |
| <p>Set the session information for a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup">psa_pake_setup</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| const <a class="reference internal" href="#c.psa_pake_cipher_suite_t" title="psa_pake_cipher_suite_t">psa_pake_cipher_suite_t</a> *cipher_suite); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>The operation object to set up. |
| It must have been initialized as per the documentation for <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_operation_t</span></code></a> and not yet in use.</dd> |
| <dt> <code class="docutils literal"><span class="pre">cipher_suite</span></code></dt> |
| <dd>The cipher suite to use. |
| A PAKE cipher suite fully characterizes a PAKE algorithm, including the PAKE algorithm.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be inactive.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The algorithm in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is not a PAKE algorithm.</li> |
| <li>The PAKE primitive in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is not compatible with the PAKE algorithm.</li> |
| <li>The hash algorithm in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is invalid, or not compatible with the PAKE algorithm and primitive.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The algorithm in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is not a supported PAKE algorithm.</li> |
| <li>The PAKE primitive in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is not supported or not compatible with the PAKE algorithm.</li> |
| <li>The hash algorithm in <code class="docutils literal"><span class="pre">cipher_suite</span></code> is not supported, or not compatible with the PAKE algorithm and primitive.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>The sequence of operations to set up a password-authenticated key exchange operation is as follows:</p> |
| <ol class="arabic simple"> |
| <li>Allocate an operation object which will be passed to all the functions listed here.</li> |
| <li>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_operation_t</span></code></a>. |
| For example, using <a class="reference internal" href="#c.PSA_PAKE_OPERATION_INIT" title="PSA_PAKE_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_setup()</span></code></a> to specify the cipher suite.</li> |
| <li>Call <code class="docutils literal"><span class="pre">psa_pake_set_xxx()</span></code> functions on the operation to complete the setup. |
| The exact sequence of <code class="docutils literal"><span class="pre">psa_pake_set_xxx()</span></code> functions that needs to be called depends on the algorithm in use.</li> |
| </ol> |
| <p>A typical sequence of calls to perform a password-authenticated key exchange:</p> |
| <ol class="arabic simple"> |
| <li>Call <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="docutils literal"><span class="pre">psa_pake_output</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">operation</span></code><code class="docutils literal"><span class="pre">,</span> </code><a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE"><code class="docutils literal"><span class="pre">PSA_PAKE_STEP_KEY_SHARE</span></code></a><code class="docutils literal"><span class="pre">,</span> <span class="pre">...)</span></code> to get the key share that needs to be sent to the peer.</li> |
| <li>Call <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="docutils literal"><span class="pre">psa_pake_input</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">operation</span></code><code class="docutils literal"><span class="pre">,</span> </code><a class="reference internal" href="#c.PSA_PAKE_STEP_KEY_SHARE" title="PSA_PAKE_STEP_KEY_SHARE"><code class="docutils literal"><span class="pre">PSA_PAKE_STEP_KEY_SHARE</span></code></a><code class="docutils literal"><span class="pre">,</span> <span class="pre">...)</span></code> to provide the key share that was received from the peer.</li> |
| <li>Depending on the algorithm additional calls to <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> and <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a> might be necessary.</li> |
| <li>Call <a class="reference internal" href="#c.psa_pake_get_implicit_key" title="psa_pake_get_implicit_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_get_implicit_key()</span></code></a> for accessing the shared secret.</li> |
| </ol> |
| <p>Refer to the documentation of individual PAKE algorithms for details on the required set up and operation for each algorithm. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| <p>If an error occurs at any step after a call to <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_setup()</span></code></a>, the operation will need to be reset by a call to <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a>. |
| The application may call <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a> at any time after the operation has been initialized.</p> |
| <p>After a successful call to <a class="reference internal" href="#c.psa_pake_setup" title="psa_pake_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_setup()</span></code></a>, the application must eventually terminate the operation. |
| The following events terminate an operation:</p> |
| <ul class="simple"> |
| <li>A call to <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a>.</li> |
| <li>A successful call to <a class="reference internal" href="#c.psa_pake_get_implicit_key" title="psa_pake_get_implicit_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_get_implicit_key()</span></code></a>.</li> |
| </ul> |
| </div> |
| <div class="section" id="psa_pake_set_password_key"> |
| <span id="c.psa_pake_set_password_key"></span><h4><code class="docutils literal"><span class="pre">psa_pake_set_password_key</span></code> (function)</h4> |
| <p>Set the password for a password-authenticated key exchange using a key.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_set_password_key" title="psa_pake_set_password_key">psa_pake_set_password_key</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| psa_key_id_t password); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">password</span></code></dt> |
| <dd>Identifier of the key holding the password or a value derived from the password. |
| It must remain valid until the operation terminates. |
| It must be of type <code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD</span></code> or <code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD_HASH</span></code>. |
| It must allow the usage <code class="xref any docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active, and <a class="reference internal" href="#c.psa_pake_set_password_key" title="psa_pake_set_password_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_password_key()</span></code></a>, <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a>, and <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> must not have been called yet.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">password</span></code> is not a valid key identifier.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></dt> |
| <dd>The key does not have the <code class="xref any docutils literal"><span class="pre">PSA_KEY_USAGE_DERIVE</span></code> flag, or it does not permit the operation’s algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The key type for <code class="docutils literal"><span class="pre">password</span></code> is not <code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD</span></code> or <code class="xref any docutils literal"><span class="pre">PSA_KEY_TYPE_PASSWORD_HASH</span></code>.</li> |
| <li><code class="docutils literal"><span class="pre">password</span></code> is not compatible with the operation’s cipher suite.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd>The key type or key size of <code class="docutils literal"><span class="pre">password</span></code> is not supported with the operation’s cipher suite.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Refer to the documentation of individual PAKE algorithms for constraints on the format and content of valid passwords. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_set_user"> |
| <span id="c.psa_pake_set_user"></span><h4><code class="docutils literal"><span class="pre">psa_pake_set_user</span></code> (function)</h4> |
| <p>Set the user ID for a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user">psa_pake_set_user</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| const uint8_t *user_id, |
| size_t user_id_len); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">user_id</span></code></dt> |
| <dd>The user ID to authenticate with.</dd> |
| <dt> <code class="docutils literal"><span class="pre">user_id_len</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">user_id</span></code> buffer in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active, and <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_user()</span></code></a>, <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a>, and <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> must not have been called yet.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">user_id</span></code> is not valid for the operation’s algorithm and cipher suite.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd>The value of <code class="docutils literal"><span class="pre">user_id</span></code> is not supported by the implementation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Call this function to set the user ID. |
| For PAKE algorithms that associate a user identifier with both participants in the session, also call <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_peer()</span></code></a> with the peer ID. |
| For PAKE algorithms that associate a single user identifier with the session, call <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_user()</span></code></a> only.</p> |
| <p>Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_set_peer"> |
| <span id="c.psa_pake_set_peer"></span><h4><code class="docutils literal"><span class="pre">psa_pake_set_peer</span></code> (function)</h4> |
| <p>Set the peer ID for a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer">psa_pake_set_peer</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| const uint8_t *peer_id, |
| size_t peer_id_len); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">peer_id</span></code></dt> |
| <dd>The peer’s ID to authenticate.</dd> |
| <dt> <code class="docutils literal"><span class="pre">peer_id_len</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">peer_id</span></code> buffer in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active, and <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_peer()</span></code></a>, <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a>, and <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> must not have been called yet.</li> |
| <li>Calling <a class="reference internal" href="#c.psa_pake_set_peer" title="psa_pake_set_peer"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_peer()</span></code></a> is invalid with the operation’s algorithm.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">peer_id</span></code> is not valid for the operation’s algorithm and cipher suite.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd>The value of <code class="docutils literal"><span class="pre">peer_id</span></code> is not supported by the implementation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Call this function in addition to <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_user()</span></code></a> for PAKE algorithms that associate a user identifier with both participants in the session. |
| For PAKE algorithms that associate a single user identifier with the session, call <a class="reference internal" href="#c.psa_pake_set_user" title="psa_pake_set_user"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_user()</span></code></a> only.</p> |
| <p>Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_set_role"> |
| <span id="c.psa_pake_set_role"></span><h4><code class="docutils literal"><span class="pre">psa_pake_set_role</span></code> (function)</h4> |
| <p>Set the application role for a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role">psa_pake_set_role</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| <a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t">psa_pake_role_t</a> role); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">role</span></code></dt> |
| <dd>A value of type <a class="reference internal" href="#c.psa_pake_role_t" title="psa_pake_role_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_role_t</span></code></a> indicating the application role in the PAKE algorithm. |
| See <a class="reference internal" href="#pake-roles"><span class="secref">PAKE roles</span></a>.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active, and <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a>, <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a>, and <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> must not have been called yet.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">role</span></code> is not a valid PAKE role in the operation’s algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">role</span></code> is not a valid PAKE role, or is not supported for the operation’s algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Not all PAKE algorithms need to differentiate the communicating participants. |
| For PAKE algorithms that do not require a role to be specified, the application can do either of the following:</p> |
| <ul class="simple"> |
| <li>Not call <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a> on the PAKE operation.</li> |
| <li>Call <a class="reference internal" href="#c.psa_pake_set_role" title="psa_pake_set_role"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_set_role()</span></code></a> with the <a class="reference internal" href="#c.PSA_PAKE_ROLE_NONE" title="PSA_PAKE_ROLE_NONE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_ROLE_NONE</span></code></a> role.</li> |
| </ul> |
| <p>Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_output"> |
| <span id="c.psa_pake_output"></span><h4><code class="docutils literal"><span class="pre">psa_pake_output</span></code> (function)</h4> |
| <p>Get output for a step of a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output">psa_pake_output</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| <a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a> step, |
| uint8_t *output, |
| size_t output_size, |
| size_t *output_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">step</span></code></dt> |
| <dd>The step of the algorithm for which the output is requested.</dd> |
| <dt> <code class="docutils literal"><span class="pre">output</span></code></dt> |
| <dd>Buffer where the output is to be written. |
| The format of the output depends on the <code class="docutils literal"><span class="pre">step</span></code>, see <a class="reference internal" href="#pake-steps"><span class="secref">PAKE step types</span></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">output_size</span></code></dt> |
| <dd><p class="first">Size of the <code class="docutils literal"><span class="pre">output</span></code> buffer in bytes. |
| This must be appropriate for the cipher suite and output step:</p> |
| <ul class="last simple"> |
| <li>A sufficient output size is <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_SIZE" title="PSA_PAKE_OUTPUT_SIZE"><code class="docutils literal"><span class="pre">PSA_PAKE_OUTPUT_SIZE</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><code class="docutils literal"><span class="pre">primitive</span></code><code class="docutils literal"><span class="pre">,</span> </code><code class="docutils literal"><span class="pre">step</span></code><code class="docutils literal"><span class="pre">)</span></code> where <code class="docutils literal"><span class="pre">alg</span></code> and <code class="docutils literal"><span class="pre">primitive</span></code> are the PAKE algorithm and primitive in the operation’s cipher suite, and <code class="docutils literal"><span class="pre">step</span></code> is the output step.</li> |
| <li><a class="reference internal" href="#c.PSA_PAKE_OUTPUT_MAX_SIZE" title="PSA_PAKE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported PAKE algorithm, primitive and step.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">output_length</span></code></dt> |
| <dd>On success, the number of bytes of the returned output.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success. |
| The first <code class="docutils literal"><span class="pre">(*output_length)</span></code> bytes of <code class="docutils literal"><span class="pre">output</span></code> contain the output.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm’s requirements for ordering of input and output steps.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></dt> |
| <dd>The size of the <code class="docutils literal"><span class="pre">output</span></code> buffer is too small. |
| <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_SIZE" title="PSA_PAKE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_MAX_SIZE" title="PSA_PAKE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_MAX_SIZE</span></code></a> can be used to determine a sufficient buffer size.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd><code class="docutils literal"><span class="pre">step</span></code> is not supported with the operation’s algorithm.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_ENTROPY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all.</p> |
| <p>The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. |
| Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| <p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_input"> |
| <span id="c.psa_pake_input"></span><h4><code class="docutils literal"><span class="pre">psa_pake_input</span></code> (function)</h4> |
| <p>Provide input for a step of a password-authenticated key exchange.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input">psa_pake_input</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| <a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t">psa_pake_step_t</a> step, |
| const uint8_t *input, |
| size_t input_length); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">step</span></code></dt> |
| <dd>The step for which the input is provided.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input</span></code></dt> |
| <dd>Buffer containing the input. |
| The format of the input depends on the <code class="docutils literal"><span class="pre">step</span></code>, see <a class="reference internal" href="#pake-steps"><span class="secref">PAKE step types</span></a>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input_length</span></code></dt> |
| <dd>Size of the <code class="docutils literal"><span class="pre">input</span></code> buffer in bytes.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The operation state is not valid: it must be active and fully set up, and this call must conform to the algorithm’s requirements for ordering of input and output steps.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_SIGNATURE</span></code></dt> |
| <dd>The verification fails for a <a class="reference internal" href="#c.PSA_PAKE_STEP_ZK_PROOF" title="PSA_PAKE_STEP_ZK_PROOF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_STEP_ZK_PROOF</span></code></a> input step.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">step</span></code> is not compatible with the operation’s algorithm.</li> |
| <li>The input is not valid for the operation’s algorithm, cipher suite or <code class="docutils literal"><span class="pre">step</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li><code class="docutils literal"><span class="pre">step</span></code> is not supported with the operation’s algorithm.</li> |
| <li>The input is not supported for the operation’s algorithm, cipher suite or <code class="docutils literal"><span class="pre">step</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>Depending on the algorithm being executed, you might need to call this function several times or you might not need to call this at all.</p> |
| <p>The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. |
| Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| <p><a class="reference internal" href="#c.PSA_PAKE_INPUT_SIZE" title="PSA_PAKE_INPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_INPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_PAKE_INPUT_MAX_SIZE" title="PSA_PAKE_INPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_INPUT_MAX_SIZE</span></code></a> can be used to allocate buffers of sufficient size to transfer inputs that are received from the peer into the operation.</p> |
| <p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="psa_pake_get_implicit_key"> |
| <span id="c.psa_pake_get_implicit_key"></span><h4><code class="docutils literal"><span class="pre">psa_pake_get_implicit_key</span></code> (function)</h4> |
| <p>Pass the implicitly confirmed shared secret from a PAKE into a key derivation operation.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_get_implicit_key" title="psa_pake_get_implicit_key">psa_pake_get_implicit_key</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> *operation, |
| psa_key_derivation_operation_t *output); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Active PAKE operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">output</span></code></dt> |
| <dd>A key derivation operation that is ready for an input step of type <code class="xref any docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success. |
| Use the <code class="docutils literal"><span class="pre">output</span></code> key derivation operation to continue with derivation of keys or data.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd><p class="first">The following conditions can result in this error:</p> |
| <ul class="last simple"> |
| <li>The state of PAKE operation <code class="docutils literal"><span class="pre">operation</span></code> is not valid: it must be active, with all setup, input, and output steps complete.</li> |
| <li>The state of key derivation operation <code class="docutils literal"><span class="pre">output</span></code> is not valid for the <code class="xref any docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> step.</li> |
| <li>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</li> |
| </ul> |
| </dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></dt> |
| <dd><code class="xref any docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> is not compatible with the algorithm in the <code class="docutils literal"><span class="pre">output</span></code> key derivation operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></dt> |
| <dd>Input from a PAKE is not supported by the algorithm in the <code class="docutils literal"><span class="pre">output</span></code> key derivation operation.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <p>At this step in the PAKE operation there is a cryptographic guarantee that only an authenticated participant who used the same password is able to compute the key. |
| But there is no guarantee that the peer is the participant it claims to be, and was able to compute the same key.</p> |
| <p>In this situation, the authentication is only implicit. |
| Since the peer is not authenticated, no action should be taken that assumes that the peer is who it claims to be |
| For example, do not access restricted files on the peer’s behalf until an explicit authentication has succeeded.</p> |
| <p>This function can be called after the key exchange phase of the operation has completed. |
| It injects the shared secret output of the PAKE into the provided key derivation operation. |
| The input step <code class="xref any docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code> is used to input the shared key material into the key derivation operation.</p> |
| <p>The exact sequence of calls to perform a password-authenticated key exchange depends on the algorithm in use. |
| Refer to the documentation of individual PAKE algorithms for more information. |
| See <a class="reference internal" href="#pake-algorithms"><span class="secref">PAKE algorithms</span></a>.</p> |
| <p>When this function returns successfully, <code class="docutils literal"><span class="pre">operation</span></code> becomes inactive. |
| If this function returns an error status, both the <code class="docutils literal"><span class="pre">operation</span></code> and the <code class="docutils literal"><span class="pre">key_derivation</span></code> operations enter an error state and must be aborted by calling <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a> and <code class="xref any docutils literal"><span class="pre">psa_key_derivation_abort()</span></code> respectively.</p> |
| </div> |
| <div class="section" id="psa_pake_abort"> |
| <span id="c.psa_pake_abort"></span><h4><code class="docutils literal"><span class="pre">psa_pake_abort</span></code> (function)</h4> |
| <p>Abort a PAKE operation.</p> |
| <pre class="literal-block"> |
| psa_status_t <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort">psa_pake_abort</a>(<a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t">psa_pake_operation_t</a> * operation); |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">operation</span></code></dt> |
| <dd>Initialized PAKE operation.</dd> |
| </dl> |
| <p class="rubric">Returns: <code class="docutils literal"><span class="pre">psa_status_t</span></code></p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">PSA_SUCCESS</span></code></dt> |
| <dd>Success. |
| The operation object can now be discarded or reused.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></dt> |
| <dd>The library requires initializing by a call to <code class="xref any docutils literal"><span class="pre">psa_crypto_init()</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></dt> |
| <dd></dd> |
| <dt> <code class="docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></dt> |
| <dd></dd> |
| </dl> |
| <p class="rubric">Description</p> |
| <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_pake_setup" title="psa_pake_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_setup()</span></code></a> again.</p> |
| <p>This function can be called any time after the operation object has been initialized as described in <a class="reference internal" href="#c.psa_pake_operation_t" title="psa_pake_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_operation_t</span></code></a>.</p> |
| <p>In particular, calling <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a> after the operation has been terminated by a call to <a class="reference internal" href="#c.psa_pake_abort" title="psa_pake_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_abort()</span></code></a> or <a class="reference internal" href="#c.psa_pake_get_implicit_key" title="psa_pake_get_implicit_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_get_implicit_key()</span></code></a> is safe and has no effect.</p> |
| </div> |
| </div> |
| <div class="section" id="support-macros"> |
| <h3>2.2.7. Support macros</h3> |
| <div class="section" id="PSA_PAKE_OUTPUT_SIZE"> |
| <span id="c.PSA_PAKE_OUTPUT_SIZE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_OUTPUT_SIZE</span></code> (macro)</h4> |
| <p>Sufficient output buffer size for <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a>, in bytes.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_SIZE" title="PSA_PAKE_OUTPUT_SIZE">PSA_PAKE_OUTPUT_SIZE</a>(alg, primitive, output_step) \ |
| <em>/* implementation-defined value */</em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>A PAKE algorithm: a value of type <code class="xref any docutils literal"><span class="pre">psa_algorithm_t</span></code> such that <a class="reference internal" href="#c.PSA_ALG_IS_PAKE" title="PSA_ALG_IS_PAKE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_PAKE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| <dt> <code class="docutils literal"><span class="pre">primitive</span></code></dt> |
| <dd>A primitive of type <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a> that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">output_step</span></code></dt> |
| <dd>A value of type <a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_step_t</span></code></a> that is valid for the algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>A sufficient output buffer size for the specified PAKE algorithm, primitive, and output step. |
| An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a PAKE algorithm, primitive, and output step that it recognizes, but does not support. |
| If the parameters are not valid, the return value is unspecified.</p> |
| <p class="rubric">Description</p> |
| <p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> will not fail due to an insufficient buffer size. |
| The actual size of the output might be smaller in any given call.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_MAX_SIZE" title="PSA_PAKE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_MAX_SIZE</span></code></a></p> |
| </div> |
| <div class="section" id="PSA_PAKE_OUTPUT_MAX_SIZE"> |
| <span id="c.PSA_PAKE_OUTPUT_MAX_SIZE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_OUTPUT_MAX_SIZE</span></code> (macro)</h4> |
| <p>Sufficient output buffer size for <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> for any of the supported PAKE algorithms, primitives and output steps.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_MAX_SIZE" title="PSA_PAKE_OUTPUT_MAX_SIZE">PSA_PAKE_OUTPUT_MAX_SIZE</a> <em>/* implementation-defined value */</em> |
| </pre> |
| <p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#c.psa_pake_output" title="psa_pake_output"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_output()</span></code></a> will not fail due to an insufficient buffer size.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_PAKE_OUTPUT_SIZE" title="PSA_PAKE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_OUTPUT_SIZE()</span></code></a>.</p> |
| </div> |
| <div class="section" id="PSA_PAKE_INPUT_SIZE"> |
| <span id="c.PSA_PAKE_INPUT_SIZE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_INPUT_SIZE</span></code> (macro)</h4> |
| <p>Sufficient buffer size for inputs to <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a>.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_INPUT_SIZE" title="PSA_PAKE_INPUT_SIZE">PSA_PAKE_INPUT_SIZE</a>(alg, primitive, input_step) \ |
| <em>/* implementation-defined value */</em> |
| </pre> |
| <p class="rubric">Parameters</p> |
| <dl class="docutils"> |
| <dt> <code class="docutils literal"><span class="pre">alg</span></code></dt> |
| <dd>A PAKE algorithm: a value of type <code class="xref any docutils literal"><span class="pre">psa_algorithm_t</span></code> such that <a class="reference internal" href="#c.PSA_ALG_IS_PAKE" title="PSA_ALG_IS_PAKE"><code class="docutils literal"><span class="pre">PSA_ALG_IS_PAKE</span></code></a><code class="docutils literal"><span class="pre">(</span></code><code class="docutils literal"><span class="pre">alg</span></code><code class="docutils literal"><span class="pre">)</span></code> is true.</dd> |
| <dt> <code class="docutils literal"><span class="pre">primitive</span></code></dt> |
| <dd>A primitive of type <a class="reference internal" href="#c.psa_pake_primitive_t" title="psa_pake_primitive_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_primitive_t</span></code></a> that is compatible with algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| <dt> <code class="docutils literal"><span class="pre">input_step</span></code></dt> |
| <dd>A value of type <a class="reference internal" href="#c.psa_pake_step_t" title="psa_pake_step_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_pake_step_t</span></code></a> that is valid for the algorithm <code class="docutils literal"><span class="pre">alg</span></code>.</dd> |
| </dl> |
| <p class="rubric">Returns</p> |
| <p>A sufficient buffer size for the specified PAKE algorithm, primitive, and input step. |
| An implementation can return either <code class="docutils literal"><span class="pre">0</span></code> or a correct size for a PAKE algorithm, primitive, and output step that it recognizes, but does not support. |
| If the parameters are not valid, the return value is unspecified.</p> |
| <p class="rubric">Description</p> |
| <p>The value returned by this macro is guaranteed to be large enough for any valid input to <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a> in an operation with the specified parameters.</p> |
| <p>This macro can be useful when transferring inputs from the peer into the PAKE operation.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_PAKE_INPUT_MAX_SIZE" title="PSA_PAKE_INPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_INPUT_MAX_SIZE</span></code></a></p> |
| </div> |
| <div class="section" id="PSA_PAKE_INPUT_MAX_SIZE"> |
| <span id="c.PSA_PAKE_INPUT_MAX_SIZE"></span><h4><code class="docutils literal"><span class="pre">PSA_PAKE_INPUT_MAX_SIZE</span></code> (macro)</h4> |
| <p>Sufficient buffer size for inputs to <a class="reference internal" href="#c.psa_pake_input" title="psa_pake_input"><code class="xref any c c-func docutils literal"><span class="pre">psa_pake_input()</span></code></a> for any of the supported PAKE algorithms, primitives and input steps.</p> |
| <pre class="literal-block"> |
| #define <a class="reference internal" href="#c.PSA_PAKE_INPUT_MAX_SIZE" title="PSA_PAKE_INPUT_MAX_SIZE">PSA_PAKE_INPUT_MAX_SIZE</a> <em>/* implementation-defined value */</em> |
| </pre> |
| <p>This macro can be useful when transferring inputs from the peer into the PAKE operation.</p> |
| <p>See also <a class="reference internal" href="#c.PSA_PAKE_INPUT_SIZE" title="PSA_PAKE_INPUT_SIZE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_PAKE_INPUT_SIZE()</span></code></a>.</p> |
| </div> |
| </div> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"><h3><a href="index.html"><b>PSA Crypto API PAKE Extension</b></a></h3> |
| AES 0058<br/> |
| Non-confidential<br/> |
| Version 1.1 PAKE Extension.0-bet.0 |
| <span style="color: red; font-weight: bold;"></span> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="about.html">About this document</a></li> |
| </ul> |
| <ul class="current"> |
| <li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li> |
| <li class="toctree-l1 current"><a class="current reference internal" href="#">2. Password-authenticated key exchange (PAKE)</a><ul> |
| <li class="toctree-l2"><a class="reference internal" href="#algorithm-encoding">2.1. Algorithm encoding</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-algorithm-encoding">2.1.1. PAKE algorithm encoding</a></li> |
| </ul> |
| </li> |
| <li class="toctree-l2"><a class="reference internal" href="#changes-and-additions-to-the-programming-api">2.2. Changes and additions to the Programming API</a><ul> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-algorithms">2.2.1. PAKE algorithms</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-primitives">2.2.2. PAKE primitives</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-cipher-suites">2.2.3. PAKE cipher suites</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-roles">2.2.4. PAKE roles</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#pake-step-types">2.2.5. PAKE step types</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#multi-part-pake-operations">2.2.6. Multi-part PAKE operations</a></li> |
| <li class="toctree-l3"><a class="reference internal" href="#support-macros">2.2.7. Support macros</a></li> |
| </ul> |
| </li> |
| </ul> |
| </li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="example_header.html">Example header file</a></li> |
| <li class="toctree-l1"><a class="reference internal" href="specdef_values.html">Example macro implementations</a></li> |
| </ul> |
| <ul> |
| <li class="toctree-l1"><a class="reference internal" href="psa_c-identifiers.html">Index of API elements</a></li> |
| </ul> |
| <div id="searchbox" style="display: none" role="search"> |
| <h3>Quick search</h3> |
| <form class="search" action="search.html" method="get"> |
| <div><input type="text" name="q" /></div> |
| <div><input type="submit" value="Go" /></div> |
| <input type="hidden" name="check_keywords" value="yes" /> |
| <input type="hidden" name="area" value="default" /> |
| </form> |
| </div> |
| <script type="text/javascript">$('#searchbox').show(0);</script> |
| </div> |
| </div> |
| <div class="clearer"></div> |
| </div> |
| <div class="footer"> |
| © 2022, Arm Limited or its affiliates. All rights reserved. |
| |
| | |
| Powered by <a href="http://sphinx-doc.org/">Sphinx 1.6.7</a> |
| & <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.8</a> |
| |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |