1<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Authenticated Encryption With Associated Data (AEAD) Cipher API</title><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><link rel="home" href="index.html" title="Linux Kernel Crypto API"><link rel="up" href="API.html" title="Chapter 5. Programming Interface"><link rel="prev" href="API-ablkcipher-request-set-crypt.html" title="ablkcipher_request_set_crypt"><link rel="next" href="API-crypto-alloc-aead.html" title="crypto_alloc_aead"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Authenticated Encryption With Associated Data (AEAD) Cipher API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="API-ablkcipher-request-set-crypt.html">Prev</a> </td><th width="60%" align="center">Chapter 5. Programming Interface</th><td width="20%" align="right"> <a accesskey="n" href="API-crypto-alloc-aead.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id-1.7.7"></a>Authenticated Encryption With Associated Data (AEAD) Cipher API</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="refentrytitle"><a href="API-crypto-alloc-aead.html"><span class="phrase">crypto_alloc_aead</span></a></span><span class="refpurpose"> — 2 allocate AEAD cipher handle 3 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-free-aead.html"><span class="phrase">crypto_free_aead</span></a></span><span class="refpurpose"> — 4 zeroize and free aead handle 5 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-ivsize.html"><span class="phrase">crypto_aead_ivsize</span></a></span><span class="refpurpose"> — 6 obtain IV size 7 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-authsize.html"><span class="phrase">crypto_aead_authsize</span></a></span><span class="refpurpose"> — 8 obtain maximum authentication data size 9 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-blocksize.html"><span class="phrase">crypto_aead_blocksize</span></a></span><span class="refpurpose"> — 10 obtain block size of cipher 11 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-setkey.html"><span class="phrase">crypto_aead_setkey</span></a></span><span class="refpurpose"> — 12 set key for cipher 13 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-setauthsize.html"><span class="phrase">crypto_aead_setauthsize</span></a></span><span class="refpurpose"> — 14 set authentication data size 15 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-encrypt.html"><span class="phrase">crypto_aead_encrypt</span></a></span><span class="refpurpose"> — 16 encrypt plaintext 17 </span></dt><dt><span class="refentrytitle"><a href="API-crypto-aead-decrypt.html"><span class="phrase">crypto_aead_decrypt</span></a></span><span class="refpurpose"> — 18 decrypt ciphertext 19 </span></dt></dl></div><p> 20 </p><p> 21 The AEAD cipher API is used with the ciphers of type CRYPTO_ALG_TYPE_AEAD 22 (listed as type <span class="quote">“<span class="quote">aead</span>”</span> in /proc/crypto) 23 </p><p> 24 The most prominent examples for this type of encryption is GCM and CCM. 25 However, the kernel supports other types of AEAD ciphers which are defined 26 with the following cipher string: 27 </p><p> 28 authenc(keyed message digest, block cipher) 29 </p><p> 30 For example: authenc(hmac(sha256), cbc(aes)) 31 </p><p> 32 The example code provided for the asynchronous block cipher operation 33 applies here as well. Naturally all *ablkcipher* symbols must be exchanged 34 the *aead* pendants discussed in the following. In addition, for the AEAD 35 operation, the aead_request_set_assoc function must be used to set the 36 pointer to the associated data memory location before performing the 37 encryption or decryption operation. In case of an encryption, the associated 38 data memory is filled during the encryption operation. For decryption, the 39 associated data memory must contain data that is used to verify the integrity 40 of the decrypted data. Another deviation from the asynchronous block cipher 41 operation is that the caller should explicitly check for -EBADMSG of the 42 crypto_aead_decrypt. That error indicates an authentication error, i.e. 43 a breach in the integrity of the message. In essence, that -EBADMSG error 44 code is the key bonus an AEAD cipher has over <span class="quote">“<span class="quote">standard</span>”</span> block chaining 45 modes. 46 </p><p> 47 Memory Structure: 48 </p><p> 49 To support the needs of the most prominent user of AEAD ciphers, namely 50 IPSEC, the AEAD ciphers have a special memory layout the caller must adhere 51 to. 52 </p><p> 53 The scatter list pointing to the input data must contain: 54 </p><p> 55 * for RFC4106 ciphers, the concatenation of 56 associated authentication data || IV || plaintext or ciphertext. Note, the 57 same IV (buffer) is also set with the aead_request_set_crypt call. Note, 58 the API call of aead_request_set_ad must provide the length of the AAD and 59 the IV. The API call of aead_request_set_crypt only points to the size of 60 the input plaintext or ciphertext. 61 </p><p> 62 * for <span class="quote">“<span class="quote">normal</span>”</span> AEAD ciphers, the concatenation of 63 associated authentication data || plaintext or ciphertext. 64 </p><p> 65 It is important to note that if multiple scatter gather list entries form 66 the input data mentioned above, the first entry must not point to a NULL 67 buffer. If there is any potential where the AAD buffer can be NULL, the 68 calling code must contain a precaution to ensure that this does not result 69 in the first scatter gather list entry pointing to a NULL buffer. 70</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="API-ablkcipher-request-set-crypt.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="API.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="API-crypto-alloc-aead.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top"><span class="phrase">ablkcipher_request_set_crypt</span> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> <span class="phrase">crypto_alloc_aead</span></td></tr></table></div></body></html> 71