TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / b0dbbb12c1b13fc6b262fa0ad65089a997bcd0d1 / . / docs / 1.0.1 / html / overview / functionality.html
blob: e8c74622cb4364fe8fd2da13d162a751957b715d [file] [log] [blame]
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]1
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]2<!DOCTYPE html>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]3
4<html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]6 <meta charset="utf-8" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]7 <title>3. Functionality overview &#8212; PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]8 <link rel="stylesheet" href="../_static/alabaster.css" type="text/css" />
9 <link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]10 <script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]11 <script type="text/javascript" src="../_static/jquery.js"></script>
12 <script type="text/javascript" src="../_static/underscore.js"></script>
13 <script type="text/javascript" src="../_static/doctools.js"></script>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]14 <script type="text/javascript" src="../_static/language_data.js"></script>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]15 <link rel="author" title="About these documents" href="../about.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]16 <link rel="index" title="Index" href="../genindex.html" />
17 <link rel="search" title="Search" href="../search.html" />
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]18 <link rel="next" title="4. Sample architectures" href="sample-arch.html" />
19 <link rel="prev" title="2. Design goals" href="goals.html" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]20
21 <link rel="stylesheet" href="../_static/custom.css" type="text/css" />
22
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]23
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]24 <meta name="viewport" content="width=device-width, initial-scale=0.9, maximum-scale=0.9" />
25
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]26 </head><body>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]27
28
29 <div class="document">
30 <div class="documentwrapper">
31 <div class="bodywrapper">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]32
33
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]34 <div class="body" role="main">
35
36 <div class="section" id="functionality-overview">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="id1"></span><h1>3. Functionality overview</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<p>This section provides a high-level overview of the functionality provided by the
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]39interface defined in this specification. Refer to the
40<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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]41<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
42specification.</p>
43<p>Due to the modularity of the interface, almost every part of the library is
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]44optional. 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 notranslate"><span class="pre">psa_crypto_init()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]45<div class="section" id="library-management">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<h2>3.1. Library management</h2>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]47<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 notranslate"><span class="pre">psa_crypto_init()</span></code></a> to initialize the library before
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]48using any other function.</p>
49</div>
50<div class="section" id="key-management">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]51<h2>3.2. Key management</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]52<p>Applications always access keys indirectly via an identifier, and can perform
53operations using a key without accessing the key material. This allows keys to
54be <em>non-extractable</em>, where an application can use a key but is not permitted to
55obtain the key material. Non-extractable keys are bound to the device, can be
56rate-limited and can have their usage restricted by policies.</p>
57<p>Each key has a set of attributes that describe the key and the policy for using
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]58the 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 notranslate"><span class="pre">psa_key_attributes_t</span></code></a> object contains all of the attributes, which
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]59is used when creating a key and when querying key attributes.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]60<p>The key attributes include:</p>
61<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]62<li><p>A <a class="reference internal" href="../api/keys/types.html#key-types"><span class="std std-ref">type</span></a> and size that describe the key material.</p></li>
63<li><p>The key <a class="reference internal" href="#key-ids"><span class="std std-ref">identifier</span></a> that the application uses to refer to the key.</p></li>
64<li><p>A <a class="reference internal" href="#key-life"><span class="std std-ref">lifetime</span></a> that determines when the key material is destroyed, and where it is stored.</p></li>
65<li><p>A <a class="reference internal" href="#key-usage-policies"><span class="std std-ref">policy</span></a> that determines how the key can be used.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]66</ul>
67<p>Keys are created using one of the <em>key creation functions</em>:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]68<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]69<li><p><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 notranslate"><span class="pre">psa_import_key()</span></code></a></p></li>
70<li><p><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 notranslate"><span class="pre">psa_generate_key()</span></code></a></p></li>
71<li><p><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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a></p></li>
72<li><p><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 notranslate"><span class="pre">psa_copy_key()</span></code></a></p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]73</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]74<p>These output the key identifier, that is used to access the key in all other parts of the API.</p>
75<p>All of the key attributes are set when the key is created and cannot be changed
76without destroying the key first. If the original key permits copying, then the
77application can specify a different lifetime or restricted policy for the
78copy of the key.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]79<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 notranslate"><span class="pre">psa_destroy_key()</span></code></a> destroys the key material, and will cause any active
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]80operations that are using the key to fail. Therefore an application must not
81destroy a key while an operation using that key is in progress, unless the
82application is prepared to handle a failure of the operation.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]83<div class="section" id="key-identifiers">
84<span id="key-ids"></span><h3>3.2.1. Key identifiers</h3>
85<p>Key identifiers are integral values that act as permanent names for persistent keys, or as transient references to volatile keys. Key identifiers are defined by the application for persistent keys, and by the implementation for volatile keys and for built-in keys.</p>
86<p>Key identifiers are output from a successful call to one of the key creation functions.</p>
87<p>Valid key identifiers must have distinct values within the same application. If
88the implementation provides <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">caller isolation</span></a>, then key
89identifiers are local to each application. That is, the same key identifier in two
90applications corresponds to two different keys.</p>
91<p>See <a class="reference internal" href="../api/keys/ids.html#key-identifiers"><span class="secref">Key identifiers</span></a>.</p>
92</div>
93<div class="section" id="key-lifetimes">
94<span id="key-life"></span><h3>3.2.2. Key lifetimes</h3>
95<p>The lifetime of a key indicates where it is stored and which application and system actions will create and destroy it.</p>
96<p>There are two main types of lifetimes: <em>volatile</em> and <em>persistent</em>.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]97<p>Volatile keys are automatically destroyed when the application instance terminates or on a power reset of the device. Volatile key identifiers are allocated by the implementation when the key is created. Volatile keys can be explicitly destroyed with 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 notranslate"><span class="pre">psa_destroy_key()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]98<p>Persistent keys are preserved until the application explicitly destroys them or until an implementation-specific device management event occurs, for example, a factory reset. The key identifier for a persistent key is set by the application when creating the key, and remains valid throughout the lifetime of the key, even if the application instance that created the key terminates.</p>
99<p>See <a class="reference internal" href="../api/keys/lifetimes.html#key-lifetimes"><span class="secref">Key lifetimes</span></a>.</p>
100</div>
101<div class="section" id="key-policies">
102<span id="key-usage-policies"></span><h3>3.2.3. Key policies</h3>
103<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. See <a class="reference internal" href="../api/keys/policy.html#key-policy"><span class="secref">Key policies</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]104</div>
105<div class="section" id="recommendations-of-minimum-standards-for-key-management">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]106<h3>3.2.4. Recommendations of minimum standards for key management</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]107<p>Most implementations provide the following functions:</p>
108<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]109<li><p><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 notranslate"><span class="pre">psa_import_key()</span></code></a>. The exceptions are implementations that only give access
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]110to a key or keys that are provisioned by proprietary means, and do not allow
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]111the main application to use its own cryptographic material.</p></li>
112<li><p><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 notranslate"><span class="pre">psa_get_key_attributes()</span></code></a> and the <code class="docutils literal notranslate"><span class="pre">psa_get_key_xxx()</span></code> accessor functions.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]113They are easy to implement, and it is difficult to write applications and to
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]114diagnose issues without being able to check the metadata.</p></li>
115<li><p><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 notranslate"><span class="pre">psa_export_public_key()</span></code></a>. This function is usually provided if the
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]116implementation supports any asymmetric algorithm, since public-key
117cryptography often requires the delivery of a public key that is associated
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]118with a protected private key.</p></li>
119<li><p><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 notranslate"><span class="pre">psa_export_key()</span></code></a>. However, highly constrained implementations that are
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]120designed to work only with short-term keys, or only with long-term
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]121non-extractable keys, do not need to provide this function.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]122</ul>
123</div>
124</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]125<div class="section" id="symmetric-cryptography">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]126<h2>3.3. Symmetric cryptography</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]127<p>This specification defines interfaces for the following types of symmetric
128cryptographic operation:</p>
129<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]130<li><p>Message digests, commonly known as hash functions.</p></li>
131<li><p>Message authentication codes (MAC).</p></li>
132<li><p>Symmetric ciphers.</p></li>
133<li><p>Authenticated encryption with associated data (AEAD).</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]134</ul>
135<p>For each type of symmetric cryptographic operation, the API includes:</p>
136<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]137<li><p>A pair of <em>single-part</em> functions. For example, compute and verify, or
138encrypt and decrypt.</p></li>
139<li><p>A series of functions that permit <em>multi-part operations</em>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]140</ul>
141<div class="section" id="single-part-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]142<h3>3.3.1. Single-part Functions</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]143<p>Single-part functions are APIs that implement the cryptographic operation in a
144single function call. This is the easiest API to use when all of the inputs and
145outputs fit into the application memory.</p>
146<p>Some use cases involve messages that are too large to be assembled in memory, or
147require non-default configuration of the algorithm. These use cases require the
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]148use of a <a class="reference internal" href="#multi-part-operations"><span class="secref">multi-part operation</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]149</div>
150<div class="section" id="multi-part-operations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]151<span id="id2"></span><h3>3.3.2. Multi-part operations</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]152<p>Multi-part operations are APIs which split a single cryptographic operation into
153a sequence of separate steps. This enables fine control over the configuration
154of the cryptographic operation, and allows the message data to be processed in
155fragments instead of all at once. For example, the following situations require
156the use of a multi-part operation:</p>
157<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]158<li><p>Processing messages that cannot be assembled in memory.</p></li>
159<li><p>Using a deterministic IV for unauthenticated encryption.</p></li>
160<li><p>Providing the IV separately for unauthenticated encryption or decryption.</p></li>
161<li><p>Separating the AEAD authentication tag from the cipher text.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]162</ul>
163<p>Each multi-part operation defines a specific object type to maintain the state
164of the operation. These types are implementation-defined. All multi-part
165operations follow the same pattern of use:</p>
166<ol class="arabic">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]167<li><p><strong>Allocate:</strong> Allocate memory for an operation object of the appropriate
168type. The application can use any allocation strategy: stack, heap, static, etc.</p></li>
169<li><p><strong>Initialize:</strong> Initialize or assign the operation object by one of the
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]170following methods:</p>
171<blockquote>
172<div><ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]173<li><p>Set it to logical zero. This is automatic for static and global
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]174variables. Explicit initialization must use the associated
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]175<code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code> macro as the type is implementation-defined.</p></li>
176<li><p>Set it to all-bits zero. This is automatic if the object was
177allocated with <code class="docutils literal notranslate"><span class="pre">calloc()</span></code>.</p></li>
178<li><p>Assign the value of the associated macro <code class="docutils literal notranslate"><span class="pre">PSA_xxx_INIT</span></code>.</p></li>
179<li><p>Assign the result of calling the associated function
180<code class="docutils literal notranslate"><span class="pre">psa_xxx_init()</span></code>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]181</ul>
182</div></blockquote>
183<p>The resulting object is now <em>inactive</em>.</p>
184<p>It is an error to initialize an operation object that is in <em>active</em> or
185<em>error</em> states. This can leak memory or other resources.</p>
186</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]187<li><p><strong>Setup:</strong> Start a new multi-part operation on an <em>inactive</em> operation
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]188object. Each operation object will define one or more setup functions to
189start a specific operation.</p>
190<p>On success, a setup function will put an operation object into an <em>active</em>
191state. On failure, the operation object will remain <em>inactive</em>.</p>
192</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]193<li><p><strong>Update:</strong> Update an <em>active</em> operation object. The update function can
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]194provide additional parameters, supply data for processing or generate
195outputs.</p>
196<p>On success, the operation object remains <em>active</em>. On failure, the
197operation object will enter an <em>error</em> state.</p>
198</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]199<li><p><strong>Finish:</strong> To end the operation, call the applicable finishing function.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]200This will take any final inputs, produce any final outputs, and then
201release any resources associated with the operation.</p>
202<p>On success, the operation object returns to the <em>inactive</em> state. On
203failure, the operation object will enter an <em>error</em> state.</p>
204</li>
205</ol>
206<p>An operation can be aborted at any stage during its use by calling the
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]207associated <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort()</span></code> function. This will release any resources
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]208associated with the operation and return the operation object to the <em>inactive</em>
209state.</p>
210<p>Any error that occurs to an operation while it is in an <em>active</em> state will
211result in the operation entering an <em>error</em> state. The application must call the
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]212associated <code class="docutils literal notranslate"><span class="pre">psa_xxx_abort()</span></code> function to release the operation resources and
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]213return the object to the <em>inactive</em> state.</p>
214<p>Once an operation object is returned to the <em>inactive</em> state, it can be reused
215by calling one of the applicable setup functions again.</p>
216<p>If a multi-part operation object is not initialized before use, the behavior is
217undefined.</p>
218<p>If a multi-part operation function determines that the operation object is not in
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]219any 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 notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]220<p>If a multi-part operation function is called with an operation object in the
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]221wrong 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 notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a> and the operation
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]222object will enter the <em>error</em> state.</p>
223<p>It is safe to move a multi-part operation object to a different memory location,
224for example, using a bitwise copy, and then to use the object in the new
225location. For example, an application can allocate an operation object on the
226stack and return it, or the operation object can be allocated within memory
227managed by a garbage collector. However, this does not permit the following
228behaviors:</p>
229<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]230<li><p>Moving the object while a function is being called on the object. This is
231not safe. See also <a class="reference internal" href="conventions.html#concurrency"><span class="std std-ref">Concurrent calls</span></a>.</p></li>
232<li><p>Working with both the original and the copied operation objects. This
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]233requires cloning the operation, which is only available for hash operations
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]234using <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 notranslate"><span class="pre">psa_hash_clone()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]235</ul>
236<p>Each type of multi-part operation can have multiple <em>active</em> states.
237Documentation for the specific operation describes the configuration and update
238functions, and any requirements about their usage and ordering.</p>
239</div>
240<div class="section" id="message-digests-hashes">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]241<h3>3.3.3. Message digests (Hashes)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]242<p>The single-part hash functions are:</p>
243<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]244<li><p><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 notranslate"><span class="pre">psa_hash_compute()</span></code></a> to calculate the hash of a message.</p></li>
245<li><p><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 notranslate"><span class="pre">psa_hash_compare()</span></code></a> to compare the hash of a message with a reference value.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]246</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]247<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]248allows messages to be processed in fragments:</p>
249<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]250<li><p>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 notranslate"><span class="pre">psa_hash_operation_t</span></code></a> object to zero, or by assigning the
251value 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 notranslate"><span class="pre">PSA_HASH_OPERATION_INIT</span></code></a>.</p></li>
252<li><p>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 notranslate"><span class="pre">psa_hash_setup()</span></code></a> to specify the required hash algorithm, call
253<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 notranslate"><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 notranslate"><span class="pre">psa_hash_operation_t</span></code></a>
254object, 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 notranslate"><span class="pre">psa_hash_resume()</span></code></a> to restart a hash operation with the
255output from a previously suspended hash operation.</p></li>
256<li><p>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 notranslate"><span class="pre">psa_hash_update()</span></code></a> function on successive chunks of the message.</p></li>
257<li><p>At the end of the message, call the required finishing function:</p>
258<ul class="simple">
259<li><p>To suspend the hash operation and extract a hash suspend state,
260call <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 notranslate"><span class="pre">psa_hash_suspend()</span></code></a>. The output state can subsequently be used
261to resume the hash operation.</p></li>
262<li><p>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 notranslate"><span class="pre">psa_hash_finish()</span></code></a>.</p></li>
263<li><p>To verify the digest of a message against a reference value, call
264<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 notranslate"><span class="pre">psa_hash_verify()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]265</ul>
266</li>
267</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]268<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 notranslate"><span class="pre">psa_hash_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]269</div>
270<div class="section" id="message-authentication-codes-macs">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]271<h3>3.3.4. Message authentication codes (MACs)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]272<p>The single-part MAC functions are:</p>
273<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]274<li><p><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 notranslate"><span class="pre">psa_mac_compute()</span></code></a> to calculate the MAC of a message.</p></li>
275<li><p><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 notranslate"><span class="pre">psa_mac_verify()</span></code></a> to compare the MAC of a message with a reference value.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]276</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]277<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]278allows messages to be processed in fragments:</p>
279<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]280<li><p>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 notranslate"><span class="pre">psa_mac_operation_t</span></code></a> object to zero, or by assigning the
281value 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 notranslate"><span class="pre">PSA_MAC_OPERATION_INIT</span></code></a>.</p></li>
282<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_mac_verify_setup()</span></code></a> to specify the
283algorithm and key.</p></li>
284<li><p>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 notranslate"><span class="pre">psa_mac_update()</span></code></a> function on successive chunks of the message.</p></li>
285<li><p>At the end of the message, call the required finishing function:</p>
286<ul class="simple">
287<li><p>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 notranslate"><span class="pre">psa_mac_sign_finish()</span></code></a>.</p></li>
288<li><p>To verify the MAC of the message against a reference value, call
289<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 notranslate"><span class="pre">psa_mac_verify_finish()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]290</ul>
291</li>
292</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]293<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 notranslate"><span class="pre">psa_mac_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]294</div>
295<div class="section" id="encryption-and-decryption">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]296<h3>3.3.5. Encryption and decryption</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]297<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]298<p class="admonition-title">Note</p>
299<p>The unauthenticated cipher API is provided to implement legacy protocols and
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]300for use cases where the data integrity and authenticity is guaranteed by
301non-cryptographic means. It is recommended that newer protocols use
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]302<a class="reference internal" href="#func-aead"><span class="secref">Authenticated encryption (AEAD)</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]303</div>
304<p>The single-part functions for encrypting or decrypting a message using an
305unauthenticated symmetric cipher are:</p>
306<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]307<li><p><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 notranslate"><span class="pre">psa_cipher_encrypt()</span></code></a> to encrypt a message using an unauthenticated symmetric
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]308cipher. The encryption function generates a random IV. Use the multi-part API
309to provide a deterministic IV: this is not secure in general, but
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]310can be secure in some conditions that depend on the algorithm.</p></li>
311<li><p><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 notranslate"><span class="pre">psa_cipher_decrypt()</span></code></a> to decrypt a message using an unauthenticated symmetric
312cipher.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]313</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]314<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]315permits alternative initialization parameters and allows messages to be
316processed in fragments:</p>
317<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]318<li><p>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 notranslate"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero, or by assigning the
319value 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 notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</p></li>
320<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_cipher_decrypt_setup()</span></code></a> to specify the
321algorithm and key.</p></li>
322<li><p>Provide additional parameters:</p>
323<ul class="simple">
324<li><p>When encrypting data, generate or set an initialization vector (IV),
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]325nonce, or similar initial value such as an initial counter value. To
326generate a random IV, which is recommended in most protocols, call
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]327<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 notranslate"><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 notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a>.</p></li>
328<li><p>When decrypting, set the IV or nonce. To set the IV, call
329<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 notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]330</ul>
331</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]332<li><p>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 notranslate"><span class="pre">psa_cipher_update()</span></code></a> function on successive chunks of the message.</p></li>
333<li><p>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 notranslate"><span class="pre">psa_cipher_finish()</span></code></a> to complete the operation and return any final
334output.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]335</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]336<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 notranslate"><span class="pre">psa_cipher_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]337</div>
338<div class="section" id="authenticated-encryption-aead">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]339<span id="func-aead"></span><h3>3.3.6. Authenticated encryption (AEAD)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]340<p>The single-part AEAD functions are:</p>
341<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]342<li><p><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 notranslate"><span class="pre">psa_aead_encrypt()</span></code></a> to encrypt a message using an authenticated symmetric
343cipher.</p></li>
344<li><p><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 notranslate"><span class="pre">psa_aead_decrypt()</span></code></a> to decrypt a message using an authenticated symmetric
345cipher.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]346</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]347<p>These functions follow the interface recommended by <span><em>An Interface and Algorithms for Authenticated Encryption</em> <a class="reference internal" href="../about.html#citation-rfc5116"><span class="cite">[RFC5116]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]348<p>The encryption function requires a nonce to be provided. To generate a random
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]349nonce, 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 notranslate"><span class="pre">psa_generate_random()</span></code></a> or use the AEAD multi-part API.</p>
350<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 notranslate"><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>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]351permits alternative initialization parameters and allows messages to be
352processed in fragments:</p>
353<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]354<li><p>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 notranslate"><span class="pre">psa_aead_operation_t</span></code></a> object to zero, or by assigning the
355value 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 notranslate"><span class="pre">PSA_AEAD_OPERATION_INIT</span></code></a>.</p></li>
356<li><p>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 notranslate"><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 notranslate"><span class="pre">psa_aead_decrypt_setup()</span></code></a> to specify the
357algorithm and key.</p></li>
358<li><p>Provide additional parameters:</p>
359<ul class="simple">
360<li><p>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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to specify the
361length of the non-encrypted and encrypted inputs to the operation.</p></li>
362<li><p>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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> or
363<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 notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a> to generate or set the nonce.</p></li>
364<li><p>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 notranslate"><span class="pre">psa_aead_set_nonce()</span></code></a> to set the nonce.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]365</ul>
366</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]367<li><p>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 notranslate"><span class="pre">psa_aead_update_ad()</span></code></a> zero or more times with fragments of the
368non-encrypted additional data.</p></li>
369<li><p>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 notranslate"><span class="pre">psa_aead_update()</span></code></a> zero or more times with fragments of the plaintext
370or ciphertext to encrypt or decrypt.</p></li>
371<li><p>At the end of the message, call the required finishing function:</p>
372<ul class="simple">
373<li><p>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 notranslate"><span class="pre">psa_aead_finish()</span></code></a> to compute
374and return authentication tag.</p></li>
375<li><p>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 notranslate"><span class="pre">psa_aead_verify()</span></code></a> to
376compute the authentication tag and verify it against a reference value.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]377</ul>
378</li>
379</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]380<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 notranslate"><span class="pre">psa_aead_abort()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]381<p>Having a multi-part interface to authenticated encryption raises specific issues.</p>
382<p>Multi-part authenticated decryption produces partial results that are not
383authenticated. Applications must not use or expose partial results of
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]384authenticated 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 notranslate"><span class="pre">psa_aead_verify()</span></code></a> has returned a success
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]385status and must destroy all partial results without revealing them if
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]386<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 notranslate"><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
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]387confidentiality of all inputs that are encrypted with the same key.</p>
388<p>For encryption, some common algorithms cannot be processed in a streaming
389fashion. For SIV mode, the whole plaintext must be known before the encryption
390can start; the multi-part AEAD API is not meant to be usable with SIV mode. For
391CCM mode, the length of the plaintext must be known before the encryption can
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]392start; 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 notranslate"><span class="pre">psa_aead_set_lengths()</span></code></a> to provide
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]393these lengths before providing input.</p>
394</div>
395<div class="section" id="key-derivation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]396<span id="id3"></span><h3>3.3.7. Key derivation</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]397<p>A key derivation encodes a deterministic method to generate a finite stream of
398bytes. This data stream is computed by the cryptoprocessor and extracted in
399chunks. If two key derivation operations are constructed with the same
400parameters, then they produce the same output.</p>
401<p>A key derivation consists of two phases:</p>
402<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]403<li><p>Input collection. This is sometimes known as <em>extraction</em>: the operation
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]404“extracts” information from the inputs to generate a pseudorandom
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]405intermediate secret value.</p></li>
406<li><p>Output generation. This is sometimes known as <em>expansion</em>: the operation
407“expands” the intermediate secret value to the desired output length.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]408</ol>
409<p>The specification defines a <a class="reference internal" href="#multi-part-operations"><span class="std std-ref">multi-part operation</span></a>
410API for key derivation that allows for multiple key and non-key outputs to be
411extracted from a single derivation operation object.</p>
412<p>In an implementation with <a class="reference internal" href="goals.html#isolation"><span class="std std-ref">isolation</span></a>, the intermediate
413state of the key derivation is not visible to the caller, and if an output of
414the derivation is a non-exportable key, then this key cannot be recovered
415outside the isolation boundary.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]416<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 notranslate"><span class="pre">psa_key_derivation_operation_t</span></code></a> type to create key
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]417derivation operations. The operation object is used as follows:</p>
418<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]419<li><p>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 notranslate"><span class="pre">psa_key_derivation_operation_t</span></code></a> object to zero or to
420<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</p></li>
421<li><p>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 notranslate"><span class="pre">psa_key_derivation_setup()</span></code></a> to select a key derivation algorithm.</p></li>
422<li><p>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 notranslate"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> and
423<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 notranslate"><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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> to
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]424provide the inputs to the key derivation algorithm. Many key derivation
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]425algorithms take multiple inputs; the <code class="docutils literal notranslate"><span class="pre">step</span></code> parameter to these functions
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]426indicates which input is being provided. The documentation for each key
427derivation algorithm describes the expected inputs for that algorithm and
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]428in what order to pass them.</p></li>
429<li><p>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 notranslate"><span class="pre">psa_key_derivation_set_capacity()</span></code></a> to set a limit on the
430amount of data that can be output from the key derivation operation.</p></li>
431<li><p>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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create a derived key, or
432<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 notranslate"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to export the derived data. These
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]433functions can be called multiple times to read successive output from the key
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]434derivation, until the stream is exhausted when its capacity has been reached.</p></li>
435<li><p>Key derivation does not finish in the same way as other multi-part
436operations. 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 notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation
437operation memory when the object is no longer required.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]438</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]439<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 notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]440derivation operation memory.</p>
441<p>A key derivation operation cannot be rewound. Once a part of the stream has been
442output, it cannot be output again. This ensures that the same part of the output
443will not be used for different purposes.</p>
444</div>
445<div class="section" id="example-of-the-symmetric-cryptography-api">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]446<h3>3.3.8. Example of the symmetric cryptography API</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]447<p>Here is an example of a use case where a master key is used to generate both a
448message encryption key and an IV for the encryption, and the derived key and IV
449are then used to encrypt a message.</p>
450<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]451<li><p>Derive the message encryption material from the master key.</p>
452<ol class="loweralpha simple">
453<li><p>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 notranslate"><span class="pre">psa_key_derivation_operation_t</span></code></a> object to zero or to
454<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_OPERATION_INIT</span></code></a>.</p></li>
455<li><p>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 notranslate"><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 notranslate"><span class="pre">PSA_ALG_HKDF</span></code></a> as the algorithm.</p></li>
456<li><p>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 notranslate"><span class="pre">psa_key_derivation_input_key()</span></code></a> with the step
457<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_SECRET</span></code></a> and the master key.</p></li>
458<li><p>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 notranslate"><span class="pre">psa_key_derivation_input_bytes()</span></code></a> with the step
459<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 notranslate"><span class="pre">PSA_KEY_DERIVATION_INPUT_INFO</span></code></a> and a public value that uniquely
460identifies the message.</p></li>
461<li><p>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 notranslate"><span class="pre">psa_key_attributes_t</span></code></a> object with the derived message
462encryption key’s attributes.</p></li>
463<li><p>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 notranslate"><span class="pre">psa_key_derivation_output_key()</span></code></a> to create the derived message key.</p></li>
464<li><p>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 notranslate"><span class="pre">psa_key_derivation_output_bytes()</span></code></a> to generate the derived IV.</p></li>
465<li><p>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 notranslate"><span class="pre">psa_key_derivation_abort()</span></code></a> to release the key derivation operation
466memory.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]467</ol>
468</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]469<li><p>Encrypt the message with the derived material.</p>
470<ol class="loweralpha simple">
471<li><p>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 notranslate"><span class="pre">psa_cipher_operation_t</span></code></a> object to zero or to
472<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 notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code></a>.</p></li>
473<li><p>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 notranslate"><span class="pre">psa_cipher_encrypt_setup()</span></code></a> with the derived message encryption key.</p></li>
474<li><p>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 notranslate"><span class="pre">psa_cipher_set_iv()</span></code></a> using the derived IV retrieved above.</p></li>
475<li><p>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 notranslate"><span class="pre">psa_cipher_update()</span></code></a> one or more times to encrypt the message.</p></li>
476<li><p>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 notranslate"><span class="pre">psa_cipher_finish()</span></code></a> at the end of the message.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]477</ol>
478</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]479<li><p>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 notranslate"><span class="pre">psa_destroy_key()</span></code></a> to clear the generated key.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]480</ol>
481</div>
482</div>
483<div class="section" id="asymmetric-cryptography">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]484<h2>3.4. Asymmetric cryptography</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]485<p>This specification defines functions for asymmetric cryptography, including
486asymmetric encryption, asymmetric signature, and two-way key agreement.</p>
487<div class="section" id="asymmetric-encryption">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]488<h3>3.4.1. Asymmetric encryption</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]489<p>Asymmetric encryption is provided through the functions
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]490<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 notranslate"><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 notranslate"><span class="pre">psa_asymmetric_decrypt()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]491</div>
492<div class="section" id="hash-and-sign">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]493<h3>3.4.2. Hash-and-sign</h3>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]494<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 notranslate"><span class="pre">psa_sign_message()</span></code></a> and
495<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 notranslate"><span class="pre">psa_verify_message()</span></code></a> take a message as one of their inputs and perform a
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]496hash-and-sign algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]497<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 notranslate"><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 notranslate"><span class="pre">psa_verify_hash()</span></code></a> take a message hash as
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]498one of their inputs. This is useful for signing pre-computed hashes, or for
499implementing 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>
500before signing the resulting hash. To determine which
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]501hash algorithm to use, call the macro <a class="reference internal" href="../api/ops/algorithms.html#c.PSA_ALG_GET_HASH" title="PSA_ALG_GET_HASH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_GET_HASH()</span></code></a> on the
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]502corresponding signature algorithm.</p>
503<p>Some hash-and-sign algorithms add padding to the message hash before completing
504the signing operation. The format of the padding that is used depends on the
505algorithm used to construct the signature.</p>
506</div>
507<div class="section" id="key-agreement">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]508<h3>3.4.3. Key agreement</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]509<p>This specification defines two functions for a Diffie-Hellman-style key
510agreement where each party combines its own private key with the peer’s public
511key.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]512<p>The recommended approach is to use a
513<a class="reference internal" href="#key-derivation"><span class="std std-ref">key derivation operation</span></a> with the
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]514<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 notranslate"><span class="pre">psa_key_derivation_key_agreement()</span></code></a> input function, which calculates a shared
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]515secret for the key derivation function.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]516<p>Where an application needs direct access to the shared secret, it can call
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]517<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 notranslate"><span class="pre">psa_raw_key_agreement()</span></code></a> instead. Note that in general the shared secret is not
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]518directly suitable for use as a key because it is biased.</p>
519</div>
520</div>
521<div class="section" id="randomness-and-key-generation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]522<h2>3.5. Randomness and key generation</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]523<p>We strongly recommended that implementations include a random generator,
524consisting of a cryptographically secure pseudo-random generator (CSPRNG), which
525is adequately seeded with a cryptographic-quality hardware entropy source,
526commonly referred to as a true random number generator (TRNG). Constrained
527implementations can omit the random generation functionality if they do not
528implement any algorithm that requires randomness internally, and they do not
529provide a key generation functionality. For example, a special-purpose component
530for signature verification can omit this.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]531<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 notranslate"><span class="pre">psa_generate_key()</span></code></a>,
532<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 notranslate"><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 notranslate"><span class="pre">psa_aead_generate_nonce()</span></code></a> to generate
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]533suitably-formatted random data, as applicable. In addition, the API includes a
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]534function <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 notranslate"><span class="pre">psa_generate_random()</span></code></a> to generate and extract arbitrary random data.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]535</div>
536</div>
537
538
539 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]540
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]541 </div>
542 </div>
543 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]544 <div class="sphinxsidebarwrapper"><h3><a href="../index.html"><b>PSA Crypto API</b></a></h3>
545IHI 0086<br/>
546Non-confidential<br/>
547Version 1.0.1
548<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]549<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]550<li class="toctree-l1"><a class="reference internal" href="../about.html">About this document</a></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]551</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]552<ul class="current">
553<li class="toctree-l1"><a class="reference internal" href="intro.html">1. Introduction</a></li>
554<li class="toctree-l1"><a class="reference internal" href="goals.html">2. Design goals</a></li>
555<li class="toctree-l1 current"><a class="current reference internal" href="#">3. Functionality overview</a><ul>
556<li class="toctree-l2"><a class="reference internal" href="#library-management">3.1. Library management</a></li>
557<li class="toctree-l2"><a class="reference internal" href="#key-management">3.2. Key management</a><ul>
558<li class="toctree-l3"><a class="reference internal" href="#key-identifiers">3.2.1. Key identifiers</a></li>
559<li class="toctree-l3"><a class="reference internal" href="#key-lifetimes">3.2.2. Key lifetimes</a></li>
560<li class="toctree-l3"><a class="reference internal" href="#key-policies">3.2.3. Key policies</a></li>
561<li class="toctree-l3"><a class="reference internal" href="#recommendations-of-minimum-standards-for-key-management">3.2.4. Recommendations of minimum standards for key management</a></li>
562</ul>
563</li>
564<li class="toctree-l2"><a class="reference internal" href="#symmetric-cryptography">3.3. Symmetric cryptography</a><ul>
565<li class="toctree-l3"><a class="reference internal" href="#single-part-functions">3.3.1. Single-part Functions</a></li>
566<li class="toctree-l3"><a class="reference internal" href="#multi-part-operations">3.3.2. Multi-part operations</a></li>
567<li class="toctree-l3"><a class="reference internal" href="#message-digests-hashes">3.3.3. Message digests (Hashes)</a></li>
568<li class="toctree-l3"><a class="reference internal" href="#message-authentication-codes-macs">3.3.4. Message authentication codes (MACs)</a></li>
569<li class="toctree-l3"><a class="reference internal" href="#encryption-and-decryption">3.3.5. Encryption and decryption</a></li>
570<li class="toctree-l3"><a class="reference internal" href="#authenticated-encryption-aead">3.3.6. Authenticated encryption (AEAD)</a></li>
571<li class="toctree-l3"><a class="reference internal" href="#key-derivation">3.3.7. Key derivation</a></li>
572<li class="toctree-l3"><a class="reference internal" href="#example-of-the-symmetric-cryptography-api">3.3.8. Example of the symmetric cryptography API</a></li>
573</ul>
574</li>
575<li class="toctree-l2"><a class="reference internal" href="#asymmetric-cryptography">3.4. Asymmetric cryptography</a><ul>
576<li class="toctree-l3"><a class="reference internal" href="#asymmetric-encryption">3.4.1. Asymmetric encryption</a></li>
577<li class="toctree-l3"><a class="reference internal" href="#hash-and-sign">3.4.2. Hash-and-sign</a></li>
578<li class="toctree-l3"><a class="reference internal" href="#key-agreement">3.4.3. Key agreement</a></li>
579</ul>
580</li>
581<li class="toctree-l2"><a class="reference internal" href="#randomness-and-key-generation">3.5. Randomness and key generation</a></li>
582</ul>
583</li>
584<li class="toctree-l1"><a class="reference internal" href="sample-arch.html">4. Sample architectures</a></li>
585<li class="toctree-l1"><a class="reference internal" href="conventions.html">5. Library conventions</a></li>
586<li class="toctree-l1"><a class="reference internal" href="implementation.html">6. Implementation considerations</a></li>
587<li class="toctree-l1"><a class="reference internal" href="usage.html">7. Usage considerations</a></li>
588<li class="toctree-l1"><a class="reference internal" href="../api/library/index.html">8. Library management reference</a></li>
589<li class="toctree-l1"><a class="reference internal" href="../api/keys/index.html">9. Key management reference</a></li>
590<li class="toctree-l1"><a class="reference internal" href="../api/ops/index.html">10. Cryptographic operation reference</a></li>
591</ul>
592<ul>
593<li class="toctree-l1"><a class="reference internal" href="../appendix/example_header.html">Example header file</a></li>
594<li class="toctree-l1"><a class="reference internal" href="../appendix/specdef_values.html">Example macro implementations</a></li>
595<li class="toctree-l1"><a class="reference internal" href="../appendix/history.html">Changes to the API</a></li>
596</ul>
597<ul>
598<li class="toctree-l1"><a class="reference internal" href="../psa_c-identifiers.html">Index of API elements</a></li>
599</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]600<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]601 <h3 id="searchlabel">Quick search</h3>
602 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]603 <form class="search" action="../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]604 <input type="text" name="q" aria-labelledby="searchlabel" />
605 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]606 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]607 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]608</div>
609<script type="text/javascript">$('#searchbox').show(0);</script>
610 </div>
611 </div>
612 <div class="clearer"></div>
613 </div>
614 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]615 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]616
617 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame]618 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
619 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]620
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]621 </div>
622
623
624
625
626 </body>
627</html>