1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><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="idp1097621188"></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 addtion, 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></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> 47