3sphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget'/translations/zh_CN/crypto/userspace-ifmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/zh_TW/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/it_IT/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ja_JP/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/ko_KR/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/pt_BR/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget'/translations/sp_SP/crypto/userspace-ifmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhtarget)}(h.. _crypto_userspace_interface:h]h}(h]h ]h"]h$]h&]refidcrypto-userspace-interfaceuh1hhKhhhhhA/var/lib/git/docbuild/linux/Documentation/crypto/userspace-if.rstubhsection)}(hhh](htitle)}(hUser Space Interfaceh]hUser Space Interface}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Introductionh]h Introduction}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hAF_ALG provides unprivileged userspace programs access to arbitrary hash, symmetric cipher, AEAD, and RNG algorithms that are implemented in kernel-mode code.h]hAF_ALG provides unprivileged userspace programs access to arbitrary hash, symmetric cipher, AEAD, and RNG algorithms that are implemented in kernel-mode code.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hAF_ALG is insecure and is deprecated. Originally added to the kernel in 2010, most kernel developers now consider it to be a mistake. Support for hardware accelerators, which was the original purpose of AF_ALG, has been removed.h]hAF_ALG is insecure and is deprecated. Originally added to the kernel in 2010, most kernel developers now consider it to be a mistake. Support for hardware accelerators, which was the original purpose of AF_ALG, has been removed.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhhhubh)}(hBAF_ALG continues to be supported only for backwards compatibility.h]hBAF_ALG continues to be supported only for backwards compatibility.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hStarting in Linux v7.3, the set of algorithms supported by AF_ALG is limited by default. See :ref:`/proc/sys/crypto/af_alg_restrict `.h](h]Starting in Linux v7.3, the set of algorithms supported by AF_ALG is limited by default. See }(hjhhhNhNubh)}(h9:ref:`/proc/sys/crypto/af_alg_restrict `h]hinline)}(hj h]h /proc/sys/crypto/af_alg_restrict}(hj$hhhNhNubah}(h]h ](xrefstdstd-refeh"]h$]h&]uh1j"hjubah}(h]h ]h"]h$]h&]refdoccrypto/userspace-if refdomainj/reftyperef refexplicitrefwarn reftargetaf_alg_restrictuh1hhhhKhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubh)}(hOn systems where no programs using AF_ALG remain, the support for it should be disabled entirely by setting ``/proc/sys/crypto/af_alg_restrict`` to 2 or by disabling ``CONFIG_CRYPTO_USER_API_*`` in the kernel configuration.h](hlOn systems where no programs using AF_ALG remain, the support for it should be disabled entirely by setting }(hjMhhhNhNubhliteral)}(h$``/proc/sys/crypto/af_alg_restrict``h]h /proc/sys/crypto/af_alg_restrict}(hjWhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjMubh to 2 or by disabling }(hjMhhhNhNubjV)}(h``CONFIG_CRYPTO_USER_API_*``h]hCONFIG_CRYPTO_USER_API_*}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjMubh in the kernel configuration.}(hjMhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhhhhubeh}(h] introductionah ]h"] introductionah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h Deprecationh]h Deprecation}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hAF_ALG was originally intended to provide userspace programs access to crypto accelerators that they wouldn't otherwise have access to.h]hAF_ALG was originally intended to provide userspace programs access to crypto accelerators that they wouldn’t otherwise have access to.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hHowever, that capability turned out to not be useful on very many systems. More significantly, the actual implementation exposes a vastly greater amount of functionality than that. It actually provides access to all software algorithms.h]hHowever, that capability turned out to not be useful on very many systems. More significantly, the actual implementation exposes a vastly greater amount of functionality than that. It actually provides access to all software algorithms.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hjhhubh)}(hX6This includes arbitrary compositions of different algorithms created via a complex template system, as well as algorithms that only make sense as internal implementation details of other algorithms. In the past, it also included full zero-copy support, which was difficult for the kernel to implement securely.h]hX6This includes arbitrary compositions of different algorithms created via a complex template system, as well as algorithms that only make sense as internal implementation details of other algorithms. In the past, it also included full zero-copy support, which was difficult for the kernel to implement securely.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK$hjhhubh)}(hUltimately, these algorithms are just math computations. They use the same instructions that userspace programs already have access to, just accessed in a much more convoluted and less efficient way.h]hUltimately, these algorithms are just math computations. They use the same instructions that userspace programs already have access to, just accessed in a much more convoluted and less efficient way.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK)hjhhubh)}(hIndeed, userspace code is nearly always what is being used anyway. These same algorithms are widely implemented in userspace crypto libraries.h]hIndeed, userspace code is nearly always what is being used anyway. These same algorithms are widely implemented in userspace crypto libraries.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hjhhubh)}(hXEven when zero-copy and off-CPU accelerators were supported, AF_ALG was usually much slower than optimized software cryptography in userspace. This was especially true for the small message sizes usually seen in performance-critical workloads. While it was possible to demonstrate performance wins for hashing large files on embedded devices, it is hard to imagine a situation where this would be performance-critical.h]hXEven when zero-copy and off-CPU accelerators were supported, AF_ALG was usually much slower than optimized software cryptography in userspace. This was especially true for the small message sizes usually seen in performance-critical workloads. While it was possible to demonstrate performance wins for hashing large files on embedded devices, it is hard to imagine a situation where this would be performance-critical.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK0hjhhubh)}(hXNowadays, AF_ALG no longer supports zero-copy or off-CPU accelerators. Therefore, it is *always* slower than an optimized userspace implementation, even for large messages. The only possible advantage left is that it avoids duplicating code between kernel and userspace. However, userspace implementations, especially hardware-accelerated ones, do not need to be large. Just because OpenSSL is huge does not mean that all userspace cryptography libraries are.h](hXNowadays, AF_ALG no longer supports zero-copy or off-CPU accelerators. Therefore, it is }(hjhhhNhNubhemphasis)}(h*always*h]halways}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhXk slower than an optimized userspace implementation, even for large messages. The only possible advantage left is that it avoids duplicating code between kernel and userspace. However, userspace implementations, especially hardware-accelerated ones, do not need to be large. Just because OpenSSL is huge does not mean that all userspace cryptography libraries are.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK7hjhhubh)}(hMeanwhile, AF_ALG hasn't been withstanding modern vulnerability discovery tools such as syzbot and large language models. It receives a steady stream of CVEs. Some of the examples include:h]hMeanwhile, AF_ALG hasn’t been withstanding modern vulnerability discovery tools such as syzbot and large language models. It receives a steady stream of CVEs. Some of the examples include:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK?hjhhubh bullet_list)}(hhh](h list_item)}(hCVE-2026-31677h]h)}(hj'h]hCVE-2026-31677}(hj)hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKChj%ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h"CVE-2026-31431 (https://copy.fail)h]h)}(hj>h](hCVE-2026-31431 (}(hj@hhhNhNubh reference)}(hhttps://copy.failh]hhttps://copy.fail}(hjIhhhNhNubah}(h]h ]h"]h$]h&]refurijKuh1jGhj@ubh)}(hj@hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKDhj<ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2025-38079h]h)}(hjjh]hCVE-2025-38079}(hjlhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKEhjhubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2025-37808h]h)}(hjh]hCVE-2025-37808}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKFhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2024-26824h]h)}(hjh]hCVE-2024-26824}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKGhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2022-48781h]h)}(hjh]hCVE-2022-48781}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKHhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h CVE-2019-8912h]h)}(hjh]h CVE-2019-8912}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKIhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2018-14619h]h)}(hjh]hCVE-2018-14619}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKJhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2017-18075h]h)}(hjh]hCVE-2017-18075}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKKhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2017-17806h]h)}(hj h]hCVE-2017-17806}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKLhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2017-17805h]h)}(hj"h]hCVE-2017-17805}(hj$hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKMhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2016-10147h]h)}(hj9h]hCVE-2016-10147}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKNhj7ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h CVE-2015-8970h]h)}(hjPh]h CVE-2015-8970}(hjRhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKOhjNubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h CVE-2015-3331h]h)}(hjgh]h CVE-2015-3331}(hjihhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKPhjeubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h CVE-2014-9644h]h)}(hj~h]h CVE-2014-9644}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKQhj|ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(h CVE-2013-7421h]h)}(hjh]h CVE-2013-7421}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKRhjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCVE-2011-4081 h]h)}(h CVE-2011-4081h]h CVE-2011-4081}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShjubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubeh}(h]h ]h"]h$]h&]bullet-uh1jhhhKChjhhubh)}(hHardware accelerator drivers are frequently buggy. To reduce attack surface, AF_ALG now only provides access to algorithms implemented in software. This means that AF_ALG no longer fulfills its original purpose.h]hHardware accelerator drivers are frequently buggy. To reduce attack surface, AF_ALG now only provides access to algorithms implemented in software. This means that AF_ALG no longer fulfills its original purpose.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKUhjhhubh)}(hX)It is recommended that, whenever possible, userspace programs be migrated to userspace crypto code (which again, is what is normally used anyway) and ``CONFIG_CRYPTO_USER_API_*`` be disabled. On systems that use SELinux, SELinux can also be used to restrict the use of AF_ALG to trusted programs.h](hIt is recommended that, whenever possible, userspace programs be migrated to userspace crypto code (which again, is what is normally used anyway) and }(hjhhhNhNubjV)}(h``CONFIG_CRYPTO_USER_API_*``h]hCONFIG_CRYPTO_USER_API_*}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jUhjubhw be disabled. On systems that use SELinux, SELinux can also be used to restrict the use of AF_ALG to trusted programs.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKYhjhhubh)}(hnThe remainder of this documentation provides the historical documentation for the deprecated AF_ALG interface.h]hnThe remainder of this documentation provides the historical documentation for the deprecated AF_ALG interface.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK^hjhhubeh}(h] deprecationah ]h"] deprecationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hUser Space API General Remarksh]hUser Space API General Remarks}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKbubh)}(heThe kernel crypto API is accessible from user space. Currently, the following ciphers are accessible:h]heThe kernel crypto API is accessible from user space. Currently, the following ciphers are accessible:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKdhjhhubj)}(hhh](j$)}(h;Message digest including keyed message digest (HMAC, CMAC) h]h)}(h:Message digest including keyed message digest (HMAC, CMAC)h]h:Message digest including keyed message digest (HMAC, CMAC)}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKghj0ubah}(h]h ]h"]h$]h&]uh1j#hj-hhhhhNubj$)}(hSymmetric ciphers h]h)}(hSymmetric ciphersh]hSymmetric ciphers}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKihjHubah}(h]h ]h"]h$]h&]uh1j#hj-hhhhhNubj$)}(h AEAD ciphers h]h)}(h AEAD ciphersh]h AEAD ciphers}(hjdhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKkhj`ubah}(h]h ]h"]h$]h&]uh1j#hj-hhhhhNubj$)}(hRandom Number Generators h]h)}(hRandom Number Generatorsh]hRandom Number Generators}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKmhjxubah}(h]h ]h"]h$]h&]uh1j#hj-hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKghjhhubh)}(hThe interface is provided via socket type using the type AF_ALG. In addition, the setsockopt option type is SOL_ALG. In case the user space header files do not export these flags yet, use the following macros:h]hThe interface is provided via socket type using the type AF_ALG. In addition, the setsockopt option type is SOL_ALG. In case the user space header files do not export these flags yet, use the following macros:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKohjhhubh literal_block)}(hR#ifndef AF_ALG #define AF_ALG 38 #endif #ifndef SOL_ALG #define SOL_ALG 279 #endifh]hR#ifndef AF_ALG #define AF_ALG 38 #endif #ifndef SOL_ALG #define SOL_ALG 279 #endif}hjsbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1jhhhKuhjhhubh)}(hA cipher is accessed with the same name as done for the in-kernel API calls. This includes the generic vs. unique naming schema for ciphers as well as the enforcement of priorities for generic names.h]hA cipher is accessed with the same name as done for the in-kernel API calls. This includes the generic vs. unique naming schema for ciphers as well as the enforcement of priorities for generic names.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK}hjhhubh)}(hX To interact with the kernel crypto API, a socket must be created by the user space application. User space invokes the cipher operation with the send()/write() system call family. The result of the cipher operation is obtained with the read()/recv() system call family.h]hX To interact with the kernel crypto API, a socket must be created by the user space application. User space invokes the cipher operation with the send()/write() system call family. The result of the cipher operation is obtained with the read()/recv() system call family.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hThe following API calls assume that the socket descriptor is already opened by the user space application and discusses only the kernel crypto API specific invocations.h]hThe following API calls assume that the socket descriptor is already opened by the user space application and discusses only the kernel crypto API specific invocations.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(h_To initialize the socket interface, the following sequence has to be performed by the consumer:h]h_To initialize the socket interface, the following sequence has to be performed by the consumer:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubhenumerated_list)}(hhh](j$)}(hvCreate a socket of type AF_ALG with the struct sockaddr_alg parameter specified below for the different cipher types. h]h)}(huCreate a socket of type AF_ALG with the struct sockaddr_alg parameter specified below for the different cipher types.h]huCreate a socket of type AF_ALG with the struct sockaddr_alg parameter specified below for the different cipher types.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubj$)}(h'Invoke bind with the socket descriptor h]h)}(h&Invoke bind with the socket descriptorh]h&Invoke bind with the socket descriptor}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubj$)}(hXFInvoke accept with the socket descriptor. The accept system call returns a new file descriptor that is to be used to interact with the particular cipher instance. When invoking send/write or recv/read system calls to send data to the kernel or obtain data from the kernel, the file descriptor returned by accept must be used. h]h)}(hXEInvoke accept with the socket descriptor. The accept system call returns a new file descriptor that is to be used to interact with the particular cipher instance. When invoking send/write or recv/read system calls to send data to the kernel or obtain data from the kernel, the file descriptor returned by accept must be used.h]hXEInvoke accept with the socket descriptor. The accept system call returns a new file descriptor that is to be used to interact with the particular cipher instance. When invoking send/write or recv/read system calls to send data to the kernel or obtain data from the kernel, the file descriptor returned by accept must be used.}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj#ubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1jhjhhhhhKubeh}(h]user-space-api-general-remarksah ]h"]user space api general remarksah$]h&]uh1hhhhhhhhKbubh)}(hhh](h)}(hIn-place Cipher operationh]hIn-place Cipher operation}(hjQhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjNhhhhhKubh)}(hXJust like the in-kernel operation of the kernel crypto API, the user space interface allows the cipher operation in-place. That means that the input buffer used for the send/write system call and the output buffer used by the read/recv system call may be one and the same. This is of particular interest for symmetric cipher operations where a copying of the output data to its final destination can be avoided.h]hXJust like the in-kernel operation of the kernel crypto API, the user space interface allows the cipher operation in-place. That means that the input buffer used for the send/write system call and the output buffer used by the read/recv system call may be one and the same. This is of particular interest for symmetric cipher operations where a copying of the output data to its final destination can be avoided.}(hj_hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNhhubh)}(hIf a consumer on the other hand wants to maintain the plaintext and the ciphertext in different memory locations, all a consumer needs to do is to provide different memory pointers for the encryption and decryption operation.h]hIf a consumer on the other hand wants to maintain the plaintext and the ciphertext in different memory locations, all a consumer needs to do is to provide different memory pointers for the encryption and decryption operation.}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjNhhubeh}(h]in-place-cipher-operationah ]h"]in-place cipher operationah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hMessage Digest APIh]hMessage Digest API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThe message digest type to be used for the cipher operation is selected when invoking the bind syscall. bind requires the caller to provide a filled struct sockaddr data structure. This data structure must be filled as follows:h]hThe message digest type to be used for the cipher operation is selected when invoking the bind syscall. bind requires the caller to provide a filled struct sockaddr data structure. This data structure must be filled as follows:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "hash", /* this selects the hash logic in the kernel */ .salg_name = "sha1" /* this is the cipher name */ };h]hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "hash", /* this selects the hash logic in the kernel */ .salg_name = "sha1" /* this is the cipher name */ };}hjsbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hX The salg_type value "hash" applies to message digests and keyed message digests. Though, a keyed message digest is referenced by the appropriate salg_name. Please see below for the setsockopt interface that explains how the key can be set for a keyed message digest.h]hXThe salg_type value “hash” applies to message digests and keyed message digests. Though, a keyed message digest is referenced by the appropriate salg_name. Please see below for the setsockopt interface that explains how the key can be set for a keyed message digest.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hUsing the send() system call, the application provides the data that should be processed with the message digest. The send system call allows the following flags to be specified:h]hUsing the send() system call, the application provides the data that should be processed with the message digest. The send system call allows the following flags to be specified:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh]j$)}(hMSG_MORE: If this flag is set, the send system call acts like a message digest update function where the final hash is not yet calculated. If the flag is not set, the send system call calculates the final message digest immediately. h]h)}(hMSG_MORE: If this flag is set, the send system call acts like a message digest update function where the final hash is not yet calculated. If the flag is not set, the send system call calculates the final message digest immediately.h]hMSG_MORE: If this flag is set, the send system call acts like a message digest update function where the final hash is not yet calculated. If the flag is not set, the send system call calculates the final message digest immediately.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hWith the recv() system call, the application can read the message digest from the kernel crypto API. If the buffer is too small for the message digest, the flag MSG_TRUNC is set by the kernel.h]hWith the recv() system call, the application can read the message digest from the kernel crypto API. If the buffer is too small for the message digest, the flag MSG_TRUNC is set by the kernel.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hIn order to set a message digest key, the calling application must use the setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the key is not set the HMAC operation is performed without the initial HMAC state change caused by the key.h]hIn order to set a message digest key, the calling application must use the setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the key is not set the HMAC operation is performed without the initial HMAC state change caused by the key.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]message-digest-apiah ]h"]message digest apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hSymmetric Cipher APIh]hSymmetric Cipher API}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhKubh)}(hThe operation is very similar to the message digest discussion. During initialization, the struct sockaddr data structure must be filled as follows:h]hThe operation is very similar to the message digest discussion. During initialization, the struct sockaddr data structure must be filled as follows:}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "skcipher", /* this selects the symmetric cipher */ .salg_name = "cbc(aes)" /* this is the cipher name */ };h]hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "skcipher", /* this selects the symmetric cipher */ .salg_name = "cbc(aes)" /* this is the cipher name */ };}hj0sbah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hBefore data can be sent to the kernel using the write/send system call family, the consumer must set the key. The key setting is described with the setsockopt invocation below.h]hBefore data can be sent to the kernel using the write/send system call family, the consumer must set the key. The key setting is described with the setsockopt invocation below.}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hUsing the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is specified with the data structure provided by the sendmsg() system call.h]hUsing the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is specified with the data structure provided by the sendmsg() system call.}(hjLhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXUThe sendmsg system call parameter of struct msghdr is embedded into the struct cmsghdr data structure. See recv(2) and cmsg(3) for more information on how the cmsghdr data structure is used together with the send/recv system call family. That cmsghdr data structure holds the following information specified with a separate header instances:h]hXUThe sendmsg system call parameter of struct msghdr is embedded into the struct cmsghdr data structure. See recv(2) and cmsg(3) for more information on how the cmsghdr data structure is used together with the send/recv system call family. That cmsghdr data structure holds the following information specified with a separate header instances:}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh](j$)}(hspecification of the cipher operation type with one of these flags: - ALG_OP_ENCRYPT - encryption of data - ALG_OP_DECRYPT - decryption of data h](h)}(hCspecification of the cipher operation type with one of these flags:h]hCspecification of the cipher operation type with one of these flags:}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjkubj)}(hhh](j$)}(h$ALG_OP_ENCRYPT - encryption of data h]h)}(h#ALG_OP_ENCRYPT - encryption of datah]h#ALG_OP_ENCRYPT - encryption of data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hj}ubj$)}(h$ALG_OP_DECRYPT - decryption of data h]h)}(h#ALG_OP_DECRYPT - decryption of datah]h#ALG_OP_DECRYPT - decryption of data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hj}ubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjkubeh}(h]h ]h"]h$]h&]uh1j#hjhhhhNhNubj$)}(hDspecification of the IV information marked with the flag ALG_SET_IV h]h)}(hCspecification of the IV information marked with the flag ALG_SET_IVh]hCspecification of the IV information marked with the flag ALG_SET_IV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hFThe send system call family allows the following flag to be specified:h]hFThe send system call family allows the following flag to be specified:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubj)}(hhh]j$)}(hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call. h]h)}(hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call.h]hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubah}(h]h ]h"]h$]h&]jjuh1jhhhKhjhhubh)}(hNote: The kernel reports -EINVAL for any unexpected data. The caller must make sure that all data matches the constraints given in /proc/crypto for the selected cipher.h]hNote: The kernel reports -EINVAL for any unexpected data. The caller must make sure that all data matches the constraints given in /proc/crypto for the selected cipher.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubh)}(hXFWith the recv() system call, the application can read the result of the cipher operation from the kernel crypto API. The output buffer must be at least as large as to hold all blocks of the encrypted or decrypted data. If the output data size is smaller, only as many blocks are returned that fit into that output buffer size.h]hXFWith the recv() system call, the application can read the result of the cipher operation from the kernel crypto API. The output buffer must be at least as large as to hold all blocks of the encrypted or decrypted data. If the output data size is smaller, only as many blocks are returned that fit into that output buffer size.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjhhubeh}(h]symmetric-cipher-apiah ]h"]symmetric cipher apiah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hAEAD Cipher APIh]hAEAD Cipher API}(hj0hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj-hhhhhMubh)}(hThe operation is very similar to the symmetric cipher discussion. During initialization, the struct sockaddr data structure must be filled as follows:h]hThe operation is very similar to the symmetric cipher discussion. During initialization, the struct sockaddr data structure must be filled as follows:}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubj)}(hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "aead", /* this selects the symmetric cipher */ .salg_name = "gcm(aes)" /* this is the cipher name */ };h]hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "aead", /* this selects the symmetric cipher */ .salg_name = "gcm(aes)" /* this is the cipher name */ };}hjLsbah}(h]h ]h"]h$]h&]jjuh1jhhhMhj-hhubh)}(hBefore data can be sent to the kernel using the write/send system call family, the consumer must set the key. The key setting is described with the setsockopt invocation below.h]hBefore data can be sent to the kernel using the write/send system call family, the consumer must set the key. The key setting is described with the setsockopt invocation below.}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubh)}(hIn addition, before data can be sent to the kernel using the write/send system call family, the consumer must set the authentication tag size. To set the authentication tag size, the caller must use the setsockopt invocation described below.h]hIn addition, before data can be sent to the kernel using the write/send system call family, the consumer must set the authentication tag size. To set the authentication tag size, the caller must use the setsockopt invocation described below.}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubh)}(hUsing the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is specified with the data structure provided by the sendmsg() system call.h]hUsing the sendmsg() system call, the application provides the data that should be processed for encryption or decryption. In addition, the IV is specified with the data structure provided by the sendmsg() system call.}(hjvhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj-hhubh)}(hXUThe sendmsg system call parameter of struct msghdr is embedded into the struct cmsghdr data structure. See recv(2) and cmsg(3) for more information on how the cmsghdr data structure is used together with the send/recv system call family. That cmsghdr data structure holds the following information specified with a separate header instances:h]hXUThe sendmsg system call parameter of struct msghdr is embedded into the struct cmsghdr data structure. See recv(2) and cmsg(3) for more information on how the cmsghdr data structure is used together with the send/recv system call family. That cmsghdr data structure holds the following information specified with a separate header instances:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM"hj-hhubj)}(hhh](j$)}(hspecification of the cipher operation type with one of these flags: - ALG_OP_ENCRYPT - encryption of data - ALG_OP_DECRYPT - decryption of data h](h)}(hCspecification of the cipher operation type with one of these flags:h]hCspecification of the cipher operation type with one of these flags:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM(hjubj)}(hhh](j$)}(h$ALG_OP_ENCRYPT - encryption of data h]h)}(h#ALG_OP_ENCRYPT - encryption of datah]h#ALG_OP_ENCRYPT - encryption of data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM*hjubah}(h]h ]h"]h$]h&]uh1j#hjubj$)}(h$ALG_OP_DECRYPT - decryption of data h]h)}(h#ALG_OP_DECRYPT - decryption of datah]h#ALG_OP_DECRYPT - decryption of data}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM,hjubah}(h]h ]h"]h$]h&]uh1j#hjubeh}(h]h ]h"]h$]h&]jjuh1jhhhM*hjubeh}(h]h ]h"]h$]h&]uh1j#hjhhhNhNubj$)}(hDspecification of the IV information marked with the flag ALG_SET_IV h]h)}(hCspecification of the IV information marked with the flag ALG_SET_IVh]hCspecification of the IV information marked with the flag ALG_SET_IV}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM.hjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubj$)}(hspecification of the associated authentication data (AAD) with the flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together with the plaintext / ciphertext. See below for the memory structure. h]h)}(hspecification of the associated authentication data (AAD) with the flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together with the plaintext / ciphertext. See below for the memory structure.h]hspecification of the associated authentication data (AAD) with the flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together with the plaintext / ciphertext. See below for the memory structure.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhM(hj-hhubh)}(hFThe send system call family allows the following flag to be specified:h]hFThe send system call family allows the following flag to be specified:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM4hj-hhubj)}(hhh]j$)}(hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call. h]h)}(hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call.h]hMSG_MORE: If this flag is set, the send system call acts like a cipher update function where more input data is expected with a subsequent invocation of the send system call.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj-ubah}(h]h ]h"]h$]h&]uh1j#hj*hhhhhNubah}(h]h ]h"]h$]h&]jjuh1jhhhM6hj-hhubh)}(hNote: The kernel reports -EINVAL for any unexpected data. The caller must make sure that all data matches the constraints given in /proc/crypto for the selected cipher.h]hNote: The kernel reports -EINVAL for any unexpected data. The caller must make sure that all data matches the constraints given in /proc/crypto for the selected cipher.}(hjKhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM:hj-hhubh)}(hXWith the recv() system call, the application can read the result of the cipher operation from the kernel crypto API. The output buffer must be at least as large as defined with the memory structure below. If the output data size is smaller, the cipher operation is not performed.h]hXWith the recv() system call, the application can read the result of the cipher operation from the kernel crypto API. The output buffer must be at least as large as defined with the memory structure below. If the output data size is smaller, the cipher operation is not performed.}(hjYhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM>hj-hhubh)}(hThe authenticated decryption operation may indicate an integrity error. Such breach in integrity is marked with the -EBADMSG error code.h]hThe authenticated decryption operation may indicate an integrity error. Such breach in integrity is marked with the -EBADMSG error code.}(hjghhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMChj-hhubh)}(hhh](h)}(hAEAD Memory Structureh]hAEAD Memory Structure}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjuhhhhhMGubh)}(h~The AEAD cipher operates with the following information that is communicated between user and kernel space as one data stream:h]h~The AEAD cipher operates with the following information that is communicated between user and kernel space as one data stream:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMIhjuhhubj)}(hhh](j$)}(hplaintext or ciphertext h]h)}(hplaintext or ciphertexth]hplaintext or ciphertext}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMLhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubj$)}(h%associated authentication data (AAD) h]h)}(h$associated authentication data (AAD)h]h$associated authentication data (AAD)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMNhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubj$)}(hauthentication tag h]h)}(hauthentication tagh]hauthentication tag}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMPhjubah}(h]h ]h"]h$]h&]uh1j#hjhhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMLhjuhhubh)}(hXThe sizes of the AAD and the authentication tag are provided with the sendmsg and setsockopt calls (see there). As the kernel knows the size of the entire data stream, the kernel is now able to calculate the right offsets of the data components in the data stream.h]hXThe sizes of the AAD and the authentication tag are provided with the sendmsg and setsockopt calls (see there). As the kernel knows the size of the entire data stream, the kernel is now able to calculate the right offsets of the data components in the data stream.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhjuhhubh)}(hYThe user space caller must arrange the aforementioned information in the following order:h]hYThe user space caller must arrange the aforementioned information in the following order:}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMWhjuhhubj)}(hhh](j$)}(h*AEAD encryption input: AAD \|\| plaintext h]h)}(h)AEAD encryption input: AAD \|\| plaintexth]h)AEAD encryption input: AAD || plaintext}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMZhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hCAEAD decryption input: AAD \|\| ciphertext \|\| authentication tag h]h)}(hBAEAD decryption input: AAD \|\| ciphertext \|\| authentication tagh]hBAEAD decryption input: AAD || ciphertext || authentication tag}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM\hj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMZhjuhhubh)}(hfThe output buffer the user space caller provides must be at least as large to hold the following data:h]hfThe output buffer the user space caller provides must be at least as large to hold the following data:}(hj: hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM^hjuhhubj)}(hhh](j$)}(h;AEAD encryption output: ciphertext \|\| authentication tag h]h)}(h:AEAD encryption output: ciphertext \|\| authentication tagh]h:AEAD encryption output: ciphertext || authentication tag}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMahjK ubah}(h]h ]h"]h$]h&]uh1j#hjH hhhhhNubj$)}(h"AEAD decryption output: plaintext h]h)}(h!AEAD decryption output: plaintexth]h!AEAD decryption output: plaintext}(hjg hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMchjc ubah}(h]h ]h"]h$]h&]uh1j#hjH hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMahjuhhubeh}(h]aead-memory-structureah ]h"]aead memory structureah$]h&]uh1hhj-hhhhhMGubeh}(h]aead-cipher-apiah ]h"]aead cipher apiah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hRandom Number Generator APIh]hRandom Number Generator API}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMfubh)}(hAgain, the operation is very similar to the other APIs. During initialization, the struct sockaddr data structure must be filled as follows:h]hAgain, the operation is very similar to the other APIs. During initialization, the struct sockaddr data structure must be filled as follows:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhhj hhubj)}(hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "rng", /* this selects the random number generator */ .salg_name = "stdrng" /* this is the RNG name */ };h]hstruct sockaddr_alg sa = { .salg_family = AF_ALG, .salg_type = "rng", /* this selects the random number generator */ .salg_name = "stdrng" /* this is the RNG name */ };}hj sbah}(h]h ]h"]h$]h&]jjuh1jhhhMnhj hhubh)}(hXDepending on the RNG type, the RNG must be seeded. The seed is provided using the setsockopt interface to set the key. The SP800-90A DRBGs do not require a seed, but may be seeded. The seed is also known as a *Personalization String* in NIST SP 800-90A standard.h](hDepending on the RNG type, the RNG must be seeded. The seed is provided using the setsockopt interface to set the key. The SP800-90A DRBGs do not require a seed, but may be seeded. The seed is also known as a }(hj hhhNhNubj)}(h*Personalization String*h]hPersonalization String}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh in NIST SP 800-90A standard.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMuhj hhubh)}(hUsing the read()/recvmsg() system calls, random numbers can be obtained. The kernel generates at most 128 bytes in one call. If user space requires more data, multiple calls to read()/recvmsg() must be made.h]hUsing the read()/recvmsg() system calls, random numbers can be obtained. The kernel generates at most 128 bytes in one call. If user space requires more data, multiple calls to read()/recvmsg() must be made.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMzhj hhubh)}(hWARNING: The user space caller may invoke the initially mentioned accept system call multiple times. In this case, the returned file descriptors have the same state.h]hWARNING: The user space caller may invoke the initially mentioned accept system call multiple times. In this case, the returned file descriptors have the same state.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM~hj hhubh)}(hhFollowing CAVP testing interfaces are enabled when kernel is built with CRYPTO_USER_API_RNG_CAVP option:h]hhFollowing CAVP testing interfaces are enabled when kernel is built with CRYPTO_USER_API_RNG_CAVP option:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh](j$)}(hthe concatenation of *Entropy* and *Nonce* can be provided to the RNG via ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires CAP_SYS_ADMIN permission. h]h)}(hthe concatenation of *Entropy* and *Nonce* can be provided to the RNG via ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires CAP_SYS_ADMIN permission.h](hthe concatenation of }(hj hhhNhNubj)}(h *Entropy*h]hEntropy}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh and }(hj hhhNhNubj)}(h*Nonce*h]hNonce}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh can be provided to the RNG via ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires CAP_SYS_ADMIN permission.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(ht*Additional Data* can be provided using the send()/sendmsg() system calls, but only after the entropy has been set. h]h)}(hs*Additional Data* can be provided using the send()/sendmsg() system calls, but only after the entropy has been set.h](j)}(h*Additional Data*h]hAdditional Data}(hjO hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjK ubhb can be provided using the send()/sendmsg() system calls, but only after the entropy has been set.}(hjK hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjG ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubeh}(h]random-number-generator-apiah ]h"]random number generator apiah$]h&]uh1hhhhhhhhMfubh)}(hhh](h)}(hZero-Copy Interfaceh]hZero-Copy Interface}(hj~ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj{ hhhhhMubh)}(hX&AF_ALG used to have zero-copy support, but it was removed due to it being a frequent source of vulnerabilities. For backwards compatibility the splice() and sendfile() system calls are still supported, but the kernel will make an internal copy of the data before passing it to the crypto code.h]hX&AF_ALG used to have zero-copy support, but it was removed due to it being a frequent source of vulnerabilities. For backwards compatibility the splice() and sendfile() system calls are still supported, but the kernel will make an internal copy of the data before passing it to the crypto code.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj{ hhubeh}(h]zero-copy-interfaceah ]h"]zero-copy interfaceah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hSetsockopt Interfaceh]hSetsockopt Interface}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hXIn addition to the read/recv and send/write system call handling to send and retrieve data subject to the cipher operation, a consumer also needs to set the additional information for the cipher operation. This additional information is set using the setsockopt system call that must be invoked with the file descriptor of the open cipher (i.e. the file descriptor returned by the accept system call).h]hXIn addition to the read/recv and send/write system call handling to send and retrieve data subject to the cipher operation, a consumer also needs to set the additional information for the cipher operation. This additional information is set using the setsockopt system call that must be invoked with the file descriptor of the open cipher (i.e. the file descriptor returned by the accept system call).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h6Each setsockopt invocation must use the level SOL_ALG.h]h6Each setsockopt invocation must use the level SOL_ALG.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(hWThe setsockopt interface allows setting the following data using the mentioned optname:h]hWThe setsockopt interface allows setting the following data using the mentioned optname:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubj)}(hhh](j$)}(hALG_SET_KEY -- Setting the key. Key setting is applicable to: - the skcipher cipher type (symmetric ciphers) - the hash cipher type (keyed message digests) - the AEAD cipher type - the RNG cipher type to provide the seed h](h)}(h=ALG_SET_KEY -- Setting the key. Key setting is applicable to:h]h=ALG_SET_KEY -- Setting the key. Key setting is applicable to:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubj)}(hhh](j$)}(h-the skcipher cipher type (symmetric ciphers) h]h)}(h,the skcipher cipher type (symmetric ciphers)h]h,the skcipher cipher type (symmetric ciphers)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j#hj ubj$)}(h-the hash cipher type (keyed message digests) h]h)}(h,the hash cipher type (keyed message digests)h]h,the hash cipher type (keyed message digests)}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j#hj ubj$)}(hthe AEAD cipher type h]h)}(hthe AEAD cipher typeh]hthe AEAD cipher type}(hj) hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj% ubah}(h]h ]h"]h$]h&]uh1j#hj ubj$)}(h(the RNG cipher type to provide the seed h]h)}(h'the RNG cipher type to provide the seedh]h'the RNG cipher type to provide the seed}(hjA hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj= ubah}(h]h ]h"]h$]h&]uh1j#hj ubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj ubeh}(h]h ]h"]h$]h&]uh1j#hj hhhNhNubj$)}(hXALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. This operation behaves the same as ALG_SET_KEY. The decrypted data is copied from a keyring key, and uses that data as the key for symmetric encryption. The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH permission set, otherwise -EPERM is returned. Supports key types: user, logon, encrypted, and trusted. h]hdefinition_list)}(hhh]hdefinition_list_item)}(hXALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. This operation behaves the same as ALG_SET_KEY. The decrypted data is copied from a keyring key, and uses that data as the key for symmetric encryption. The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH permission set, otherwise -EPERM is returned. Supports key types: user, logon, encrypted, and trusted. h](hterm)}(hFALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t.h]hFALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t.}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1jp hhhMhjl ubh definition)}(hhh](h)}(hThis operation behaves the same as ALG_SET_KEY. The decrypted data is copied from a keyring key, and uses that data as the key for symmetric encryption.h]hThis operation behaves the same as ALG_SET_KEY. The decrypted data is copied from a keyring key, and uses that data as the key for symmetric encryption.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubh)}(hThe passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH permission set, otherwise -EPERM is returned. Supports key types: user, logon, encrypted, and trusted.h]hThe passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH permission set, otherwise -EPERM is returned. Supports key types: user, logon, encrypted, and trusted.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubeh}(h]h ]h"]h$]h&]uh1j hjl ubeh}(h]h ]h"]h$]h&]uh1jj hhhMhjg ubah}(h]h ]h"]h$]h&]uh1je hja ubah}(h]h ]h"]h$]h&]uh1j#hj hhhNhNubj$)}(hXGALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for AEAD ciphers. For a encryption operation, the authentication tag of the given size will be generated. For a decryption operation, the provided ciphertext is assumed to contain an authentication tag of the given size (see section about AEAD memory layout below). h]h)}(hXFALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for AEAD ciphers. For a encryption operation, the authentication tag of the given size will be generated. For a decryption operation, the provided ciphertext is assumed to contain an authentication tag of the given size (see section about AEAD memory layout below).h]hXFALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for AEAD ciphers. For a encryption operation, the authentication tag of the given size will be generated. For a decryption operation, the provided ciphertext is assumed to contain an authentication tag of the given size (see section about AEAD memory layout below).}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubj$)}(hALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. This option is applicable to RNG cipher type only. h]h)}(h~ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. This option is applicable to RNG cipher type only.h]h~ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. This option is applicable to RNG cipher type only.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj ubah}(h]h ]h"]h$]h&]uh1j#hj hhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jhhhMhj hhubeh}(h]setsockopt-interfaceah ]h"]setsockopt interfaceah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hUser space API exampleh]hUser space API example}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhMubh)}(hPlease see [1] for libkcapi which provides an easy-to-use wrapper around the aforementioned Netlink kernel interface. [1] also contains a test application that invokes all libkcapi API calls.h]hPlease see [1] for libkcapi which provides an easy-to-use wrapper around the aforementioned Netlink kernel interface. [1] also contains a test application that invokes all libkcapi API calls.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj hhubh)}(h.[1] https://www.chronox.de/libkcapi/index.htmlh](h[1] }(hj hhhNhNubjH)}(h*https://www.chronox.de/libkcapi/index.htmlh]h*https://www.chronox.de/libkcapi/index.html}(hj hhhNhNubah}(h]h ]h"]h$]h&]refurij uh1jGhj ubeh}(h]h ]h"]h$]h&]uh1hhhhMhj hhubeh}(h]user-space-api-exampleah ]h"]user space api exampleah$]h&]uh1hhhhhhhhMubeh}(h](user-space-interfaceheh ]h"](user space interfacecrypto_userspace_interfaceeh$]h&]uh1hhhhhhhhKexpect_referenced_by_name}jA hsexpect_referenced_by_id}hhsubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjk error_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehÌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}h]hasnameids}(jA hj@ j= jjj jjKjHjj}jj j*j'j j j j jx ju j j j j j8 j5 u nametypes}(jA j@ jj jKjjj*j j jx j j j8 uh}(hhj= hjhjjjHjj}jNj jj'jj j-j juju j j j{ j j j5 j u footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages]hsystem_message)}(hhh]h)}(hhh]h@Hyperlink target "crypto-userspace-interface" is not referenced.}hj sbah}(h]h ]h"]h$]h&]uh1hhj ubah}(h]h ]h"]h$]h&]levelKtypeINFOsourcehÌlineKuh1j uba transformerN include_log] decorationNhhub.