Blame - docs/1.0.1/html/api/ops/ciphers.html - mirror/mbed-crypto

blob: b9f7270d1197c208f2fa537fb8ad2988296e1365 [file] [log] [blame]

Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	1
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	2	<!DOCTYPE html>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	3
				4	<html xmlns="http://www.w3.org/1999/xhtml">
				5	<head>
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	6	<meta charset="utf-8" />
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	7	<title>10.4. Unauthenticated ciphers — PSA Crypto API 1.0.1 documentation</title>
Gilles Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	14	<script type="text/javascript" src="../../_static/language_data.js"></script>
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	15	<link rel="author" title="About these documents" href="../../about.html" />
Gilles Peskine	6c723a2	2020-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	20
				21	<link rel="stylesheet" href="../../_static/custom.css" type="text/css" />
				22
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	23
Gilles Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	26	</head><body>
Gilles Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	32
				33
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	34	<div class="body" role="main">
				35
				36	<div class="section" id="unauthenticated-ciphers">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	37	<span id="ciphers"></span><h1>10.4. Unauthenticated ciphers</h1>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	38	<div class="admonition warning">
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	39	<p class="admonition-title">Warning</p>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	40	<p>The unauthenticated cipher API is provided to implement legacy protocols and
				41	for use cases where the data integrity and authenticity is guaranteed by
				42	non-cryptographic means.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	44	</div>
				45	<div class="section" id="cipher-algorithms">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	46	<span id="id1"></span><h2>10.4.1. Cipher algorithms</h2>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	47	<div class="section" id="PSA_ALG_STREAM_CIPHER">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	49	<p>The stream cipher mode of a stream cipher algorithm.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	54	<div class="admonition warning">
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	57	</div>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	59	<p class="rubric">ChaCha20</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	63	<ul class="simple">
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	73	</ul>
				74	</li>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	75	</ul>
				76	</div>
				77	<div class="section" id="PSA_ALG_CTR">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	92	</ul>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	98	</div>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	99	</div>
				100	<div class="section" id="PSA_ALG_CFB">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	111	</div>
				112	<div class="section" id="PSA_ALG_OFB">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	116	<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	123	</div>
				124	<div class="section" id="PSA_ALG_XTS">
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	132	</div>
				133	<div class="section" id="PSA_ALG_ECB_NO_PADDING">
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	137	<div class="admonition warning">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	140	</div>
				141	<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	144	<div class="admonition note">
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	149	</div>
				150	<div class="section" id="PSA_ALG_CBC_NO_PADDING">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	154	<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	162	</div>
				163	<div class="section" id="PSA_ALG_CBC_PKCS7">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	167	<p>The underlying block cipher is determined by the key type.</p>
Gilles Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	174	</div>
				175	</div>
				176	<div class="section" id="single-part-cipher-functions">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	177	<h2>10.4.2. Single-part cipher functions</h2>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	178	<div class="section" id="psa_cipher_encrypt">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	180	<p>Encrypt a message using a symmetric cipher.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	187	size_t * output_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	188	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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.
				191	It 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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	205	</ul>
				206	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	209	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	237	The 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>.
				238	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> 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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	240	</div>
				241	<div class="section" id="psa_cipher_decrypt">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	243	<p>Decrypt a message using a symmetric cipher.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	250	size_t * output_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	251	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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.
				254	It 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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	268	</ul>
				269	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	272	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	302	</div>
				303	</div>
				304	<div class="section" id="multi-part-cipher-operations">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	305	<h2>10.4.3. Multi-part cipher operations</h2>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	306	<div class="section" id="psa_cipher_operation_t">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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;
				314	memset(&operation, 0, sizeof(operation));</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	315	</li>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	318	</li>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	321	</li>
Bence Szépkúti	e26ccad	2021-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;
				324	operation = <a class="reference internal" href="#c.psa_cipher_operation_init" title="psa_cipher_operation_init">psa_cipher_operation_init</a>();</pre>
