/usr/share/doc/libkcapi/html/ch02s04.html is in libkcapi-doc 1.0.3-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>AEAD Cipher API</title><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Linux Kernel Crypto API User Space Interface Library"><link rel="up" href="Usage.html" title="Chapter 2. Programming Guidelines"><link rel="prev" href="ch02s03.html" title="Asynchronous Symmetric Cipher API"><link rel="next" href="ch02s05.html" title="Message Digest 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="ch02s03.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Programming Guidelines</th><td width="20%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm71"></a>AEAD Cipher API</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="sect2"><a href="ch02s04.html#idm79">Aynchronous AEAD Cipher API</a></span></dt><dt><span class="sect2"><a href="ch02s04.html#idm82">AEAD Memory Structure</a></span></dt></dl></div><p>
AEAD ciphers implement a very similar API approach as the symmetric ciphers:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
One-shot API: The one-shot API performs an encryption operation
with one API call. With that API call, the caller provides the input
data and immediately receives the output from the cipher operation.
</p></li><li class="listitem"><p>
Stream API: With the stream API, the caller can implement independent
calls to send data to the kernel and receive data from the kernel.
However, unlike the symmetric cipher API, one AEAD cipher operation
must be considered as one unit as the integrity value is calculated
for one encryption or decryption operation. The caller can use multiple
calls to provide the input data. The last chunk of data must be
sent to the kernel with the API call marking the last submission.
Then, the cipher operation can be triggered with the recvmsg invocation.
It is possible to implement a multi-threaded application as the
thread triggering the cipher operation is put to sleep until the last
block is received. Once the last block is received, the caller waiting
on the cipher operation is woken up to obtain the data.
</p></li></ul></div><p>
</p><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm79"></a>Aynchronous AEAD Cipher API</h3></div></div></div><p>
Similarly to the symmetric cipher API, the AEAD API supports
asynchronous operation as well. The same concept regarding the IOVECs
applies as discussed for the asynchronous symmetric cipher API above.
</p></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="idm82"></a>AEAD Memory Structure</h3></div></div></div><p>
When using the stream API for AEAD, the caller must observe a particular
order of data components. It is permissible that for each of the following
data components multiple send calls are used. But in total, all send calls
must send the AEAD data in the requested sequence. That sequence has
changed with kernel 4.9. The following sequence is applicable to kernel
versions up to and including 4.8:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Associated Authentication Data: The AAD must be provided as a first
chunk.</p></li><li class="listitem"><p>Plaintext / Ciphertext: Following the AAD, the entire plaintext
or ciphertext is provided that shall be encrypted and integrity protected
or decrypted and whose integrity shall be verified.</p></li><li class="listitem"><p>Authentication Tag: Regardless of an encryption or decryption,
the authentication tag memory must be provided.</p></li></ol></div><p>
The caller must provide memory that is identical in size for the input and
output data, even parts of the memory is unused. For example, for
encryption, the AEAD cipher operation only needs the AAD and the plaintext.
Nonetheless, the interface requires that the memory is big enough to
hold the tag as well. This requirement particularly aids the in-place
cipher operation.
</p><p>
Starting with kernel 4.9, the interface changed slightly such that the
authentication tag memory is only needed in the output buffer for
encryption and in the input buffer for decryption.
</p><p>
To allow the calling application to be agnostic about the differences
in the kernel interface, the calling application is offered additional
API calls which should be used as follows:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Obtain the required input buffer length for the cryptographic
operation using the calls kcapi_aead_inbuflen_enc or
kcapi_aead_inbuflen_dec.</p></li><li class="listitem"><p>Obtain the required output buffer length for the cryptographic
operation using the APIs of kcapi_aead_outbuflen_enc or
kcapi_aead_outbuflen_dec.</p></li><li class="listitem"><p>For an in-place operation with a linear buffer, do the following
(for an example, see test/kcapi-main.c:cavs_aead()):
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>allocate memory that is max(inbuflen, outbuflen),</p></li><li class="listitem"><p>call to kcapi_aead_getdata_input and kcapi_aead_getdata_output
with the allocated memory pointer to obtain the pointers into that
allocated memory where the AAD, plaintext / ciphertext and tag is to be
provided,</p></li><li class="listitem"><p>fill these AAD, plaintext/ciphertext and tag pointers with the
respective data if they are non-NULL -- note, a NULL pointer may
be returned for the tag pointer,</p></li><li class="listitem"><p>invoke the crypto operation with the pointer to the allocated
buffer and inbuflen is supplied to the.</p></li></ol></div><p>
</p></li><li class="listitem"><p>For for separate, potentially non-contiguous buffers, do the
following (for an example, see test/kcapi-main.c:cavs_aead_stream()):
</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>ensure that your total buffer size for input and output complies
with the result from the buffer lengths supplied by the aforementioned
API calls,</p></li><li class="listitem"><p>call to kcapi_aead_getdata_input and kcapi_aead_getdata_output
with NULL pointers for the memory buffers to obtain the lengths for the
AEAD data components,</p></li><li class="listitem"><p>initialize the IOVECs and/or invoke the stream API with the
independent buffers with the AAD, plaintext/ciphertext and tag if the
associated length values are non-zero.</p></li></ol></div><p>
</p></li></ol></div><p>
If the caller chooses to not implement an in-place operation, the kernel
will copy the AAD data into the output buffer, so that the destination
buffer will hold the the ciphertext or plaintext, the AAD data and the
authentication tag (encryption only). The memory structure of the
destination buffer is identical to the source buffer. (This is currently
not yet implemented for all ciphers and will be fixed in future
kernel versions.)
</p></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s03.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="Usage.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ch02s05.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Asynchronous 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"> Message Digest API</td></tr></table></div></body></html>
|