1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>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="User.html" title="Chapter 4. User Space Interface"><link rel="prev" href="ch04s05.html" title="Symmetric Cipher API"><link rel="next" href="ch04s07.html" title="Random Number Generator API"></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">AEAD Cipher API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch04s05.html">Prev</a> </td><th width="60%" align="center">Chapter 4. User Space Interface</th><td width="20%" align="right"> <a accesskey="n" href="ch04s07.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idp1097367044"></a>AEAD Cipher API</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ch04s06.html#idp1097375068">AEAD Memory Structure</a></span></dt></dl></div><p> 2 The operation is very similar to the symmetric cipher discussion. 3 During initialization, the struct sockaddr data structure must be 4 filled as follows: 5 </p><pre class="programlisting"> 6struct sockaddr_alg sa = { 7 .salg_family = AF_ALG, 8 .salg_type = "aead", /* this selects the symmetric cipher */ 9 .salg_name = "gcm(aes)" /* this is the cipher name */ 10}; 11 </pre><p> 12 Before data can be sent to the kernel using the write/send system 13 call family, the consumer must set the key. The key setting is 14 described with the setsockopt invocation below. 15 </p><p> 16 In addition, before data can be sent to the kernel using the 17 write/send system call family, the consumer must set the authentication 18 tag size. To set the authentication tag size, the caller must use the 19 setsockopt invocation described below. 20 </p><p> 21 Using the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is 22 specified with the data structure provided by the sendmsg() system call. 23 </p><p> 24 The sendmsg system call parameter of struct msghdr is embedded into the 25 struct cmsghdr data structure. See recv(2) and cmsg(3) for more 26 information on how the cmsghdr data structure is used together with the 27 send/recv system call family. That cmsghdr data structure holds the 28 following information specified with a separate header instances: 29 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 30 specification of the cipher operation type with one of these flags: 31 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem"><p>ALG_OP_ENCRYPT - encryption of data</p></li><li class="listitem"><p>ALG_OP_DECRYPT - decryption of data</p></li></ul></div></li><li class="listitem"><p> 32 specification of the IV information marked with the flag ALG_SET_IV 33 </p></li><li class="listitem"><p> 34 specification of the associated authentication data (AAD) with the 35 flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together 36 with the plaintext / ciphertext. See below for the memory structure. 37 </p></li></ul></div><p> 38 The send system call family allows the following flag to be specified: 39 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 40 MSG_MORE: If this flag is set, the send system call acts like a 41 cipher update function where more input data is expected 42 with a subsequent invocation of the send system call. 43 </p></li></ul></div><p> 44 Note: The kernel reports -EINVAL for any unexpected data. The caller 45 must make sure that all data matches the constraints given in 46 /proc/crypto for the selected cipher. 47 </p><p> 48 With the recv() system call, the application can read the result of 49 the cipher operation from the kernel crypto API. The output buffer 50 must be at least as large as defined with the memory structure below. 51 If the output data size is smaller, the cipher operation is not performed. 52 </p><p> 53 The authenticated decryption operation may indicate an integrity error. 54 Such breach in integrity is marked with the -EBADMSG error code. 55 </p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idp1097375068"></a>AEAD Memory Structure</h3></div></div></div><p> 56 The AEAD cipher operates with the following information that 57 is communicated between user and kernel space as one data stream: 58 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>plaintext or ciphertext</p></li><li class="listitem"><p>associated authentication data (AAD)</p></li><li class="listitem"><p>authentication tag</p></li></ul></div><p> 59 The sizes of the AAD and the authentication tag are provided with 60 the sendmsg and setsockopt calls (see there). As the kernel knows 61 the size of the entire data stream, the kernel is now able to 62 calculate the right offsets of the data components in the data 63 stream. 64 </p><p> 65 The user space caller must arrange the aforementioned information 66 in the following order: 67 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 68 AEAD encryption input: AAD || plaintext 69 </p></li><li class="listitem"><p> 70 AEAD decryption input: AAD || ciphertext || authentication tag 71 </p></li></ul></div><p> 72 The output buffer the user space caller provides must be at least as 73 large to hold the following data: 74 </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p> 75 AEAD encryption output: ciphertext || authentication tag 76 </p></li><li class="listitem"><p> 77 AEAD decryption output: plaintext 78 </p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch04s05.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="User.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch04s07.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Symmetric Cipher API </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Random Number Generator API</td></tr></table></div></body></html> 79