Gilles Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	333	</div>
				334	<div class="section" id="psa_cipher_operation_init">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	336	<p>Return an initial value for a cipher operation object.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	339	</div>
				340	<div class="section" id="psa_cipher_encrypt_setup">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	342	<p>Set the key for a multi-part symmetric encryption operation.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	346	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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.
				351	It 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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	355	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	388	</ol>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	391	<ul class="simple">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	394	</ul>
				395	</div>
				396	<div class="section" id="psa_cipher_decrypt_setup">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	398	<p>Set the key for a multi-part symmetric decryption operation.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	c2db5f0	2021-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	402	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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.
				407	It 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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	411	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	444	</ol>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	447	<ul class="simple">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	450	</ul>
				451	</div>
				452	<div class="section" id="psa_cipher_generate_iv">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	454	<p>Generate an initialization vector (IV) for a symmetric encryption operation.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	456	uint8_t * iv,
				457	size_t iv_size,
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	458	size_t * iv_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	459	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	469	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	478	</ul>
				479	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	498	</div>
				499	<div class="section" id="psa_cipher_set_iv">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	503	const uint8_t * iv,
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	504	size_t iv_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	505	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	513	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	522	</ul>
				523	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	541	<div class="admonition note">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	544	</div>
				545	</div>
				546	<div class="section" id="psa_cipher_update">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	554	size_t * output_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	555	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	569	</ul>
				570	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	573	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	597	</ol>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	599	</div>
				600	<div class="section" id="psa_cipher_finish">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	602	<p>Finish encrypting or decrypting a message in a cipher operation.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	604	uint8_t * output,
				605	size_t output_size,
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	606	size_t * output_length);</pre>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	607	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	617	</ul>
				618	</dd>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	621	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	643	</dl>
				644	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	648	</div>
				649	<div class="section" id="psa_cipher_abort">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	651	<p>Abort a cipher operation.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	653	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	657	</dl>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	666	</dl>
				667	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	671	</div>
				672	</div>
				673	<div class="section" id="support-macros">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	674	<h2>10.4.4. Support macros</h2>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	675	<div class="section" id="PSA_ALG_IS_STREAM_CIPHER">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	677	<p>Whether the specified algorithm is a stream cipher.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	679	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	683	</dl>
				684	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	694	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	702	</dl>
				703	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	705	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	708	</div>
				709	<div class="section" id="PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	714	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	718	</dl>
				719	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	722	</div>
				723	<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	728	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	736	</dl>
				737	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	739	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	742	</div>
				743	<div class="section" id="PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	748	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	752	</dl>
				753	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	756	</div>
				757	<div class="section" id="PSA_CIPHER_IV_LENGTH">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	759	<p>The default IV size for a cipher algorithm, in bytes.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	761	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	770	If the algorithm does not use an IV, return <code class="docutils literal notranslate"><span class="pre">0</span></code>.
				771	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>.
				772	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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	773	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	777	</div>
				778	<div class="section" id="PSA_CIPHER_IV_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	783	</div>
				784	<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	789	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	797	</dl>
				798	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	800	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	803	</div>
				804	<div class="section" id="PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	809	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	813	</dl>
				814	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	817	</div>
				818	<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	823	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	829	</dl>
				830	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	832	<p class="rubric">Description</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	835	</div>
				836	<div class="section" id="PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	841	</div>
				842	<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_LENGTH">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	844	<p>The block size of a block cipher.</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	846	<p class="rubric">Parameters</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	850	</dl>
				851	<p class="rubric">Returns</p>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	853	<p class="rubric">Description</p>
				854	<div class="admonition note">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	857	</div>
				858	<div class="admonition note">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	861	</div>
				862	<div class="admonition warning">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	865	</div>
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	867	</div>
				868	<div class="section" id="PSA_BLOCK_CIPHER_BLOCK_MAX_SIZE">
Bence Szépkúti	e26ccad	2021-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 Peskine	6c723a2	2020-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úti	e26ccad	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	873	</div>
				874	</div>
				875	</div>
				876
				877
				878	</div>
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	879
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	880	</div>
				881	</div>
				882	<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
Gilles Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	883	<div class="sphinxsidebarwrapper"><h3><a href="../../index.html"><b>PSA Crypto API</b></a></h3>
				884	IHI 0086<br/>
				885	Non-confidential<br/>
				886	Version 1.0.1
				887	<span style="color: red; font-weight: bold;"></span>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	888	<ul>
Gilles Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	890	</ul>
Gilles Peskine	c2db5f0	2021-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 Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	929	<div id="searchbox" style="display: none" role="search">
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	930	<h3 id="searchlabel">Quick search</h3>
				931	<div class="searchformwrapper">
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	932	<form class="search" action="../../search.html" method="get">
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	933	<input type="text" name="q" aria-labelledby="searchlabel" />
				934	<input type="submit" value="Go" />
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	935	</form>
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	936	</div>
Gilles Peskine	6c723a2	2020-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 Peskine	c2db5f0	2021-01-18 20:36:53 +0100	[diff] [blame]	944	© 2018-2020, Arm Limited or its affiliates. All rights reserved.
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	945
				946	\|
Bence Szépkúti	e26ccad	2021-02-01 14:26:11 +0100	[diff] [blame]	947	Powered by <a href="http://sphinx-doc.org/">Sphinx 2.1.2</a>
				948	& <a href="https://github.com/bitprophet/alabaster">Alabaster 0.7.12</a>
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	949
Gilles Peskine	6c723a2	2020-04-17 16:57:52 +0200	[diff] [blame]	950	</div>
				951
				952
				953
				954
				955	</body>
				956	</html>