/usr/share/doc/libkcapi/html/ch02s03.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 | <html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>Asynchronous Symmetric 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="ch02s02.html" title="Synchronous Symmetric Cipher API"><link rel="next" href="ch02s04.html" title="AEAD Cipher 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">Asynchronous Symmetric Cipher API</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ch02s02.html">Prev</a> </td><th width="60%" align="center">Chapter 2. Programming Guidelines</th><td width="20%" align="right"> <a accesskey="n" href="ch02s04.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="idm63"></a>Asynchronous Symmetric Cipher API</h2></div></div></div><p>
In addition to the symmetric cipher API, an asynchronous API is offered
with the kcapi_cipher_*_aio and kcapi_aead_*_aio API calls. The concept of
that API is to perform parallel operations of multiple encryption or
decryption data streams.
</p><p>
To use the AIO API, the caller must use the KCAPI_INIT_AIO with the
kcapi_cipher_init function call to set up all additional logistics for
handing AIO. That means, users which are not interested in AIO will
not suffer from the additional memory overhead including the time required
to allocate that memory required for AIO.
</p><p>
This implies that the asynchronous API handles the scatter-gather lists
referenced by the IOVECs differently compared to the synchronous APIs.
Whereas the synchronous API references different parts of plaintext or
ciphertext that are processed with one cipher operation, the IOVECs of the
asynchronous API references plaintext or ciphertext where each IOVEC
is processed with an independent cipher operation. I.e. when using AES-CBC
with the synchronous API and the scatter-gather lists, all input data is
sent to one invocation of the AES-CBC cipher. Conversely, the asynchronous
API invokes one individual AES-CBC operation for each individual IOVEC.
</p><p>
The asynchronous API is designed to perform an in-place operation where
the buffers for the input data are used to store the output data.
</p><p>
The asynchronous API in libkcapi as well as the kernel has a higher
overhead for setting the cipher operation up. That means that if the
caller only uses a one IOVEC with one associated cipher operation, the
asynchronous API is expected to be slower compared to the synchronous API.
But already with two or three combined cipher operations, the AIO
API should be faster than the synchronous API. You may test the difference
in performance with the test/kcapi test application by using the options -f
for measuring the time of cipher operations in nanoseconds, -d for the
number of parallel invocations and -x 1 for a symmetric one-shot cipher
invocation and -x 9 for an asymmetric cipher operation with the given input
data.
</p><p>
The kernel offers the AIO interface since kernel version 4.1 (symmetric
ciphers) and 4.7 (AEAD ciphers). The libkcapi implements a transparent
fallback to use the synchronous cipher API in case the AIO support is not
present for the current kernel. This allows the calling users to be
agnostic of the kernel support. Nonetheless, libkcapi with report the lack
of AIO support if AIO is requested as the fallback implementation has a
slight performance overhead.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ch02s02.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="ch02s04.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Synchronous 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"> AEAD Cipher API</td></tr></table></div></body></html>
|