| |
| <!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>Functionality overview — PSA Crypto API 1.0.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.0.0', |
| COLLAPSE_INDEX: false, |
| FILE_SUFFIX: '.html', |
| HAS_SOURCE: true, |
| 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="index" title="Index" href="../genindex.html" /> |
| <link rel="search" title="Search" href="../search.html" /> |
| <link rel="next" title="Sample architectures" href="sample-arch.html" /> |
| <link rel="prev" title="Design goals" href="goals.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="functionality-overview"> |
| <span id="id1"></span><h1>Functionality overview</h1> |
| <p>This section provides a high-level overview of the functionality provided by the |
| interface defined in this specification. Refer to the <a class="reference internal" href="../api/library/index.html#api-reference"><span class="std std-ref">API definition</span></a> for a detailed description.</p> |
| <p><a class="reference internal" href="../appendix/history.html#future"><span class="std std-ref">Future additions</span></a> describes features that might be included in future versions of this |
| specification.</p> |
| <p>Due to the modularity of the interface, almost every part of the library is |
| optional. The only mandatory function is <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a>.</p> |
| <div class="section" id="library-management"> |
| <h2>Library management</h2> |
| <p>Applications must call <a class="reference internal" href="../api/library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal"><span class="pre">psa_crypto_init()</span></code></a> to initialize the library before |
| using any other function.</p> |
| </div> |
| <div class="section" id="key-management"> |
| <h2>Key management</h2> |
| <p>Applications always access keys indirectly via an identifier, and can perform |
| operations using a key without accessing the key material. This allows keys to |
| be <em>non-extractable</em>, where an application can use a key but is not permitted to |
| obtain the key material. Non-extractable keys are bound to the device, can be |
| rate-limited and can have their usage restricted by policies.</p> |
| <p>Each key has a set of attributes that describe the key and the policy for using |
| the key. A <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object contains all of the attributes, which |
| is used when creating a key and when querying key attributes.</p> |
| <p>Each key has a <em>lifetime</em> that determines when the key material is destroyed. |
| There are two types of lifetimes: <a class="reference internal" href="#volatile-keys"><span class="std std-ref">volatile</span></a> and |
| <a class="reference internal" href="#persistent-keys"><span class="std std-ref">persistent</span></a>.</p> |
| <div class="section" id="volatile-keys"> |
| <span id="id2"></span><h3>Volatile keys</h3> |
| <p>A <em>volatile</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> |
| or until the application terminates, which conceptually destroys all of its |
| volatile keys.</p> |
| <p>Conceptually, a volatile key is stored in RAM. Volatile keys have the |
| lifetime <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_VOLATILE" title="PSA_KEY_LIFETIME_VOLATILE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_VOLATILE</span></code></a>.</p> |
| <p>To create a volatile key:</p> |
| <ol class="arabic simple"> |
| <li>Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the required type, size, policy |
| and other key attributes.</li> |
| <li>Create the key with <a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>, <a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>, |
| <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> or <a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a>. If successful, these |
| functions output a transient <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a>.</li> |
| </ol> |
| <p>To destroy a volatile key, call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier.</p> |
| </div> |
| <div class="section" id="persistent-keys"> |
| <span id="id3"></span><h3>Persistent keys</h3> |
| <p>A <em>persistent</em> key exists until it explicitly destroyed with <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> |
| or until it is wiped by the reset or destruction of the device.</p> |
| <p>Each persistent key has a permanent key identifier, which acts as a name for the key. |
| Within an application, the key identifier corresponds to a single key. The |
| application specifies the key identifier when the key is created and when |
| using the key.</p> |
| <p>Persistent keys can be stored in different storage areas; this is indicated |
| through different lifetime values. This specification defines a single lifetime |
| value <a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_LIFETIME_PERSISTENT" title="PSA_KEY_LIFETIME_PERSISTENT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_LIFETIME_PERSISTENT</span></code></a> which corresponds to a default storage |
| area. Implementations can define alternative lifetime values corresponding to |
| different storage areas with different retention policies, or to secure elements |
| with different security characteristics.</p> |
| <p>To create a persistent key:</p> |
| <ol class="arabic"> |
| <li><p class="first">Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the key’s type, size, policy |
| and other attributes.</p> |
| </li> |
| <li><p class="first">In the attributes object, set the desired lifetime and persistent identifier |
| for the key.</p> |
| </li> |
| <li><p class="first">Create the key with one of the <em>key creation functions</em>:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a></li> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a></li> |
| <li><a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a></li> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_copy_key" title="psa_copy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_copy_key()</span></code></a></li> |
| </ul> |
| <p>If successful, these functions output the <a class="reference internal" href="#key-ids"><span class="std std-ref">key identifier</span></a> |
| that was specified by the application in step 2.</p> |
| </li> |
| </ol> |
| <p>To access an existing persistent key: use the key identifier in any API that |
| requires a key.</p> |
| <p>To remove cached copies of key material for persistent keys created with the |
| <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> policy: call <a class="reference internal" href="../api/keys/management.html#c.psa_purge_key" title="psa_purge_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_purge_key()</span></code></a> with the key identifier.</p> |
| <p>To destroy a persistent key: call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> with the key identifier. |
| Destroying a persistent key permanently removes it from memory and storage.</p> |
| <p>The key lifetime and identifier are set when the key is created and cannot be |
| changed without destroying the key first. If the original key permits copying, |
| then the application can specify a different lifetime for the copy of the key.</p> |
| </div> |
| <div class="section" id="key-identifiers"> |
| <span id="key-ids"></span><h3>Key identifiers</h3> |
| <p>Key identifiers are integral values that act as permanent names for persistent |
| keys, or as transient references to volatile keys. Key identifiers use the |
| <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_id_t" title="psa_key_id_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_id_t</span></code></a> type, and the range of identifier values is divided as follows:</p> |
| <dl class="docutils"> |
| <dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"> <span class="pre">=</span> <span class="pre">0</span></code></dt> |
| <dd>Reserved as an invalid key identifier.</dd> |
| <dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MIN" title="PSA_KEY_ID_USER_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_USER_MAX" title="PSA_KEY_ID_USER_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_USER_MAX</span></code></a></dt> |
| <dd>Applications can freely choose persistent key identifiers in this range.</dd> |
| <dt><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MIN" title="PSA_KEY_ID_VENDOR_MIN"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MIN</span></code></a><code class="docutils literal"> <span class="pre">-</span> </code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_VENDOR_MAX" title="PSA_KEY_ID_VENDOR_MAX"><code class="docutils literal"><span class="pre">PSA_KEY_ID_VENDOR_MAX</span></code></a></dt> |
| <dd>Implementations can define additional persistent key identifiers in this |
| range, and must allocate any volatile key identifiers from this range.</dd> |
| </dl> |
| <p>Key identifiers outside these ranges are reserved for future use.</p> |
| <p>Key identifiers are output from a successful call to one of |
| the key creation functions. For persistent keys, this is the same identifier |
| as the one specified in the key attributes used to create the key. |
| The key identifier remains valid until it is invalidated by passing it to |
| <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a>. A volatile key identifier must not be used after it has been |
| invalidated.</p> |
| <p>Valid key identifiers must have distinct values within the same application. If |
| the implementation provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key |
| identifiers are local to each application. That is, the same key identifier in two |
| applications corresponds to two different keys.</p> |
| <p>If an invalid key identifier is provided as a parameter in any function, the |
| function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a>; except for the special case of |
| calling <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="docutils literal"><span class="pre">psa_destroy_key</span></code></a><code class="docutils literal"><span class="pre">(</span></code><a class="reference internal" href="../api/keys/locations.html#c.PSA_KEY_ID_NULL" title="PSA_KEY_ID_NULL"><code class="docutils literal"><span class="pre">PSA_KEY_ID_NULL</span></code></a><code class="docutils literal"><span class="pre">)</span></code>, which has no effect and always |
| returns <a class="reference internal" href="../api/library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_SUCCESS</span></code></a>.</p> |
| <p>There must be a matching call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> for each successful call |
| to a create a volatile key.</p> |
| <p>A call to <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> destroys the key material, and will cause any active |
| operations that are using the key to fail. Therefore an application must not |
| destroy a key while an operation using that key is in progress, unless the |
| application is prepared to handle a failure of the operation.</p> |
| </div> |
| <div class="section" id="recommendations-of-minimum-standards-for-key-management"> |
| <h3>Recommendations of minimum standards for key management</h3> |
| <p>Most implementations provide the following functions:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_import_key" title="psa_import_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_import_key()</span></code></a>. The exceptions are implementations that only give access |
| to a key or keys that are provisioned by proprietary means, and do not allow |
| the main application to use its own cryptographic material.</li> |
| <li><a class="reference internal" href="../api/keys/attributes.html#c.psa_get_key_attributes" title="psa_get_key_attributes"><code class="xref any c c-func docutils literal"><span class="pre">psa_get_key_attributes()</span></code></a> and the <code class="docutils literal"><span class="pre">psa_get_key_xxx()</span></code> accessor functions. |
| They are easy to implement, and it is difficult to write applications and to |
| diagnose issues without being able to check the metadata.</li> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_export_public_key" title="psa_export_public_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_public_key()</span></code></a>. This function is usually provided if the |
| implementation supports any asymmetric algorithm, since public-key |
| cryptography often requires the delivery of a public key that is associated |
| with a protected private key.</li> |
| <li><a class="reference internal" href="../api/keys/management.html#c.psa_export_key" title="psa_export_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_export_key()</span></code></a>. However, highly constrained implementations that are |
| designed to work only with short-term keys, or only with long-term |
| non-extractable keys, do not need to provide this function.</li> |
| </ul> |
| </div> |
| </div> |
| <div class="section" id="usage-policies"> |
| <h2>Usage policies</h2> |
| <p>All keys have an associated policy that regulates which operations are permitted |
| on the key. Each key policy is a set of usage flags and a specific algorithm |
| that is permitted with the key. The policy is part of the key attributes that |
| are managed by a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object.</p> |
| <p>The usage flags are encoded in a bitmask, which has the type |
| <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_usage_t" title="psa_key_usage_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_usage_t</span></code></a>. Four kinds of usage flag can be specified:</p> |
| <ul class="simple"> |
| <li>The extractable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_EXPORT" title="PSA_KEY_USAGE_EXPORT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_EXPORT</span></code></a> determines whether the key |
| material can be extracted.</li> |
| <li>The copyable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_COPY" title="PSA_KEY_USAGE_COPY"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_COPY</span></code></a> determines whether the key material |
| can be copied into a new key, which can have a different lifetime or a more |
| restrictive policy.</li> |
| <li>The cacheable flag <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_CACHE" title="PSA_KEY_USAGE_CACHE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_CACHE</span></code></a> determines whether the |
| implementation is permitted to retain non-essential copies of the |
| key material in RAM. This policy only applies to persistent keys. See also |
| <em><a class="reference internal" href="implementation.html#key-material"><span class="std std-ref">Managing key material</span></a></em>.</li> |
| <li>The other usage flags, for example, <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> and <a class="reference internal" href="../api/keys/usage.html#c.PSA_KEY_USAGE_SIGN_MESSAGE" title="PSA_KEY_USAGE_SIGN_MESSAGE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_USAGE_SIGN_MESSAGE</span></code></a>, |
| determine whether the corresponding operation is permitted on the key.</li> |
| </ul> |
| <p>In addition to the usage bitmask, a policy specifies which algorithm is |
| permitted with the key. This specification only defines policies that restrict |
| keys to a single algorithm, which is consistent with both common practice and |
| security good practice.</p> |
| <p>A highly constrained implementation might not be able to support all the policies |
| that can be expressed through this interface. If an implementation cannot create |
| a key with the required policy, it must return an appropriate error code when |
| the key is created.</p> |
| </div> |
| <div class="section" id="symmetric-cryptography"> |
| <h2>Symmetric cryptography</h2> |
| <p>This specification defines interfaces for the following types of symmetric |
| cryptographic operation:</p> |
| <ul class="simple"> |
| <li>Message digests, commonly known as hash functions.</li> |
| <li>Message authentication codes (MAC).</li> |
| <li>Symmetric ciphers.</li> |
| <li>Authenticated encryption with associated data (AEAD).</li> |
| </ul> |
| <p>For each type of symmetric cryptographic operation, the API includes:</p> |
| <ul class="simple"> |
| <li>A pair of <em>single-part</em> functions. For example, compute and verify, or |
| encrypt and decrypt.</li> |
| <li>A series of functions that permit <em>multi-part operations</em>.</li> |
| </ul> |
| <div class="section" id="single-part-functions"> |
| <h3>Single-part Functions</h3> |
| <p>Single-part functions are APIs that implement the cryptographic operation in a |
| single function call. This is the easiest API to use when all of the inputs and |
| outputs fit into the application memory.</p> |
| <p>Some use cases involve messages that are too large to be assembled in memory, or |
| require non-default configuration of the algorithm. These use cases require the |
| use of a <em><a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a></em>.</p> |
| </div> |
| <div class="section" id="multi-part-operations"> |
| <span id="id4"></span><h3>Multi-part operations</h3> |
| <p>Multi-part operations are APIs which split a single cryptographic operation into |
| a sequence of separate steps. This enables fine control over the configuration |
| of the cryptographic operation, and allows the message data to be processed in |
| fragments instead of all at once. For example, the following situations require |
| the use of a multi-part operation:</p> |
| <ul class="simple"> |
| <li>Processing messages that cannot be assembled in memory.</li> |
| <li>Using a deterministic IV for unauthenticated encryption.</li> |
| <li>Providing the IV separately for unauthenticated encryption or decryption.</li> |
| <li>Separating the AEAD authentication tag from the cipher text.</li> |
| </ul> |
| <p>Each multi-part operation defines a specific object type to maintain the state |
| of the operation. These types are implementation-defined. All multi-part |
| operations follow the same pattern of use:</p> |
| <ol class="arabic"> |
| <li><p class="first"><strong>Allocate:</strong> Allocate memory for an operation object of the appropriate |
| type. The application can use any allocation strategy: stack, heap, static, etc.</p> |
| </li> |
| <li><p class="first"><strong>Initialize:</strong> Initialize or assign the operation object by one of the |
| following methods:</p> |
| <blockquote> |
| <div><ul class="simple"> |
| <li>Set it to logical zero. This is automatic for static and global |
| variables. Explicit initialization must use the associated |
| <code class="docutils literal"><span class="pre">PSA_xxx_INIT</span></code> macro as the type is implementation-defined.</li> |
| <li>Set it to all-bits zero. This is automatic if the object was |
| allocated with <code class="docutils literal"><span class="pre">calloc()</span></code>.</li> |
| <li>Assign the value of the associated macro <code class="docutils literal"><span class="pre">PSA_xxx_INIT</span></code>.</li> |
| <li>Assign the result of calling the associated function |
| <code class="docutils literal"><span class="pre">psa_xxx_init()</span></code>.</li> |
| </ul> |
| </div></blockquote> |
| <p>The resulting object is now <em>inactive</em>.</p> |
| <p>It is an error to initialize an operation object that is in <em>active</em> or |
| <em>error</em> states. This can leak memory or other resources.</p> |
| </li> |
| <li><p class="first"><strong>Setup:</strong> Start a new multi-part operation on an <em>inactive</em> operation |
| object. Each operation object will define one or more setup functions to |
| start a specific operation.</p> |
| <p>On success, a setup function will put an operation object into an <em>active</em> |
| state. On failure, the operation object will remain <em>inactive</em>.</p> |
| </li> |
| <li><p class="first"><strong>Update:</strong> Update an <em>active</em> operation object. The update function can |
| provide additional parameters, supply data for processing or generate |
| outputs.</p> |
| <p>On success, the operation object remains <em>active</em>. On failure, the |
| operation object will enter an <em>error</em> state.</p> |
| </li> |
| <li><p class="first"><strong>Finish:</strong> To end the operation, call the applicable finishing function. |
| This will take any final inputs, produce any final outputs, and then |
| release any resources associated with the operation.</p> |
| <p>On success, the operation object returns to the <em>inactive</em> state. On |
| failure, the operation object will enter an <em>error</em> state.</p> |
| </li> |
| </ol> |
| <p>An operation can be aborted at any stage during its use by calling the |
| associated <code class="docutils literal"><span class="pre">psa_xxx_abort()</span></code> function. This will release any resources |
| associated with the operation and return the operation object to the <em>inactive</em> |
| state.</p> |
| <p>Any error that occurs to an operation while it is in an <em>active</em> state will |
| result in the operation entering an <em>error</em> state. The application must call the |
| associated <code class="docutils literal"><span class="pre">psa_xxx_abort()</span></code> function to release the operation resources and |
| return the object to the <em>inactive</em> state.</p> |
| <p>Once an operation object is returned to the <em>inactive</em> state, it can be reused |
| by calling one of the applicable setup functions again.</p> |
| <p>If a multi-part operation object is not initialized before use, the behavior is |
| undefined.</p> |
| <p>If a multi-part operation function determines that the operation object is not in |
| any valid state, it can return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a>.</p> |
| <p>If a multi-part operation function is called with an operation object in the |
| wrong state, the function will return <a class="reference internal" href="../api/library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> and the operation |
| object will enter the <em>error</em> state.</p> |
| <p>It is safe to move a multi-part operation object to a different memory location, |
| for example, using a bitwise copy, and then to use the object in the new |
| location. For example, an application can allocate an operation object on the |
| stack and return it, or the operation object can be allocated within memory |
| managed by a garbage collector. However, this does not permit the following |
| behaviors:</p> |
| <ul class="simple"> |
| <li>Moving the object while a function is being called on the object. This is |
| not safe. See also <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>.</li> |
| <li>Working with both the original and the copied operation objects. This |
| requires cloning the operation, which is only available for hash operations |
| using <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_clone()</span></code></a>.</li> |
| </ul> |
| <p>Each type of multi-part operation can have multiple <em>active</em> states. |
| Documentation for the specific operation describes the configuration and update |
| functions, and any requirements about their usage and ordering.</p> |
| </div> |
| <div class="section" id="message-digests-hashes"> |
| <h3>Message digests (Hashes)</h3> |
| <p>The single-part hash functions are:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_compute" title="psa_hash_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compute()</span></code></a> to calculate the hash of a message.</li> |
| <li><a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_compare" title="psa_hash_compare"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_compare()</span></code></a> to compare the hash of a message with a reference value.</li> |
| </ul> |
| <p>The <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> |
| allows messages to be processed in fragments:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> object to zero, or by assigning the |
| value of the associated macro <a class="reference internal" href="../api/ops/hashes.html#c.PSA_HASH_OPERATION_INIT" title="PSA_HASH_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_setup" title="psa_hash_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_setup()</span></code></a> to specify the required hash algorithm, call |
| <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_clone" title="psa_hash_clone"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_clone()</span></code></a> to duplicate the state of <em>active</em> <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_operation_t" title="psa_hash_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_hash_operation_t</span></code></a> |
| object, or call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_resume" title="psa_hash_resume"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_resume()</span></code></a> to restart a hash operation with the |
| output from a previously suspended hash operation.</li> |
| <li>Call the <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_update" title="psa_hash_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_update()</span></code></a> function on successive chunks of the message.</li> |
| <li>At the end of the message, call the required finishing function:<ul> |
| <li>To suspend the hash operation and extract a hash suspend state, |
| call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_suspend" title="psa_hash_suspend"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_suspend()</span></code></a>. The output state can subsequently be used |
| to resume the hash operation.</li> |
| <li>To calculate the digest of a message, call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_finish" title="psa_hash_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_finish()</span></code></a>.</li> |
| <li>To verify the digest of a message against a reference value, call |
| <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_verify" title="psa_hash_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_verify()</span></code></a>.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/hashes.html#c.psa_hash_abort" title="psa_hash_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_hash_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="message-authentication-codes-macs"> |
| <h3>Message authentication codes (MACs)</h3> |
| <p>The single-part MAC functions are:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/ops/macs.html#c.psa_mac_compute" title="psa_mac_compute"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_compute()</span></code></a> to calculate the MAC of a message.</li> |
| <li><a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify" title="psa_mac_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify()</span></code></a> to compare the MAC of a message with a reference value.</li> |
| </ul> |
| <p>The <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> |
| allows messages to be processed in fragments:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_operation_t" title="psa_mac_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_mac_operation_t</span></code></a> object to zero, or by assigning the |
| value of the associated macro <a class="reference internal" href="../api/ops/macs.html#c.PSA_MAC_OPERATION_INIT" title="PSA_MAC_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_setup" title="psa_mac_sign_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_setup()</span></code></a> or <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_setup" title="psa_mac_verify_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_setup()</span></code></a> to specify the |
| algorithm and key.</li> |
| <li>Call the <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_update" title="psa_mac_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_update()</span></code></a> function on successive chunks of the message.</li> |
| <li>At the end of the message, call the required finishing function:<ul> |
| <li>To calculate the MAC of the message, call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_sign_finish" title="psa_mac_sign_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_sign_finish()</span></code></a>.</li> |
| <li>To verify the MAC of the message against a reference value, call |
| <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_verify_finish" title="psa_mac_verify_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_verify_finish()</span></code></a>.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/macs.html#c.psa_mac_abort" title="psa_mac_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_mac_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="encryption-and-decryption"> |
| <h3>Encryption and decryption</h3> |
| <div class="admonition note"> |
| <p class="first admonition-title">Note</p> |
| <p class="last">The unauthenticated cipher API is provided to implement legacy protocols and |
| for use cases where the data integrity and authenticity is guaranteed by |
| non-cryptographic means. It is recommended that newer protocols use |
| <em><a class="reference internal" href="#func-aead"><span class="std std-ref">Authenticated encryption (AEAD)</span></a></em>.</p> |
| </div> |
| <p>The single-part functions for encrypting or decrypting a message using an |
| unauthenticated symmetric cipher are:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt" title="psa_cipher_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt()</span></code></a> to encrypt a message using an unauthenticated symmetric |
| cipher. The encryption function generates a random IV. Use the multi-part API |
| to provide a deterministic IV: this is not secure in general, but |
| can be secure in some conditions that depend on the algorithm.</li> |
| <li><a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt" title="psa_cipher_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt()</span></code></a> to decrypt a message using an unauthenticated symmetric |
| cipher.</li> |
| </ul> |
| <p>The <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> |
| permits alternative initialization parameters and allows messages to be |
| processed in fragments:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero, or by assigning the |
| value of the associated macro <a class="reference internal" href="../api/ops/ciphers.html#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> or <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> to specify the |
| algorithm and key.</li> |
| <li>Provide additional parameters:<ul> |
| <li>When encrypting data, generate or set an initialization vector (IV), |
| nonce, or similar initial value such as an initial counter value. To |
| generate a random IV, which is recommended in most protocols, call |
| <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a>. To set the IV, call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>.</li> |
| <li>When decrypting, set the IV or nonce. To set the IV, call |
| <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a>.</li> |
| </ul> |
| </li> |
| <li>Call the <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> function on successive chunks of the message.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a> to complete the operation and return any final |
| output.</li> |
| </ol> |
| <p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_abort" title="psa_cipher_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_abort()</span></code></a>.</p> |
| </div> |
| <div class="section" id="authenticated-encryption-aead"> |
| <span id="func-aead"></span><h3>Authenticated encryption (AEAD)</h3> |
| <p>The single-part AEAD functions are:</p> |
| <ul class="simple"> |
| <li><a class="reference internal" href="../api/ops/aead.html#c.psa_aead_encrypt" title="psa_aead_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt()</span></code></a> to encrypt a message using an authenticated symmetric |
| cipher.</li> |
| <li><a class="reference internal" href="../api/ops/aead.html#c.psa_aead_decrypt" title="psa_aead_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt()</span></code></a> to decrypt a message using an authenticated symmetric |
| cipher.</li> |
| </ul> |
| <p>These functions follow the interface recommended by <a class="reference external" href="https://tools.ietf.org/html/rfc5116.html">RFC 5116</a>.</p> |
| <p>The encryption function requires a nonce to be provided. To generate a random |
| nonce, either call <a class="reference internal" href="../api/ops/rng.html#c.psa_generate_random" title="psa_generate_random"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_random()</span></code></a> or use the AEAD multi-part API.</p> |
| <p>The <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a> <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> |
| permits alternative initialization parameters and allows messages to be |
| processed in fragments:</p> |
| <ol class="arabic simple"> |
| <li>Initialize the <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_operation_t" title="psa_aead_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_aead_operation_t</span></code></a> object to zero, or by assigning the |
| value of the associated macro <a class="reference internal" href="../api/ops/aead.html#c.PSA_AEAD_OPERATION_INIT" title="PSA_AEAD_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_encrypt_setup" title="psa_aead_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_encrypt_setup()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_decrypt_setup" title="psa_aead_decrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the |
| algorithm and key.</li> |
| <li>Provide additional parameters:<ul> |
| <li>If the algorithm requires it, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the |
| length of the non-encrypted and encrypted inputs to the operation.</li> |
| <li>When encrypting, call either <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> or |
| <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce.</li> |
| <li>When decrypting, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_nonce" title="psa_aead_set_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_nonce()</span></code></a> to set the nonce.</li> |
| </ul> |
| </li> |
| <li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update_ad" title="psa_aead_update_ad"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update_ad()</span></code></a> zero or more times with fragments of the |
| non-encrypted additional data.</li> |
| <li>Call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_update" title="psa_aead_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_update()</span></code></a> zero or more times with fragments of the plaintext |
| or ciphertext to encrypt or decrypt.</li> |
| <li>At the end of the message, call the required finishing function:<ul> |
| <li>To complete an encryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_finish" title="psa_aead_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_finish()</span></code></a> to compute |
| and return authentication tag.</li> |
| <li>To complete a decryption operation, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> to |
| compute the authentication tag and verify it against a reference value.</li> |
| </ul> |
| </li> |
| </ol> |
| <p>To abort the operation or recover from an error, call <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_abort" title="psa_aead_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_abort()</span></code></a>.</p> |
| <p>Having a multi-part interface to authenticated encryption raises specific issues.</p> |
| <p>Multi-part authenticated decryption produces partial results that are not |
| authenticated. Applications must not use or expose partial results of |
| authenticated decryption until <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> has returned a success |
| status and must destroy all partial results without revealing them if |
| <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_verify" title="psa_aead_verify"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_verify()</span></code></a> returns a failure status. Revealing partial results, either directly or indirectly through the application’s behavior, can compromise the |
| confidentiality of all inputs that are encrypted with the same key.</p> |
| <p>For encryption, some common algorithms cannot be processed in a streaming |
| fashion. For SIV mode, the whole plaintext must be known before the encryption |
| can start; the multi-part AEAD API is not meant to be usable with SIV mode. For |
| CCM mode, the length of the plaintext must be known before the encryption can |
| start; the application can call the function <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_set_lengths" title="psa_aead_set_lengths"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_set_lengths()</span></code></a> to provide |
| these lengths before providing input.</p> |
| </div> |
| <div class="section" id="key-derivation"> |
| <span id="id5"></span><h3>Key derivation</h3> |
| <p>A key derivation encodes a deterministic method to generate a finite stream of |
| bytes. This data stream is computed by the cryptoprocessor and extracted in |
| chunks. If two key derivation operations are constructed with the same |
| parameters, then they produce the same output.</p> |
| <p>A key derivation consists of two phases:</p> |
| <ol class="arabic simple"> |
| <li>Input collection. This is sometimes known as <em>extraction</em>: the operation |
| “extracts” information from the inputs to generate a pseudorandom |
| intermediate secret value.</li> |
| <li>Output generation. This is sometimes known as <em>expansion</em>: the operation |
| “expands” the intermediate secret value to the desired output length.</li> |
| </ol> |
| <p>The specification defines a <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a> |
| API for key derivation that allows for multiple key and non-key outputs to be |
| extracted from a single derivation operation object.</p> |
| <p>In an implementation with <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">isolation</span></a>, the intermediate |
| state of the key derivation is not visible to the caller, and if an output of |
| the derivation is a non-exportable key, then this key cannot be recovered |
| outside the isolation boundary.</p> |
| <p>Applications use the <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a> type to create key |
| derivation operations. The operation object is used as follows:</p> |
| <ol class="arabic simple"> |
| <li>Initialize a <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a> object to zero or to |
| <a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_setup" title="psa_key_derivation_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_setup()</span></code></a> to select a key derivation algorithm.</li> |
| <li>Call the functions <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> and |
| <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a>, or <a class="reference internal" href="../api/ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> to |
| provide the inputs to the key derivation algorithm. Many key derivation |
| algorithms take multiple inputs; the <code class="docutils literal"><span class="pre">step</span></code> parameter to these functions |
| indicates which input is being provided. The documentation for each key |
| derivation algorithm describes the expected inputs for that algorithm and |
| in what order to pass them.</li> |
| <li>Optionally, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_set_capacity" title="psa_key_derivation_set_capacity"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_set_capacity()</span></code></a> to set a limit on the |
| amount of data that can be output from the key derivation operation.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create a derived key, or |
| <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to export the derived data. These |
| functions can be called multiple times to read successive output from the key |
| derivation, until the stream is exhausted when its capacity has been reached.</li> |
| <li>Key derivation does not finish in the same way as other multi-part |
| operations. Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation |
| operation memory when the object is no longer required.</li> |
| </ol> |
| <p>To recover from an error, call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key |
| derivation operation memory.</p> |
| <p>A key derivation operation cannot be rewound. Once a part of the stream has been |
| output, it cannot be output again. This ensures that the same part of the output |
| will not be used for different purposes.</p> |
| </div> |
| <div class="section" id="example-of-the-symmetric-cryptography-api"> |
| <h3>Example of the symmetric cryptography API</h3> |
| <p>Here is an example of a use case where a master key is used to generate both a |
| message encryption key and an IV for the encryption, and the derived key and IV |
| are then used to encrypt a message.</p> |
| <ol class="arabic simple"> |
| <li>Derive the message encryption material from the master key.<ol class="arabic"> |
| <li>Initialize a <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_operation_t" title="psa_key_derivation_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_derivation_operation_t</span></code></a> object to zero or to |
| <a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_OPERATION_INIT" title="PSA_KEY_DERIVATION_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_setup" title="psa_key_derivation_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_setup()</span></code></a> with <a class="reference internal" href="../api/ops/kdf.html#c.PSA_ALG_HKDF" title="PSA_ALG_HKDF"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_HKDF</span></code></a> as the algorithm.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_key" title="psa_key_derivation_input_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_key()</span></code></a> with the step |
| <a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_SECRET" title="PSA_KEY_DERIVATION_INPUT_SECRET"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> and the master key.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_input_bytes" title="psa_key_derivation_input_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> with the step |
| <a class="reference internal" href="../api/ops/kdf.html#c.PSA_KEY_DERIVATION_INPUT_INFO" title="PSA_KEY_DERIVATION_INPUT_INFO"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> and a public value that uniquely |
| identifies the message.</li> |
| <li>Populate a <a class="reference internal" href="../api/keys/attributes.html#c.psa_key_attributes_t" title="psa_key_attributes_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_key_attributes_t</span></code></a> object with the derived message |
| encryption key’s attributes.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_key" title="psa_key_derivation_output_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create the derived message key.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_output_bytes" title="psa_key_derivation_output_bytes"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to generate the derived IV.</li> |
| <li>Call <a class="reference internal" href="../api/ops/kdf.html#c.psa_key_derivation_abort" title="psa_key_derivation_abort"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation operation |
| memory.</li> |
| </ol> |
| </li> |
| <li>Encrypt the message with the derived material.<ol class="arabic"> |
| <li>Initialize a <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="xref any c c-type docutils literal"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero or to |
| <a class="reference internal" href="../api/ops/ciphers.html#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> with the derived message encryption key.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_set_iv" title="psa_cipher_set_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_set_iv()</span></code></a> using the derived IV retrieved above.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_update" title="psa_cipher_update"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_update()</span></code></a> one or more times to encrypt the message.</li> |
| <li>Call <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_finish" title="psa_cipher_finish"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_finish()</span></code></a> at the end of the message.</li> |
| </ol> |
| </li> |
| <li>Call <a class="reference internal" href="../api/keys/management.html#c.psa_destroy_key" title="psa_destroy_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_destroy_key()</span></code></a> to clear the generated key.</li> |
| </ol> |
| </div> |
| </div> |
| <div class="section" id="asymmetric-cryptography"> |
| <h2>Asymmetric cryptography</h2> |
| <p>This specification defines functions for asymmetric cryptography, including |
| asymmetric encryption, asymmetric signature, and two-way key agreement.</p> |
| <div class="section" id="asymmetric-encryption"> |
| <h3>Asymmetric encryption</h3> |
| <p>Asymmetric encryption is provided through the functions |
| <a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_encrypt" title="psa_asymmetric_encrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_encrypt()</span></code></a> and <a class="reference internal" href="../api/ops/pke.html#c.psa_asymmetric_decrypt" title="psa_asymmetric_decrypt"><code class="xref any c c-func docutils literal"><span class="pre">psa_asymmetric_decrypt()</span></code></a>.</p> |
| </div> |
| <div class="section" id="hash-and-sign"> |
| <h3>Hash-and-sign</h3> |
| <p>The signature and verification functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_message" title="psa_sign_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_message()</span></code></a> and |
| <a class="reference internal" href="../api/ops/sign.html#c.psa_verify_message" title="psa_verify_message"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_message()</span></code></a> take a message as one of their inputs and perform a |
| hash-and-sign algorithm.</p> |
| <p>The functions <a class="reference internal" href="../api/ops/sign.html#c.psa_sign_hash" title="psa_sign_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_sign_hash()</span></code></a> and <a class="reference internal" href="../api/ops/sign.html#c.psa_verify_hash" title="psa_verify_hash"><code class="xref any c c-func docutils literal"><span class="pre">psa_verify_hash()</span></code></a> take a message hash as |
| one of their inputs. This is useful for signing pre-computed hashes, or for |
| implementing hash-and-sign using a <a class="reference internal" href="../api/ops/hashes.html#hash-mp"><span class="std std-ref">multi-part hash operation</span></a> |
| before signing the resulting hash. To determine which |
| hash algorithm to use, call the macro <a class="reference internal" href="../api/keys/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the |
| corresponding signature algorithm.</p> |
| <p>Some hash-and-sign algorithms add padding to the message hash before completing |
| the signing operation. The format of the padding that is used depends on the |
| algorithm used to construct the signature.</p> |
| </div> |
| <div class="section" id="key-agreement"> |
| <h3>Key agreement</h3> |
| <p>This specification defines two functions for a Diffie-Hellman-style key |
| agreement where each party combines its own private key with the peer’s public |
| key.</p> |
| <p>The recommended approach is to use a <a class="reference internal" href="#key-derivation"><span class="std std-ref">key derivation |
| operation</span></a> with the <a class="reference internal" href="../api/ops/ka.html#c.psa_key_derivation_key_agreement" title="psa_key_derivation_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> |
| input function, which calculates a shared secret for the key derivation |
| function.</p> |
| <p>Where an application needs direct access to the shared secret, it can call |
| <a class="reference internal" href="../api/ops/ka.html#c.psa_raw_key_agreement" title="psa_raw_key_agreement"><code class="xref any c c-func docutils literal"><span class="pre">psa_raw_key_agreement()</span></code></a> instead. Note that in general the shared secret is not |
| directly suitable for use as a key because it is biased.</p> |
| </div> |
| </div> |
| <div class="section" id="randomness-and-key-generation"> |
| <h2>Randomness and key generation</h2> |
| <p>We strongly recommended that implementations include a random generator, |
| consisting of a cryptographically secure pseudo-random generator (CSPRNG), which |
| is adequately seeded with a cryptographic-quality hardware entropy source, |
| commonly referred to as a true random number generator (TRNG). Constrained |
| implementations can omit the random generation functionality if they do not |
| implement any algorithm that requires randomness internally, and they do not |
| provide a key generation functionality. For example, a special-purpose component |
| for signature verification can omit this.</p> |
| <p>It is recommended that applications use <a class="reference internal" href="../api/keys/management.html#c.psa_generate_key" title="psa_generate_key"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_key()</span></code></a>, |
| <a class="reference internal" href="../api/ops/ciphers.html#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv"><code class="xref any c c-func docutils literal"><span class="pre">psa_cipher_generate_iv()</span></code></a> or <a class="reference internal" href="../api/ops/aead.html#c.psa_aead_generate_nonce" title="psa_aead_generate_nonce"><code class="xref any c c-func docutils literal"><span class="pre">psa_aead_generate_nonce()</span></code></a> to generate |
| suitably-formatted random data, as applicable. In addition, the API includes a |
| function <a class="reference internal" href="../api/ops/rng.html#c.psa_generate_random" title="psa_generate_random"><code class="xref any c c-func docutils literal"><span class="pre">psa_generate_random()</span></code></a> to generate and extract arbitrary random data.</p> |
| </div> |
| </div> |
| |
| |
| </div> |
| </div> |
| </div> |
| <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> |
| <div class="sphinxsidebarwrapper"> |
| <h3><a href="../index.html">Table Of Contents</a></h3> |
| <ul> |
| <li><a class="reference internal" href="#">Functionality overview</a><ul> |
| <li><a class="reference internal" href="#library-management">Library management</a></li> |
| <li><a class="reference internal" href="#key-management">Key management</a><ul> |
| <li><a class="reference internal" href="#volatile-keys">Volatile keys</a></li> |
| <li><a class="reference internal" href="#persistent-keys">Persistent keys</a></li> |
| <li><a class="reference internal" href="#key-identifiers">Key identifiers</a></li> |
| <li><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">Recommendations of minimum standards for key management</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#usage-policies">Usage policies</a></li> |
| <li><a class="reference internal" href="#symmetric-cryptography">Symmetric cryptography</a><ul> |
| <li><a class="reference internal" href="#single-part-functions">Single-part Functions</a></li> |
| <li><a class="reference internal" href="#multi-part-operations">Multi-part operations</a></li> |
| <li><a class="reference internal" href="#message-digests-hashes">Message digests (Hashes)</a></li> |
| <li><a class="reference internal" href="#message-authentication-codes-macs">Message authentication codes (MACs)</a></li> |
| <li><a class="reference internal" href="#encryption-and-decryption">Encryption and decryption</a></li> |
| <li><a class="reference internal" href="#authenticated-encryption-aead">Authenticated encryption (AEAD)</a></li> |
| <li><a class="reference internal" href="#key-derivation">Key derivation</a></li> |
| <li><a class="reference internal" href="#example-of-the-symmetric-cryptography-api">Example of the symmetric cryptography API</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#asymmetric-cryptography">Asymmetric cryptography</a><ul> |
| <li><a class="reference internal" href="#asymmetric-encryption">Asymmetric encryption</a></li> |
| <li><a class="reference internal" href="#hash-and-sign">Hash-and-sign</a></li> |
| <li><a class="reference internal" href="#key-agreement">Key agreement</a></li> |
| </ul> |
| </li> |
| <li><a class="reference internal" href="#randomness-and-key-generation">Randomness and key generation</a></li> |
| </ul> |
| </li> |
| </ul> |
| <div class="relations"> |
| <h3>Related Topics</h3> |
| <ul> |
| <li><a href="../index.html">Documentation overview</a><ul> |
| <li>Previous: <a href="goals.html" title="previous chapter">Design goals</a></li> |
| <li>Next: <a href="sample-arch.html" title="next chapter">Sample architectures</a></li> |
| </ul></li> |
| </ul> |
| </div> |
| <div role="note" aria-label="source link"> |
| <h3>This Page</h3> |
| <ul class="this-page-menu"> |
| <li><a href="../_sources/overview/functionality.rst.txt" |
| rel="nofollow">Show Source</a></li> |
| </ul> |
| </div> |
| <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"> |
| © 2019-2020, 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> |
| |
| | |
| <a href="../_sources/overview/functionality.rst.txt" |
| rel="nofollow">Page source</a> |
| </div> |
| |
| |
| |
| |
| </body> |
| </html> |