TrustedFirmware Git Browser
Code Review Sign In
review.trustedfirmware.org / mirror / mbed-crypto / e26ccadad2903200a70e2bda85902c009246a59a / . / docs / html / api / ops / ciphers.html
blob: b9f7270d1197c208f2fa537fb8ad2988296e1365 [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>10.4. Unauthenticated ciphers &#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="10.5. Authenticated encryption with associated data (AEAD)" href="aead.html" />
19 <link rel="prev" title="10.3. Message authentication codes (MAC)" href="macs.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="unauthenticated-ciphers">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]37<span id="ciphers"></span><h1>10.4. Unauthenticated ciphers</h1>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]38<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]39<p class="admonition-title">Warning</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]40<p>The unauthenticated cipher API is provided to implement legacy protocols and
41for use cases where the data integrity and authenticity is guaranteed by
42non-cryptographic means.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]43<p>It is recommended that newer protocols use <a class="reference internal" href="aead.html#aead"><span class="secref">Authenticated encryption with associated data (AEAD)</span></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]44</div>
45<div class="section" id="cipher-algorithms">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]46<span id="id1"></span><h2>10.4.1. Cipher algorithms</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]47<div class="section" id="PSA_ALG_STREAM_CIPHER">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]48<span id="c.PSA_ALG_STREAM_CIPHER"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]49<p>The stream cipher mode of a stream cipher algorithm.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]50<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER">PSA_ALG_STREAM_CIPHER</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04800100)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]51<p>The underlying stream cipher is determined by the key type. The ARC4 and ChaCha20 ciphers use this algorithm identifier.</p>
52<p class="rubric">ARC4</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]53<p>To use ARC4, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_ARC4" title="PSA_KEY_TYPE_ARC4"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_ARC4</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]54<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]55<p class="admonition-title">Warning</p>
56<p>The ARC4 cipher is weak and deprecated and is only recommended for use in legacy protocols.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]57</div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]58<p>The ARC4 cipher does not use an initialization vector (IV). When using a multi-part cipher operation with the <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a> algorithm and an ARC4 key, <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not be called.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]59<p class="rubric">ChaCha20</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]60<p>To use ChaCha20, use a key type of <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_CHACHA20" title="PSA_KEY_TYPE_CHACHA20"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_CHACHA20</span></code></a> and algorithm id <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]61<p>Implementations must support the variant that is defined in <span><em>ChaCha20 and Poly1305 for IETF Protocols</em> <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc7539.html#section-2.4">§2.4</a>, which has a 96-bit nonce and a 32-bit counter. Implementations can optionally also support the original variant, as defined in <span><em>ChaCha, a variant of Salsa20</em> <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a></span>, which has a 64-bit nonce and a 64-bit counter. Except where noted, the <a class="reference internal" href="../../about.html#citation-rfc7539"><span class="cite">[RFC7539]</span></a> variant must be used.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]62<p>ChaCha20 defines a nonce and an initial counter to be provided to the encryption and decryption operations. When using a ChaCha20 key with the <a class="reference internal" href="#c.PSA_ALG_STREAM_CIPHER" title="PSA_ALG_STREAM_CIPHER"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_STREAM_CIPHER</span></code></a> algorithm, these values are provided using the initialization vector (IV) functions in the following ways:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]63<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]64<li><p>A call to <a class="reference internal" href="#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> will generate a random 12-byte nonce, and set the counter value to zero. The random nonce is output as a 12-byte IV value in the output.</p></li>
65<li><p>A call to <a class="reference internal" href="#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> will use first 12 bytes of the input buffer as the nonce and set the counter value to zero.</p></li>
66<li><p>A call to <a class="reference internal" href="#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> on a multi-part cipher operation will generate and return a random 12-byte nonce and set the counter value to zero.</p></li>
67<li><p>A call to <a class="reference internal" href="#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> on a multi-part cipher operation can support the following IV sizes:</p>
68<ul>
69<li><p>12 bytes: the provided IV is used as the nonce, and the counter value is set to zero.</p></li>
70<li><p>16 bytes: the first four bytes of the IV are used as the counter value (encoded as little-endian), and the remaining 12 bytes is used as the nonce.</p></li>
71<li><p>8 bytes: the cipher operation uses the original <a class="reference internal" href="../../about.html#citation-chacha20"><span class="cite">[CHACHA20]</span></a> definition of ChaCha20: the provided IV is used as the 64-bit nonce, and the 64-bit counter value is set to zero.</p></li>
72<li><p>It is recommended that implementations do not support other sizes of IV.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]73</ul>
74</li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]75</ul>
76</div>
77<div class="section" id="PSA_ALG_CTR">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]78<span id="c.PSA_ALG_CTR"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CTR</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]79<p>A stream cipher built using the Counter (CTR) mode of a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]80<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR">PSA_ALG_CTR</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01000)</pre>
81<p>CTR is a stream cipher which is built from a block cipher. The underlying block cipher is determined by the key type. For example, to use AES-128-CTR, use this algorithm with a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code></a> and a size of 128 bits (16 bytes).</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]82<p>The CTR block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
83<p>CTR mode requires a <em>counter block</em> which is the same size as the cipher block length. The counter block is updated for each block (or a partial final block) that is encrypted or decrypted.</p>
84<p>A counter block value must only be used once across all messages encrypted using the same key value. This is typically achieved by splitting the counter block into a nonce, which is unique among all message encrypted with the key, and a counter which is incremented for each block of a message.</p>
85<p>For example, when using AES-CTR encryption, which uses a 16-byte block, the application can provide a 12-byte nonce when setting the IV. This leaves 4 bytes for the counter, allowing up to 2^32 blocks (64GB) of message data to be encrypted in each message.</p>
86<p>The first counter block is constructed from the initialization vector (IV). The initial counter block is is constructed in the following ways:</p>
87<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]88<li><p>A call to <a class="reference internal" href="#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> will generate a random counter block value. This is the first block of output.</p></li>
89<li><p>A call to <a class="reference internal" href="#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> will use first block of the input buffer as the initial counter block value.</p></li>
90<li><p>A call to <a class="reference internal" href="#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> on a multi-part cipher operation will generate and return a random counter block value.</p></li>
91<li><p>A call to <a class="reference internal" href="#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> on a multi-part cipher operation requires an IV must be between <code class="docutils literal notranslate"><span class="pre">1</span></code> and <em>n</em> bytes in length, where <em>n</em> is the cipher block length. The counter block is initialized using the IV, and padded with zero bytes up to the block length.</p></li>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]92</ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]93<p>During the counter block update operation, the counter block is treated as a single big-endian encoded integer and the update operation increments this integer by <code class="docutils literal notranslate"><span class="pre">1</span></code>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]94<p>This scheme meets the recommendations in Appendix B of <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite psa_c psa_c-cite">[SP800-38A]</span></a>.</p>
95<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]96<p class="admonition-title">Note</p>
97<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]98</div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]99</div>
100<div class="section" id="PSA_ALG_CFB">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]101<span id="c.PSA_ALG_CFB"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CFB</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]102<p>A stream cipher built using the Cipher Feedback (CFB) mode of a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]103<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB">PSA_ALG_CFB</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01100)</pre>
104<p>The underlying block cipher is determined by the key type. This is the variant of CFB where each iteration encrypts or decrypts a segment of the input that is the same length as the cipher block size. For example, using <a class="reference internal" href="#c.PSA_ALG_CFB" title="PSA_ALG_CFB"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_CFB</span></code></a> with a key of type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code></a> will result in the AES-CFB-128 cipher.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]105<p>CFB mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
106<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]107<p class="admonition-title">Note</p>
108<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]109</div>
110<p>The CFB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>, using a segment size <em>s</em> equal to the block size <em>b</em>. The definition in <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite psa_c psa_c-cite">[SP800-38A]</span></a> is extended to allow an incomplete final block of input, in which case the algorithm discards the final bytes of the key stream when encrypting or decrypting the final partial block.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]111</div>
112<div class="section" id="PSA_ALG_OFB">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]113<span id="c.PSA_ALG_OFB"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_OFB</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]114<p>A stream cipher built using the Output Feedback (OFB) mode of a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]115<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_OFB" title="PSA_ALG_OFB">PSA_ALG_OFB</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04c01200)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]116<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]117<p>OFB mode requires an initialization vector (IV) that is the same size as the cipher block length. OFB mode requires that the IV is a nonce, and must be unique for each use of the mode with the same key.</p>
118<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]119<p class="admonition-title">Note</p>
120<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]121</div>
122<p>The OFB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]123</div>
124<div class="section" id="PSA_ALG_XTS">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]125<span id="c.PSA_ALG_XTS"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_XTS</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]126<p>The XEX with Ciphertext Stealing (XTS) cipher mode of a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]127<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_XTS" title="PSA_ALG_XTS">PSA_ALG_XTS</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x0440ff00)</pre>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]128<p>XTS is a cipher mode which is built from a block cipher, designed for use in disk encryption. It requires at least one full cipher block length of input, but beyond this minimum the input does not need to be a whole number of blocks.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]129<p>XTS mode uses two keys for the underlying block cipher. These are provided by using a key that is twice the normal key size for the cipher. For example, to use AES-256-XTS the application must create a key with type <a class="reference internal" href="../keys/types.html#c.PSA_KEY_TYPE_AES" title="PSA_KEY_TYPE_AES"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_TYPE_AES</span></code></a> and bit size <code class="docutils literal notranslate"><span class="pre">512</span></code>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]130<p>XTS mode requires an initialization vector (IV) that is the same size as the cipher block length. The IV for XTS is typically defined to be the sector number of the disk block being encrypted or decrypted.</p>
131<p>The XTS block cipher mode is defined in <span><em>1619-2018 - IEEE Standard for Cryptographic Protection of Data on Block-Oriented Storage Devices</em> <a class="reference internal" href="../../about.html#citation-ieee-xts"><span class="cite">[IEEE-XTS]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]132</div>
133<div class="section" id="PSA_ALG_ECB_NO_PADDING">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]134<span id="c.PSA_ALG_ECB_NO_PADDING"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_ECB_NO_PADDING</span></code> (macro)</h3>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]135<p>The Electronic Codebook (ECB) mode of a block cipher, with no padding.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]136<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_ECB_NO_PADDING" title="PSA_ALG_ECB_NO_PADDING">PSA_ALG_ECB_NO_PADDING</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404400)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]137<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]138<p class="admonition-title">Warning</p>
139<p>ECB mode does not protect the confidentiality of the encrypted data except in extremely narrow circumstances. It is recommended that applications only use ECB if they need to construct an operating mode that the implementation does not provide. Implementations are encouraged to provide the modes that applications need in preference to supporting direct access to ECB.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]140</div>
141<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]142<p>This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]143<p>ECB mode does not accept an initialization vector (IV). When using a multi-part cipher operation with this algorithm, <a class="reference internal" href="#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> and <a class="reference internal" href="#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> must not be called.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]144<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]145<p class="admonition-title">Note</p>
146<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]147</div>
148<p>The ECB block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]149</div>
150<div class="section" id="PSA_ALG_CBC_NO_PADDING">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]151<span id="c.PSA_ALG_CBC_NO_PADDING"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CBC_NO_PADDING</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]152<p>The Cipher Block Chaining (CBC) mode of a block cipher, with no padding.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]153<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_CBC_NO_PADDING" title="PSA_ALG_CBC_NO_PADDING">PSA_ALG_CBC_NO_PADDING</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404000)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]154<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]155<p>This symmetric cipher mode can only be used with messages whose lengths are a multiple of the block size of the chosen block cipher.</p>
156<p>CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
157<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]158<p class="admonition-title">Note</p>
159<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]160</div>
161<p>The CBC block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]162</div>
163<div class="section" id="PSA_ALG_CBC_PKCS7">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]164<span id="c.PSA_ALG_CBC_PKCS7"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_CBC_PKCS7</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]165<p>The Cipher Block Chaining (CBC) mode of a block cipher, with PKCS#7 padding.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]166<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_CBC_PKCS7" title="PSA_ALG_CBC_PKCS7">PSA_ALG_CBC_PKCS7</a> ((<a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a>)0x04404100)</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]167<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]168<p>CBC mode requires an initialization vector (IV) that is the same size as the cipher block length.</p>
169<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]170<p class="admonition-title">Note</p>
171<p>The cipher block length can be determined using <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]172</div>
173<p>The CBC block cipher mode is defined in <span><em>NIST Special Publication 800-38A: Recommendation for Block Cipher Modes of Operation: Methods and Techniques</em> <a class="reference internal" href="../../about.html#citation-sp800-38a"><span class="cite">[SP800-38A]</span></a></span>. The padding operation is defined by <span><em>PKCS #7: Cryptographic Message Syntax Version 1.5</em> <a class="reference internal" href="../../about.html#citation-rfc2315"><span class="cite">[RFC2315]</span></a></span> <a class="reference external" href="https://tools.ietf.org/html/rfc2315.html#section-10.3">§10.3</a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]174</div>
175</div>
176<div class="section" id="single-part-cipher-functions">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]177<h2>10.4.2. Single-part cipher functions</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]178<div class="section" id="psa_cipher_encrypt">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]179<span id="c.psa_cipher_encrypt"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]180<p>Encrypt a message using a symmetric cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]181<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_encrypt" title="psa_cipher_encrypt">psa_cipher_encrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]182 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]183 const uint8_t * input,
184 size_t input_length,
185 uint8_t * output,
186 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]187 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]188<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]189<dl class="simple">
190<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation.
191It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</p>
192</dd>
193<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The cipher algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
194</dd>
195<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message to encrypt.</p>
196</dd>
197<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
198</dd>
199<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper.</p>
200</dd>
201<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
202<ul class="simple">
203<li><p>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
204<li><p><a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher encryption.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]205</ul>
206</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]207<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the output.</p>
208</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]209</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]210<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
211<dl class="simple">
212<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
213</dd>
214<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
215<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
216</dd>
217<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
218</dd>
219<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">input_length</span></code> is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</p>
220</dd>
221<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</p>
222</dd>
223<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">output_size</span></code> is too small. <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
224</dd>
225<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
226<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
227<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
228<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
229<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
230<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
231<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
232<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
233</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]234</dl>
235<p class="rubric">Description</p>
236<p>This function encrypts a message with a random initialization vector (IV).
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]237The length of the IV is <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.
238The output of <a class="reference internal" href="#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> is the IV followed by the ciphertext.</p>
239<p>Use the multi-part operation interface with a <a class="reference internal" href="#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 provide other forms of IV or to manage the IV and ciphertext independently.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]240</div>
241<div class="section" id="psa_cipher_decrypt">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]242<span id="c.psa_cipher_decrypt"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]243<p>Decrypt a message using a symmetric cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]244<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_decrypt" title="psa_cipher_decrypt">psa_cipher_decrypt</a>(<a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]245 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]246 const uint8_t * input,
247 size_t input_length,
248 uint8_t * output,
249 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]250 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]251<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]252<dl class="simple">
253<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
254It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</p>
255</dd>
256<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The cipher algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
257</dd>
258<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.</p>
259</dd>
260<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
261</dd>
262<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the plaintext is to be written.</p>
263</dd>
264<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
265<ul class="simple">
266<li><p>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p></li>
267<li><p><a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher decryption.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]268</ul>
269</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]270<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the output.</p>
271</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]272</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]273<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
274<dl class="simple">
275<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
276</dd>
277<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
278<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
279</dd>
280<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
281</dd>
282<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The <code class="docutils literal notranslate"><span class="pre">input_length</span></code> is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</p>
283</dd>
284<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</p>
285</dd>
286<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">output_size</span></code> is too small. <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
287</dd>
288<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
289<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
290<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
291<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
292<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
293<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
294<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
295<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
296</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]297</dl>
298<p class="rubric">Description</p>
299<p>This function decrypts a message encrypted with a symmetric cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]300<p>The input to this function must contain the IV followed by the ciphertext, as output by <a class="reference internal" href="#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>. The IV must be <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> bytes in length, where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of <code class="docutils literal notranslate"><span class="pre">key</span></code>.</p>
301<p>Use the multi-part operation interface with a <a class="reference internal" href="#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 decrypt data which is not in the expected input format.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]302</div>
303</div>
304<div class="section" id="multi-part-cipher-operations">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]305<h2>10.4.3. Multi-part cipher operations</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]306<div class="section" id="psa_cipher_operation_t">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]307<span id="c.psa_cipher_operation_t"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_operation_t</span></code> (type)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]308<p>The type of the state object for multi-part cipher operations.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]309<pre class="literal-block">typedef <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-type"><span class="std std-ref">/* implementation-defined type */</span></a></em> <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]310<p>Before calling any function on a cipher operation object, the application must initialize it by any of the following means:</p>
311<ul>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]312<li><p>Set the object to all-bits-zero, for example:</p>
313<pre class="literal-block"><a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;
314memset(&amp;operation, 0, sizeof(operation));</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]315</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]316<li><p>Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:</p>
317<pre class="literal-block">static <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]318</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]319<li><p>Initialize the object to the initializer <a class="reference internal" href="#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>, for example:</p>
320<pre class="literal-block"><a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation = <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT">PSA_CIPHER_OPERATION_INIT</a>;</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]321</li>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]322<li><p>Assign the result of the function <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_cipher_operation_init()</span></code></a> to the object, for example:</p>
323<pre class="literal-block"><a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> operation;
324operation = <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init">psa_cipher_operation_init</a>();</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]325</li>
326</ul>
327<p>This is an implementation-defined type. Applications that make assumptions about the content of this object will result in in implementation-specific behavior, and are non-portable.</p>
328</div>
329<div class="section" id="PSA_CIPHER_OPERATION_INIT">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]330<span id="c.PSA_CIPHER_OPERATION_INIT"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_OPERATION_INIT</span></code> (macro)</h3>
331<p>This macro returns a suitable initializer for a cipher operation object of type <a class="reference internal" href="#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>.</p>
332<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_OPERATION_INIT" title="PSA_CIPHER_OPERATION_INIT">PSA_CIPHER_OPERATION_INIT</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]333</div>
334<div class="section" id="psa_cipher_operation_init">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]335<span id="c.psa_cipher_operation_init"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_operation_init</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]336<p>Return an initial value for a cipher operation object.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]337<pre class="literal-block"><a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init">psa_cipher_operation_init</a>(void);</pre>
338<p class="rubric">Returns: <a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t"><code class="docutils literal notranslate"><span class="pre">psa_cipher_operation_t</span></code></a></p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]339</div>
340<div class="section" id="psa_cipher_encrypt_setup">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]341<span id="c.psa_cipher_encrypt_setup"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_encrypt_setup</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]342<p>Set the key for a multi-part symmetric encryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]343<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_encrypt_setup" title="psa_cipher_encrypt_setup">psa_cipher_encrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]344 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]345 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]346<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]347<dl class="simple">
348<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</p>
349</dd>
350<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
351It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a>.</p>
352</dd>
353<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The cipher algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
354</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]355</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]356<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
357<dl class="simple">
358<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
359</dd>
360<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
361<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_ENCRYPT" title="PSA_KEY_USAGE_ENCRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_ENCRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
362</dd>
363<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
364</dd>
365<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</p>
366</dd>
367<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
368<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
369<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
370<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
371<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
372<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
373<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
374<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
375</dd>
376<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
377</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]378</dl>
379<p class="rubric">Description</p>
380<p>The sequence of operations to encrypt a message with a symmetric cipher is as follows:</p>
381<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]382<li><p>Allocate an operation object which will be passed to all the functions listed here.</p></li>
383<li><p>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#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>, e.g. <a class="reference internal" href="#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>
384<li><p>Call <a class="reference internal" href="#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> to specify the algorithm and key.</p></li>
385<li><p>Call either <a class="reference internal" href="#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="#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> to generate or set the initialization vector (IV), if the algorithm requires one. It is recommended to use <a class="reference internal" href="#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> unless the protocol being implemented requires a specific IV value.</p></li>
386<li><p>Call <a class="reference internal" href="#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> zero, one or more times, passing a fragment of the message each time.</p></li>
387<li><p>Call <a class="reference internal" href="#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>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]388</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]389<p>If an error occurs at any step after a call to <a class="reference internal" href="#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>, the operation will need to be reset by a call to <a class="reference internal" href="#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>. The application can call <a class="reference internal" href="#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> at any time after the operation has been initialized.</p>
390<p>After a successful call to <a class="reference internal" href="#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>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]391<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]392<li><p>A successful call to <a class="reference internal" href="#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>.</p></li>
393<li><p>A call to <a class="reference internal" href="#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></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]394</ul>
395</div>
396<div class="section" id="psa_cipher_decrypt_setup">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]397<span id="c.psa_cipher_decrypt_setup"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_decrypt_setup</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]398<p>Set the key for a multi-part symmetric decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]399<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_decrypt_setup" title="psa_cipher_decrypt_setup">psa_cipher_decrypt_setup</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]400 <a class="reference internal" href="../keys/ids.html#c.psa_key_id_t" title="psa_key_id_t">psa_key_id_t</a> key,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]401 <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t">psa_algorithm_t</a> alg);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]402<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]403<dl class="simple">
404<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>The operation object to set up. It must have been initialized as per the documentation for <a class="reference internal" href="#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> and not yet in use.</p>
405</dd>
406<dt> <code class="docutils literal notranslate"><span class="pre">key</span></code></dt><dd><p>Identifier of the key to use for the operation. It must remain valid until the operation terminates.
407It must allow the usage <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a>.</p>
408</dd>
409<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>The cipher algorithm to compute (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
410</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]411</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]412<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
413<dl class="simple">
414<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
415</dd>
416<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_HANDLE" title="PSA_ERROR_INVALID_HANDLE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_HANDLE</span></code></a></dt><dd></dd>
417<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_PERMITTED" title="PSA_ERROR_NOT_PERMITTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_PERMITTED</span></code></a></dt><dd><p>The key does not have the <a class="reference internal" href="../keys/policy.html#c.PSA_KEY_USAGE_DECRYPT" title="PSA_KEY_USAGE_DECRYPT"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_KEY_USAGE_DECRYPT</span></code></a> flag, or it does not permit the requested algorithm.</p>
418</dd>
419<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">key</span></code> is not compatible with <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
420</dd>
421<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_NOT_SUPPORTED" title="PSA_ERROR_NOT_SUPPORTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_NOT_SUPPORTED</span></code></a></dt><dd><p><code class="docutils literal notranslate"><span class="pre">alg</span></code> is not supported or is not a cipher algorithm.</p>
422</dd>
423<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
424<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
425<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
426<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
427<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
428<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
429<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
430<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be inactive.</p>
431</dd>
432<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
433</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]434</dl>
435<p class="rubric">Description</p>
436<p>The sequence of operations to decrypt a message with a symmetric cipher is as follows:</p>
437<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]438<li><p>Allocate an operation object which will be passed to all the functions listed here.</p></li>
439<li><p>Initialize the operation object with one of the methods described in the documentation for <a class="reference internal" href="#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>, e.g. <a class="reference internal" href="#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>
440<li><p>Call <a class="reference internal" href="#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 algorithm and key.</p></li>
441<li><p>Call <a class="reference internal" href="#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> with the initialization vector (IV) for the decryption, if the algorithm requires one. This must match the IV used for the encryption.</p></li>
442<li><p>Call <a class="reference internal" href="#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> zero, one or more times, passing a fragment of the message each time.</p></li>
443<li><p>Call <a class="reference internal" href="#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>.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]444</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]445<p>If an error occurs at any step after a call to <a class="reference internal" href="#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>, the operation will need to be reset by a call to <a class="reference internal" href="#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>. The application can call <a class="reference internal" href="#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> at any time after the operation has been initialized.</p>
446<p>After a successful call to <a class="reference internal" href="#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>, the application must eventually terminate the operation. The following events terminate an operation:</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]447<ul class="simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]448<li><p>A successful call to <a class="reference internal" href="#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>.</p></li>
449<li><p>A call to <a class="reference internal" href="#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></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]450</ul>
451</div>
452<div class="section" id="psa_cipher_generate_iv">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]453<span id="c.psa_cipher_generate_iv"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_generate_iv</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]454<p>Generate an initialization vector (IV) for a symmetric encryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]455<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_generate_iv" title="psa_cipher_generate_iv">psa_cipher_generate_iv</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]456 uint8_t * iv,
457 size_t iv_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]458 size_t * iv_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]459<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]460<dl class="simple">
461<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active cipher operation.</p>
462</dd>
463<dt> <code class="docutils literal notranslate"><span class="pre">iv</span></code></dt><dd><p>Buffer where the generated IV is to be written.</p>
464</dd>
465<dt> <code class="docutils literal notranslate"><span class="pre">iv_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">iv</span></code> buffer in bytes. This must be at least <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> and <code class="docutils literal notranslate"><span class="pre">alg</span></code> are type of key and the algorithm respectively that were used to set up the cipher operation.</p>
466</dd>
467<dt> <code class="docutils literal notranslate"><span class="pre">iv_length</span></code></dt><dd><p>On success, the number of bytes of the generated IV.</p>
468</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]469</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]470<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
471<dl class="simple">
472<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
473</dd>
474<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>Either:</p>
475<ul class="simple">
476<li><p>The cipher algorithm does not use an IV.</p></li>
477<li><p>The operation state is not valid: it must be active, with no IV set.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]478</ul>
479</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]480<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">iv</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
481</dd>
482<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
483<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
484<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
485<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
486<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
487<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
488<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
489<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
490</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]491</dl>
492<p class="rubric">Description</p>
493<p>This function generates a random IV, nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]494<p>The generated IV is always the default length for the key and algorithm: <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code>, where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation. To generate different lengths of IV, use <a class="reference internal" href="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> and <a class="reference internal" href="#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>
495<p>If the cipher algorithm does not use an IV, calling this function returns a <a class="reference internal" href="../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> error. For these algorithms, <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> will be zero.</p>
496<p>The application must call <a class="reference internal" href="#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> before calling this function.</p>
497<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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]498</div>
499<div class="section" id="psa_cipher_set_iv">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]500<span id="c.psa_cipher_set_iv"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_set_iv</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]501<p>Set the initialization vector (IV) for a symmetric encryption or decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]502<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_set_iv" title="psa_cipher_set_iv">psa_cipher_set_iv</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]503 const uint8_t * iv,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]504 size_t iv_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]505<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]506<dl class="simple">
507<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active cipher operation.</p>
508</dd>
509<dt> <code class="docutils literal notranslate"><span class="pre">iv</span></code></dt><dd><p>Buffer containing the IV to use.</p>
510</dd>
511<dt> <code class="docutils literal notranslate"><span class="pre">iv_length</span></code></dt><dd><p>Size of the IV in bytes.</p>
512</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]513</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]514<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
515<dl class="simple">
516<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
517</dd>
518<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>Either:</p>
519<ul class="simple">
520<li><p>The cipher algorithm does not use an IV.</p></li>
521<li><p>The operation state is not valid: it must be an active cipher encrypt operation, with no IV set.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]522</ul>
523</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]524<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The size of <code class="docutils literal notranslate"><span class="pre">iv</span></code> is not acceptable for the chosen algorithm, or the chosen algorithm does not use an IV.</p>
525</dd>
526<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
527<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
528<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
529<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
530<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
531<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
532<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
533<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
534</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]535</dl>
536<p class="rubric">Description</p>
537<p>This function sets the IV, nonce or initial counter value for the encryption or decryption operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]538<p>If the cipher algorithm does not use an IV, calling this function returns a <a class="reference internal" href="../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> error. For these algorithms, <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> will be zero.</p>
539<p>The application must call <a class="reference internal" href="#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="#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> before calling this function.</p>
540<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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]541<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]542<p class="admonition-title">Note</p>
543<p>When encrypting, <a class="reference internal" href="#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> is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]544</div>
545</div>
546<div class="section" id="psa_cipher_update">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]547<span id="c.psa_cipher_update"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_update</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]548<p>Encrypt or decrypt a message fragment in an active cipher operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]549<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_update" title="psa_cipher_update">psa_cipher_update</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]550 const uint8_t * input,
551 size_t input_length,
552 uint8_t * output,
553 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]554 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]555<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]556<dl class="simple">
557<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active cipher operation.</p>
558</dd>
559<dt> <code class="docutils literal notranslate"><span class="pre">input</span></code></dt><dd><p>Buffer containing the message fragment to encrypt or decrypt.</p>
560</dd>
561<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">input</span></code> buffer in bytes.</p>
562</dd>
563<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the output is to be written.</p>
564</dd>
565<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
566<ul class="simple">
567<li><p>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</p></li>
568<li><p><a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">input_length</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> evaluates to the maximum output size of any supported cipher algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]569</ul>
570</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]571<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the returned output.</p>
572</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]573</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]574<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
575<dl class="simple">
576<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
577</dd>
578<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active, with an IV set if required for the algorithm.</p>
579</dd>
580<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE()</span></code></a> can be used to determine the required buffer size.</p>
581</dd>
582<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
583<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
584<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
585<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
586<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
587<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
588<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
589<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
590</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]591</dl>
592<p class="rubric">Description</p>
593<p>The following must occur before calling this function:</p>
594<ol class="arabic simple">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]595<li><p>Call either <a class="reference internal" href="#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="#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>. The choice of setup function determines whether this function encrypts or decrypts its input.</p></li>
596<li><p>If the algorithm requires an IV, call <a class="reference internal" href="#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="#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>. <a class="reference internal" href="#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> is recommended when encrypting.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]597</ol>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]598<p>If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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]599</div>
600<div class="section" id="psa_cipher_finish">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]601<span id="c.psa_cipher_finish"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_finish</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]602<p>Finish encrypting or decrypting a message in a cipher operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]603<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_finish" title="psa_cipher_finish">psa_cipher_finish</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation,
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]604 uint8_t * output,
605 size_t output_size,
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]606 size_t * output_length);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]607<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]608<dl class="simple">
609<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Active cipher operation.</p>
610</dd>
611<dt> <code class="docutils literal notranslate"><span class="pre">output</span></code></dt><dd><p>Buffer where the output is to be written.</p>
612</dd>
613<dt> <code class="docutils literal notranslate"><span class="pre">output_size</span></code></dt><dd><p>Size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer in bytes. This must be appropriate for the selected algorithm and key:</p>
614<ul class="simple">
615<li><p>A sufficient output size is <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">key_type</span></code><code class="docutils literal notranslate"><span class="pre">,</span> </code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> where <code class="docutils literal notranslate"><span class="pre">key_type</span></code> is the type of key and <code class="docutils literal notranslate"><span class="pre">alg</span></code> is the algorithm that were used to set up the operation.</p></li>
616<li><p><a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a> evaluates to the maximum output size of any supported cipher algorithm.</p></li>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]617</ul>
618</dd>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]619<dt> <code class="docutils literal notranslate"><span class="pre">output_length</span></code></dt><dd><p>On success, the number of bytes that make up the returned output.</p>
620</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]621</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]622<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
623<dl class="simple">
624<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd><p>Success.</p>
625</dd>
626<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_ARGUMENT" title="PSA_ERROR_INVALID_ARGUMENT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_ARGUMENT</span></code></a></dt><dd><p>The total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.</p>
627</dd>
628<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INVALID_PADDING" title="PSA_ERROR_INVALID_PADDING"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INVALID_PADDING</span></code></a></dt><dd><p>This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.</p>
629</dd>
630<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The operation state is not valid: it must be active, with an IV set if required for the algorithm.</p>
631</dd>
632<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BUFFER_TOO_SMALL" title="PSA_ERROR_BUFFER_TOO_SMALL"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BUFFER_TOO_SMALL</span></code></a></dt><dd><p>The size of the <code class="docutils literal notranslate"><span class="pre">output</span></code> buffer is too small. <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE()</span></code></a> or <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a> can be used to determine the required buffer size.</p>
633</dd>
634<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_INSUFFICIENT_MEMORY" title="PSA_ERROR_INSUFFICIENT_MEMORY"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_INSUFFICIENT_MEMORY</span></code></a></dt><dd></dd>
635<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
636<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
637<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
638<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_STORAGE_FAILURE" title="PSA_ERROR_STORAGE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_STORAGE_FAILURE</span></code></a></dt><dd></dd>
639<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_CORRUPT" title="PSA_ERROR_DATA_CORRUPT"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_CORRUPT</span></code></a></dt><dd></dd>
640<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_DATA_INVALID" title="PSA_ERROR_DATA_INVALID"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_DATA_INVALID</span></code></a></dt><dd></dd>
641<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
642</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]643</dl>
644<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]645<p>The application must call <a class="reference internal" href="#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="#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> before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.</p>
646<p>This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to <a class="reference internal" href="#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>.</p>
647<p>When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling <a class="reference internal" href="#c.psa_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]648</div>
649<div class="section" id="psa_cipher_abort">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]650<span id="c.psa_cipher_abort"></span><h3><code class="docutils literal notranslate"><span class="pre">psa_cipher_abort</span></code> (function)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]651<p>Abort a cipher operation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]652<pre class="literal-block"><a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t">psa_status_t</a> <a class="reference internal" href="#c.psa_cipher_abort" title="psa_cipher_abort">psa_cipher_abort</a>(<a class="reference internal" href="#c.psa_cipher_operation_t" title="psa_cipher_operation_t">psa_cipher_operation_t</a> * operation);</pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]653<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]654<dl class="simple">
655<dt> <code class="docutils literal notranslate"><span class="pre">operation</span></code></dt><dd><p>Initialized cipher operation.</p>
656</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]657</dl>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]658<p class="rubric">Returns: <a class="reference internal" href="../library/status.html#c.psa_status_t" title="psa_status_t"><code class="docutils literal notranslate"><span class="pre">psa_status_t</span></code></a></p>
659<dl class="simple">
660<dt> <a class="reference internal" href="../library/status.html#c.PSA_SUCCESS" title="PSA_SUCCESS"><code class="docutils literal notranslate"><span class="pre">PSA_SUCCESS</span></code></a></dt><dd></dd>
661<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_COMMUNICATION_FAILURE" title="PSA_ERROR_COMMUNICATION_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_COMMUNICATION_FAILURE</span></code></a></dt><dd></dd>
662<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_HARDWARE_FAILURE" title="PSA_ERROR_HARDWARE_FAILURE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_HARDWARE_FAILURE</span></code></a></dt><dd></dd>
663<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_CORRUPTION_DETECTED" title="PSA_ERROR_CORRUPTION_DETECTED"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_CORRUPTION_DETECTED</span></code></a></dt><dd></dd>
664<dt> <a class="reference internal" href="../library/status.html#c.PSA_ERROR_BAD_STATE" title="PSA_ERROR_BAD_STATE"><code class="docutils literal notranslate"><span class="pre">PSA_ERROR_BAD_STATE</span></code></a></dt><dd><p>The library has not been previously initialized by <a class="reference internal" href="../library/library.html#c.psa_crypto_init" title="psa_crypto_init"><code class="xref any c c-func docutils literal notranslate"><span class="pre">psa_crypto_init()</span></code></a>. It is implementation-dependent whether a failure to initialize results in this error code.</p>
665</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]666</dl>
667<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]668<p>Aborting an operation frees all associated resources except for the <code class="docutils literal notranslate"><span class="pre">operation</span></code> object itself. Once aborted, the operation object can be reused for another operation by calling <a class="reference internal" href="#c.psa_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="#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> again.</p>
669<p>This function can be called any time after the operation object has been initialized as described in <a class="reference internal" href="#c.psa_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>.</p>
670<p>In particular, calling <a class="reference internal" href="#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> after the operation has been terminated by a call to <a class="reference internal" href="#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> or <a class="reference internal" href="#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> is safe and has no effect.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]671</div>
672</div>
673<div class="section" id="support-macros">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]674<h2>10.4.4. Support macros</h2>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]675<div class="section" id="PSA_ALG_IS_STREAM_CIPHER">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]676<span id="c.PSA_ALG_IS_STREAM_CIPHER"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_STREAM_CIPHER</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]677<p>Whether the specified algorithm is a stream cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]678<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_ALG_IS_STREAM_CIPHER" title="PSA_ALG_IS_STREAM_CIPHER">PSA_ALG_IS_STREAM_CIPHER</a>(alg) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]679<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]680<dl class="simple">
681<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>An algorithm identifier (value of type <a class="reference internal" href="algorithms.html#c.psa_algorithm_t" title="psa_algorithm_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_algorithm_t</span></code></a>).</p>
682</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]683</dl>
684<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]685<p><code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is a stream cipher algorithm, <code class="docutils literal notranslate"><span class="pre">0</span></code> otherwise. This macro can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or <code class="docutils literal notranslate"><span class="pre">1</span></code> if <code class="docutils literal notranslate"><span class="pre">alg</span></code> is not a supported algorithm identifier or if it is not a symmetric cipher algorithm.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]686<p class="rubric">Description</p>
687<p>A stream cipher is a symmetric cipher that encrypts or decrypts messages by applying a bitwise-xor with a stream of bytes that is generated from a key.</p>
688</div>
689<div class="section" id="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]690<span id="c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
691<p>The maximum size of the output of <a class="reference internal" href="#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>, in bytes.</p>
692<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE</a>(key_type, alg, input_length) \
693 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]694<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]695<dl class="simple">
696<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
697</dd>
698<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A cipher algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
699</dd>
700<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
701</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]702</dl>
703<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]704<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]705<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]706<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller.</p>
707<p>See also <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]708</div>
709<div class="section" id="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]710<span id="c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
711<p>A sufficient output buffer size for <a class="reference internal" href="#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>, for any of the supported key types and cipher algorithms.</p>
712<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE">PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE</a>(input_length) \
713 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]714<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]715<dl class="simple">
716<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
717</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]718</dl>
719<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]720<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size.</p>
721<p>See also <a class="reference internal" href="#c.PSA_CIPHER_ENCRYPT_OUTPUT_SIZE" title="PSA_CIPHER_ENCRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_ENCRYPT_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]722</div>
723<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]724<span id="c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</span></code> (macro)</h3>
725<p>The maximum size of the output of <a class="reference internal" href="#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>, in bytes.</p>
726<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE">PSA_CIPHER_DECRYPT_OUTPUT_SIZE</a>(key_type, alg, input_length) \
727 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]728<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]729<dl class="simple">
730<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
731</dd>
732<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A cipher algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
733</dd>
734<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
735</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]736</dl>
737<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]738<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]739<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]740<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size. Depending on the algorithm, the actual size of the output might be smaller.</p>
741<p>See also <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]742</div>
743<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]744<span id="c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
745<p>A sufficient output buffer size for <a class="reference internal" href="#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>, for any of the supported key types and cipher algorithms.</p>
746<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE">PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE</a>(input_length) \
747 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]748<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]749<dl class="simple">
750<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
751</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]752</dl>
753<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]754<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size.</p>
755<p>See also <a class="reference internal" href="#c.PSA_CIPHER_DECRYPT_OUTPUT_SIZE" title="PSA_CIPHER_DECRYPT_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_DECRYPT_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]756</div>
757<div class="section" id="PSA_CIPHER_IV_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]758<span id="c.PSA_CIPHER_IV_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]759<p>The default IV size for a cipher algorithm, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]760<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH">PSA_CIPHER_IV_LENGTH</a>(key_type, alg) <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]761<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]762<dl class="simple">
763<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
764</dd>
765<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A cipher algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
766</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]767</dl>
768<p class="rubric">Returns</p>
769<p>The default IV size for the specified key type and algorithm.
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]770If the algorithm does not use an IV, return <code class="docutils literal notranslate"><span class="pre">0</span></code>.
771If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal notranslate"><span class="pre">0</span></code>.
772An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]773<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]774<p>The IV that is generated as part of a call to <a class="reference internal" href="#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> is always the default IV length for the algorithm.</p>
775<p>This macro can be used to allocate a buffer of sufficient size to store the IV output from <a class="reference internal" href="#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> when using a multi-part cipher operation.</p>
776<p>See also <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]777</div>
778<div class="section" id="PSA_CIPHER_IV_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]779<span id="c.PSA_CIPHER_IV_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_MAX_SIZE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]780<p>The maximum IV size for all supported cipher algorithms, in bytes.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]781<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_IV_MAX_SIZE" title="PSA_CIPHER_IV_MAX_SIZE">PSA_CIPHER_IV_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
782<p>See also <a class="reference internal" href="#c.PSA_CIPHER_IV_LENGTH" title="PSA_CIPHER_IV_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_IV_LENGTH()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]783</div>
784<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]785<span id="c.PSA_CIPHER_UPDATE_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE</span></code> (macro)</h3>
786<p>A sufficient output buffer size for <a class="reference internal" href="#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>.</p>
787<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE">PSA_CIPHER_UPDATE_OUTPUT_SIZE</a>(key_type, alg, input_length) \
788 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]789<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]790<dl class="simple">
791<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
792</dd>
793<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A cipher algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
794</dd>
795<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
796</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]797</dl>
798<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]799<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]800<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]801<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size. The actual size of the output might be smaller in any given call.</p>
802<p>See also <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]803</div>
804<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]805<span id="c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
806<p>A sufficient output buffer size for <a class="reference internal" href="#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>, for any of the supported key types and cipher algorithms.</p>
807<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE">PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE</a>(input_length) \
808 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]809<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]810<dl class="simple">
811<dt> <code class="docutils literal notranslate"><span class="pre">input_length</span></code></dt><dd><p>Size of the input in bytes.</p>
812</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]813</dl>
814<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]815<p>If the size of the output buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient buffer size.</p>
816<p>See also <a class="reference internal" href="#c.PSA_CIPHER_UPDATE_OUTPUT_SIZE" title="PSA_CIPHER_UPDATE_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_UPDATE_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]817</div>
818<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]819<span id="c.PSA_CIPHER_FINISH_OUTPUT_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE</span></code> (macro)</h3>
820<p>A sufficient ciphertext buffer size for <a class="reference internal" href="#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>.</p>
821<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE">PSA_CIPHER_FINISH_OUTPUT_SIZE</a>(key_type, alg) \
822 <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]823<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]824<dl class="simple">
825<dt> <code class="docutils literal notranslate"><span class="pre">key_type</span></code></dt><dd><p>A symmetric key type that is compatible with algorithm <code class="docutils literal notranslate"><span class="pre">alg</span></code>.</p>
826</dd>
827<dt> <code class="docutils literal notranslate"><span class="pre">alg</span></code></dt><dd><p>A cipher algorithm (<code class="docutils literal notranslate"><span class="pre">PSA_ALG_XXX</span></code> value such that <a class="reference internal" href="algorithms.html#c.PSA_ALG_IS_CIPHER" title="PSA_ALG_IS_CIPHER"><code class="docutils literal notranslate"><span class="pre">PSA_ALG_IS_CIPHER</span></code></a><code class="docutils literal notranslate"><span class="pre">(</span></code><code class="docutils literal notranslate"><span class="pre">alg</span></code><code class="docutils literal notranslate"><span class="pre">)</span></code> is true).</p>
828</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]829</dl>
830<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]831<p>A sufficient output size for the specified key type and algorithm. If the key type or cipher algorithm is not recognized, or the parameters are incompatible, return <code class="docutils literal notranslate"><span class="pre">0</span></code>. An implementation can return either <code class="docutils literal notranslate"><span class="pre">0</span></code> or a correct size for a key type and cipher algorithm that it recognizes, but does not support.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]832<p class="rubric">Description</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]833<p>If the size of the ciphertext buffer is at least this large, it is guaranteed that <a class="reference internal" href="#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> will not fail due to an insufficient ciphertext buffer size. The actual size of the output might be smaller in any given call.</p>
834<p>See also <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]835</div>
836<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]837<span id="c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</span></code> (macro)</h3>
838<p>A sufficient ciphertext buffer size for <a class="reference internal" href="#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>, for any of the supported key types and cipher algorithms.</p>
839<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE">PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
840<p>See also <a class="reference internal" href="#c.PSA_CIPHER_FINISH_OUTPUT_SIZE" title="PSA_CIPHER_FINISH_OUTPUT_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_CIPHER_FINISH_OUTPUT_SIZE()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]841</div>
842<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_LENGTH">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]843<span id="c.PSA_BLOCK_CIPHER_BLOCK_LENGTH"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]844<p>The block size of a block cipher.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]845<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH">PSA_BLOCK_CIPHER_BLOCK_LENGTH</a>(type) <em><a class="reference internal" href="../../overview/implementation.html#specification-defined-value"><span class="std std-ref">/* specification-defined value */</span></a></em></pre>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]846<p class="rubric">Parameters</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]847<dl class="simple">
848<dt> <code class="docutils literal notranslate"><span class="pre">type</span></code></dt><dd><p>A cipher key type (value of type <a class="reference internal" href="../keys/types.html#c.psa_key_type_t" title="psa_key_type_t"><code class="xref any c c-type docutils literal notranslate"><span class="pre">psa_key_type_t</span></code></a>).</p>
849</dd>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]850</dl>
851<p class="rubric">Returns</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]852<p>The block size for a block cipher, or <code class="docutils literal notranslate"><span class="pre">1</span></code> for a stream cipher. The return value is undefined if <code class="docutils literal notranslate"><span class="pre">type</span></code> is not a supported cipher key type.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]853<p class="rubric">Description</p>
854<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]855<p class="admonition-title">Note</p>
856<p>It is possible to build stream cipher algorithms on top of a block cipher, for example CTR mode (<a class="reference internal" href="#c.PSA_ALG_CTR" title="PSA_ALG_CTR"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_ALG_CTR</span></code></a>). This macro only takes the key type into account, so it cannot be used to determine the size of the data that <a class="reference internal" href="#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> might buffer for future processing in general.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]857</div>
858<div class="admonition note">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]859<p class="admonition-title">Note</p>
860<p>This macro expression is a compile-time constant if <code class="docutils literal notranslate"><span class="pre">type</span></code> is a compile-time constant.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]861</div>
862<div class="admonition warning">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]863<p class="admonition-title">Warning</p>
864<p>This macro is permitted to evaluate its argument multiple times.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]865</div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]866<p>See also <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE" title="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]867</div>
868<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]869<span id="c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE"></span><h3><code class="docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</span></code> (macro)</h3>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]870<p>The maximum size of a block cipher supported by the implementation.</p>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]871<pre class="literal-block">#define <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE" title="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE">PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE</a> <em><a class="reference internal" href="../../overview/implementation.html#implementation-defined-value"><span class="std std-ref">/* implementation-defined value */</span></a></em></pre>
872<p>See also <a class="reference internal" href="#c.PSA_BLOCK_CIPHER_BLOCK_LENGTH" title="PSA_BLOCK_CIPHER_BLOCK_LENGTH"><code class="xref any c c-macro docutils literal notranslate"><span class="pre">PSA_BLOCK_CIPHER_BLOCK_LENGTH()</span></code></a>.</p>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]873</div>
874</div>
875</div>
876
877
878 </div>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]879
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]880 </div>
881 </div>
882 <div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]883 <div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
884IHI 0086<br/>
885Non-confidential<br/>
886Version 1.0.1
887<span style="color: red; font-weight: bold;"></span>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]888<ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]889<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]890</ul>
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]891<ul class="current">
892<li class="toctree-l1"><a class="reference internal" href="../../overview/intro.html">1. Introduction</a></li>
893<li class="toctree-l1"><a class="reference internal" href="../../overview/goals.html">2. Design goals</a></li>
894<li class="toctree-l1"><a class="reference internal" href="../../overview/functionality.html">3. Functionality overview</a></li>
895<li class="toctree-l1"><a class="reference internal" href="../../overview/sample-arch.html">4. Sample architectures</a></li>
896<li class="toctree-l1"><a class="reference internal" href="../../overview/conventions.html">5. Library conventions</a></li>
897<li class="toctree-l1"><a class="reference internal" href="../../overview/implementation.html">6. Implementation considerations</a></li>
898<li class="toctree-l1"><a class="reference internal" href="../../overview/usage.html">7. Usage considerations</a></li>
899<li class="toctree-l1"><a class="reference internal" href="../library/index.html">8. Library management reference</a></li>
900<li class="toctree-l1"><a class="reference internal" href="../keys/index.html">9. Key management reference</a></li>
901<li class="toctree-l1 current"><a class="reference internal" href="index.html">10. Cryptographic operation reference</a><ul class="current">
902<li class="toctree-l2"><a class="reference internal" href="algorithms.html">10.1. Algorithms</a></li>
903<li class="toctree-l2"><a class="reference internal" href="hashes.html">10.2. Message digests</a></li>
904<li class="toctree-l2"><a class="reference internal" href="macs.html">10.3. Message authentication codes (MAC)</a></li>
905<li class="toctree-l2 current"><a class="current reference internal" href="#">10.4. Unauthenticated ciphers</a><ul>
906<li class="toctree-l3"><a class="reference internal" href="#cipher-algorithms">10.4.1. Cipher algorithms</a></li>
907<li class="toctree-l3"><a class="reference internal" href="#single-part-cipher-functions">10.4.2. Single-part cipher functions</a></li>
908<li class="toctree-l3"><a class="reference internal" href="#multi-part-cipher-operations">10.4.3. Multi-part cipher operations</a></li>
909<li class="toctree-l3"><a class="reference internal" href="#support-macros">10.4.4. Support macros</a></li>
910</ul>
911</li>
912<li class="toctree-l2"><a class="reference internal" href="aead.html">10.5. Authenticated encryption with associated data (AEAD)</a></li>
913<li class="toctree-l2"><a class="reference internal" href="kdf.html">10.6. Key derivation</a></li>
914<li class="toctree-l2"><a class="reference internal" href="sign.html">10.7. Asymmetric signature</a></li>
915<li class="toctree-l2"><a class="reference internal" href="pke.html">10.8. Asymmetric encryption</a></li>
916<li class="toctree-l2"><a class="reference internal" href="ka.html">10.9. Key agreement</a></li>
917<li class="toctree-l2"><a class="reference internal" href="rng.html">10.10. Other cryptographic services</a></li>
918</ul>
919</li>
920</ul>
921<ul>
922<li class="toctree-l1"><a class="reference internal" href="../../appendix/example_header.html">Example header file</a></li>
923<li class="toctree-l1"><a class="reference internal" href="../../appendix/specdef_values.html">Example macro implementations</a></li>
924<li class="toctree-l1"><a class="reference internal" href="../../appendix/history.html">Changes to the API</a></li>
925</ul>
926<ul>
927<li class="toctree-l1"><a class="reference internal" href="../../psa_c-identifiers.html">Index of API elements</a></li>
928</ul>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]929<div id="searchbox" style="display: none" role="search">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]930 <h3 id="searchlabel">Quick search</h3>
931 <div class="searchformwrapper">
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]932 <form class="search" action="../../search.html" method="get">
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]933 <input type="text" name="q" aria-labelledby="searchlabel" />
934 <input type="submit" value="Go" />
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]935 </form>
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]936 </div>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]937</div>
938<script type="text/javascript">$('#searchbox').show(0);</script>
939 </div>
940 </div>
941 <div class="clearer"></div>
942 </div>
943 <div class="footer">
Gilles Peskinec2db5f02021-01-18 20:36:53 +0100[diff] [blame]944 &copy; 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]945
946 |
Bence Szépkútie26ccad2021-02-01 14:26:11 +0100[diff] [blame^]947 Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
948 &amp; <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]949
Gilles Peskine6c723a22020-04-17 16:57:52 +0200[diff] [blame]950 </div>
951
952
953
954
955 </body>
956</html>