€•ûÔ      Œsphinx.addnodes”Œdocument”“”)”}”(Œ	rawsource”Œ ”Œchildren”]”(Œtranslations”ŒLanguagesNode”“”)”}”(hhh]”(h Œpending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ
attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ	refdomain”Œstd”Œreftype”Œdoc”Œ	reftarget”Œ'/translations/zh_CN/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuŒtagname”hhhubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/zh_TW/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/it_IT/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ja_JP/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/ko_KR/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ	refdomain”h)Œreftype”h+Œ	reftarget”Œ'/translations/sp_SP/crypto/userspace-if”Œmodname”NŒ	classname”NŒrefexplicit”ˆuh1hhhubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h
hhŒ	_document”hŒsource”NŒline”NubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒUser Space Interface”h]”hŒUser Space Interface”…””}”(hh¨hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh£hžhhŸŒA/var/lib/git/docbuild/linux/Documentation/crypto/userspace-if.rst”h Kubh¢)”}”(hhh]”(h§)”}”(hŒIntroduction”h]”hŒIntroduction”…””}”(hhºhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hh·hžhhŸh¶h KubhŒ	paragraph”“”)”}”(hŒßThe concepts of the kernel crypto API visible to kernel space is fully
applicable to the user space interface as well. Therefore, the kernel
crypto API high level discussion for the in-kernel use cases applies
here as well.”h]”hŒßThe concepts of the kernel crypto API visible to kernel space is fully
applicable to the user space interface as well. Therefore, the kernel
crypto API high level discussion for the in-kernel use cases applies
here as well.”…””}”(hhÊhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hŒThe major difference, however, is that user space can only act as a
consumer and never as a provider of a transformation or cipher
algorithm.”h]”hŒThe major difference, however, is that user space can only act as a
consumer and never as a provider of a transformation or cipher
algorithm.”…””}”(hhØhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hX
  The following covers the user space interface exported by the kernel
crypto API. A working example of this description is libkcapi that can
be obtained from [1]. That library can be used by user space
applications that require cryptographic services from the kernel.”h]”hX
  The following covers the user space interface exported by the kernel
crypto API. A working example of this description is libkcapi that can
be obtained from [1]. That library can be used by user space
applications that require cryptographic services from the kernel.”…””}”(hhæhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hŒÙSome details of the in-kernel kernel crypto API aspects do not apply to
user space, however. This includes the difference between synchronous
and asynchronous invocations. The user space API call is fully
synchronous.”h]”hŒÙSome details of the in-kernel kernel crypto API aspects do not apply to
user space, however. This includes the difference between synchronous
and asynchronous invocations. The user space API call is fully
synchronous.”…””}”(hhôhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubhÉ)”}”(hŒ([1] https://www.chronox.de/libkcapi.html”h]”(hŒ[1] ”…””}”(hj  hžhhŸNh NubhŒ	reference”“”)”}”(hŒ$https://www.chronox.de/libkcapi.html”h]”hŒ$https://www.chronox.de/libkcapi.html”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j  uh1j
  hj  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khh·hžhubeh}”(h]”Œintroduction”ah ]”h"]”Œintroduction”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒUser Space API General Remarks”h]”hŒUser Space API General Remarks”…””}”(hj,  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj)  hžhhŸh¶h KubhÉ)”}”(hŒeThe kernel crypto API is accessible from user space. Currently, the
following ciphers are accessible:”h]”hŒeThe kernel crypto API is accessible from user space. Currently, the
following ciphers are accessible:”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj)  hžhubhŒbullet_list”“”)”}”(hhh]”(hŒ	list_item”“”)”}”(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)”…””}”(hjS  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K"hjO  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjJ  hžhhŸh¶h NubjN  )”}”(hŒSymmetric ciphers
”h]”hÉ)”}”(hŒSymmetric ciphers”h]”hŒSymmetric ciphers”…””}”(hjk  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K$hjg  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjJ  hžhhŸh¶h NubjN  )”}”(hŒAEAD ciphers
”h]”hÉ)”}”(hŒAEAD ciphers”h]”hŒAEAD ciphers”…””}”(hjƒ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K&hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjJ  hžhhŸh¶h NubjN  )”}”(hŒRandom Number Generators
”h]”hÉ)”}”(hŒRandom Number Generators”h]”hŒRandom Number Generators”…””}”(hj›  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K(hj—  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjJ  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ-”uh1jH  hŸh¶h K"hj)  hžhubhÉ)”}”(hŒÑThe 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]”hŒÑThe 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j·  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K*hj)  hžhubhŒliteral_block”“”)”}”(hŒR#ifndef AF_ALG
#define AF_ALG 38
#endif
#ifndef SOL_ALG
#define SOL_ALG 279
#endif”h]”hŒR#ifndef AF_ALG
#define AF_ALG 38
#endif
#ifndef SOL_ALG
#define SOL_ALG 279
#endif”…””}”hjÇ  sbah}”(h]”h ]”h"]”h$]”h&]”Œ	xml:space”Œpreserve”uh1jÅ  hŸh¶h K0hj)  hžhubhÉ)”}”(hŒÇA 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]”hŒÇA 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j×  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K8hj)  hžhubhÉ)”}”(hX  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]”hX  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jå  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K<hj)  hžhubhÉ)”}”(hŒ¨The 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]”hŒ¨The 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jó  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KAhj)  hžhubhÉ)”}”(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:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KEhj)  hžhubhŒenumerated_list”“”)”}”(hhh]”(jN  )”}”(hŒvCreate a socket of type AF_ALG with the struct sockaddr_alg
parameter specified below for the different cipher types.
”h]”hÉ)”}”(hŒuCreate a socket of type AF_ALG with the struct sockaddr_alg
parameter specified below for the different cipher types.”h]”hŒuCreate a socket of type AF_ALG with the struct sockaddr_alg
parameter specified below for the different cipher types.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KHhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj  hžhhŸh¶h NubjN  )”}”(hŒ'Invoke bind with the socket descriptor
”h]”hÉ)”}”(hŒ&Invoke bind with the socket descriptor”h]”hŒ&Invoke bind with the socket descriptor”…””}”(hj0  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KKhj,  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj  hžhhŸh¶h NubjN  )”}”(hXF  Invoke 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É)”}”(hXE  Invoke 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XE  Invoke 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jH  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KMhjD  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”Œenumtype”Œarabic”Œprefix”hŒsuffix”Œ.”uh1j  hj)  hžhhŸh¶h KHubeh}”(h]”Œuser-space-api-general-remarks”ah ]”h"]”Œuser space api general remarks”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kubh¢)”}”(hhh]”(h§)”}”(hŒIn-place Cipher operation”h]”hŒIn-place Cipher operation”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjo  hžhhŸh¶h KTubhÉ)”}”(hX›  Just 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]”hX›  Just 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j€  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KVhjo  hžhubhÉ)”}”(hŒáIf 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]”hŒáIf 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jŽ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K]hjo  hžhubeh}”(h]”Œin-place-cipher-operation”ah ]”h"]”Œin-place cipher operation”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KTubh¢)”}”(hhh]”(h§)”}”(hŒMessage Digest API”h]”hŒMessage Digest API”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj¤  hžhhŸh¶h KcubhÉ)”}”(hŒãThe 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]”hŒãThe 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jµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kehj¤  hžhubjÆ  )”}”(hŒ·struct 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]”hŒ·struct 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jÃ  sbah}”(h]”h ]”h"]”h$]”h&]”jÕ  jÖ  uh1jÅ  hŸh¶h Klhj¤  hžhubhÉ)”}”(hX
  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]”hX  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jÑ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kshj¤  hžhubhÉ)”}”(hŒ²Using 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]”hŒ²Using 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jß  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kxhj¤  hžhubjI  )”}”(hhh]”jN  )”}”(hŒéMSG_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É)”}”(hŒèMSG_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ŒèMSG_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jô  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K|hjð  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjí  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h K|hj¤  hžhubhÉ)”}”(hŒÀWith 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]”hŒÀWith 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj¤  hžhubhÉ)”}”(hŒúIn 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]”hŒúIn 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K…hj¤  hžhubeh}”(h]”Œmessage-digest-api”ah ]”h"]”Œmessage digest api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Kcubh¢)”}”(hhh]”(h§)”}”(hŒSymmetric Cipher API”h]”hŒSymmetric Cipher API”…””}”(hj5  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj2  hžhhŸh¶h K‹ubhÉ)”}”(hŒ”The operation is very similar to the message digest discussion. During
initialization, the struct sockaddr data structure must be filled as
follows:”h]”hŒ”The operation is very similar to the message digest discussion. During
initialization, the struct sockaddr data structure must be filled as
follows:”…””}”(hjC  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Khj2  hžhubjÆ  )”}”(hŒ·struct 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]”hŒ·struct 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jQ  sbah}”(h]”h ]”h"]”h$]”h&]”jÕ  jÖ  uh1jÅ  hŸh¶h K“hj2  hžhubhÉ)”}”(hŒ°Before 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]”hŒ°Before 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j_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kšhj2  hžhubhÉ)”}”(hŒÙUsing 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]”hŒÙUsing 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jm  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kžhj2  hžhubhÉ)”}”(hXU  The 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]”hXU  The 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j{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¢hj2  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒ”specification of the cipher operation type with one of these flags:

-  ALG_OP_ENCRYPT - encryption of data

-  ALG_OP_DECRYPT - decryption of data
”h]”(hÉ)”}”(hŒCspecification of the cipher operation type with one of these flags:”h]”hŒCspecification of the cipher operation type with one of these flags:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¨hjŒ  ubjI  )”}”(hhh]”(jN  )”}”(hŒ$ALG_OP_ENCRYPT - encryption of data
”h]”hÉ)”}”(hŒ#ALG_OP_ENCRYPT - encryption of data”h]”hŒ#ALG_OP_ENCRYPT - encryption of data”…””}”(hj¥  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kªhj¡  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjž  ubjN  )”}”(hŒ$ALG_OP_DECRYPT - decryption of data
”h]”hÉ)”}”(hŒ#ALG_OP_DECRYPT - decryption of data”h]”hŒ#ALG_OP_DECRYPT - decryption of data”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¬hj¹  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjž  ubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h KªhjŒ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj‰  hžhhŸNh NubjN  )”}”(hŒDspecification of the IV information marked with the flag ALG_SET_IV
”h]”hÉ)”}”(hŒCspecification of the IV information marked with the flag ALG_SET_IV”h]”hŒCspecification of the IV information marked with the flag ALG_SET_IV”…””}”(hjá  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K®hjÝ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj‰  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h K¨hj2  hžhubhÉ)”}”(hŒFThe send system call family allows the following flag to be specified:”h]”hŒFThe send system call family allows the following flag to be specified:”…””}”(hjû  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K°hj2  hžhubjI  )”}”(hhh]”jN  )”}”(hŒ¯MSG_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É)”}”(hŒ®MSG_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Œ®MSG_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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K²hj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj	  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h K²hj2  hžhubhÉ)”}”(hŒ¨Note: 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]”hŒ¨Note: 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j*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h K¶hj2  hžhubhÉ)”}”(hXF  With 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]”hXF  With 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j8  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kºhj2  hžhubeh}”(h]”Œsymmetric-cipher-api”ah ]”h"]”Œsymmetric cipher api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h K‹ubh¢)”}”(hhh]”(h§)”}”(hŒAEAD Cipher API”h]”hŒAEAD Cipher API”…””}”(hjQ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjN  hžhhŸh¶h KÁubhÉ)”}”(hŒ–The operation is very similar to the symmetric cipher discussion. During
initialization, the struct sockaddr data structure must be filled as
follows:”h]”hŒ–The operation is very similar to the symmetric cipher discussion. During
initialization, the struct sockaddr data structure must be filled as
follows:”…””}”(hj_  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÃhjN  hžhubjÆ  )”}”(hŒ³struct 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]”hŒ³struct 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jm  sbah}”(h]”h ]”h"]”h$]”h&]”jÕ  jÖ  uh1jÅ  hŸh¶h KÉhjN  hžhubhÉ)”}”(hŒ°Before 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]”hŒ°Before 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j{  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÐhjN  hžhubhÉ)”}”(hŒñIn 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]”hŒñIn 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j‰  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÔhjN  hžhubhÉ)”}”(hŒÙUsing 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]”hŒÙUsing 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j—  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÙhjN  hžhubhÉ)”}”(hXU  The 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]”hXU  The 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j¥  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KÝhjN  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒ”specification of the cipher operation type with one of these flags:

-  ALG_OP_ENCRYPT - encryption of data

-  ALG_OP_DECRYPT - decryption of data
”h]”(hÉ)”}”(hŒCspecification of the cipher operation type with one of these flags:”h]”hŒCspecification of the cipher operation type with one of these flags:”…””}”(hjº  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kãhj¶  ubjI  )”}”(hhh]”(jN  )”}”(hŒ$ALG_OP_ENCRYPT - encryption of data
”h]”hÉ)”}”(hŒ#ALG_OP_ENCRYPT - encryption of data”h]”hŒ#ALG_OP_ENCRYPT - encryption of data”…””}”(hjÏ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KåhjË  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjÈ  ubjN  )”}”(hŒ$ALG_OP_DECRYPT - decryption of data
”h]”hÉ)”}”(hŒ#ALG_OP_DECRYPT - decryption of data”h]”hŒ#ALG_OP_DECRYPT - decryption of data”…””}”(hjç  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kçhjã  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjÈ  ubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Kåhj¶  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj³  hžhhŸNh NubjN  )”}”(hŒDspecification of the IV information marked with the flag ALG_SET_IV
”h]”hÉ)”}”(hŒCspecification of the IV information marked with the flag ALG_SET_IV”h]”hŒCspecification of the IV information marked with the flag ALG_SET_IV”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Kéhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj³  hžhhŸh¶h NubjN  )”}”(hŒËspecification 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É)”}”(hŒÊspecification 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ŒÊspecification 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j#  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Këhj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj³  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h KãhjN  hžhubhÉ)”}”(hŒFThe send system call family allows the following flag to be specified:”h]”hŒFThe send system call family allows the following flag to be specified:”…””}”(hj=  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KïhjN  hžhubjI  )”}”(hhh]”jN  )”}”(hŒ¯MSG_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É)”}”(hŒ®MSG_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Œ®MSG_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jR  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KñhjN  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjK  hžhhŸh¶h Nubah}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h KñhjN  hžhubhÉ)”}”(hŒ¨Note: 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]”hŒ¨Note: 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jl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KõhjN  hžhubhÉ)”}”(hX  With 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]”hX  With 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jz  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KùhjN  hžhubhÉ)”}”(hŒˆThe authenticated decryption operation may indicate an integrity error.
Such breach in integrity is marked with the -EBADMSG error code.”h]”hŒˆThe authenticated decryption operation may indicate an integrity error.
Such breach in integrity is marked with the -EBADMSG error code.”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h KþhjN  hžhubh¢)”}”(hhh]”(h§)”}”(hŒAEAD Memory Structure”h]”hŒAEAD Memory Structure”…””}”(hj™  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj–  hžhhŸh¶h MubhÉ)”}”(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:”…””}”(hj§  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj–  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒplaintext or ciphertext
”h]”hÉ)”}”(hŒplaintext or ciphertext”h]”hŒplaintext or ciphertext”…””}”(hj¼  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj¸  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjµ  hžhhŸh¶h NubjN  )”}”(hŒ%associated authentication data (AAD)
”h]”hÉ)”}”(hŒ$associated authentication data (AAD)”h]”hŒ$associated authentication data (AAD)”…””}”(hjÔ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M	hjÐ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjµ  hžhhŸh¶h NubjN  )”}”(hŒauthentication tag
”h]”hÉ)”}”(hŒauthentication tag”h]”hŒauthentication tag”…””}”(hjì  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjè  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjµ  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Mhj–  hžhubhÉ)”}”(hX  The 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]”hX  The 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj–  hžhubhÉ)”}”(hŒYThe user space caller must arrange the aforementioned information in the
following order:”h]”hŒYThe user space caller must arrange the aforementioned information in the
following order:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj–  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒ*AEAD encryption input: AAD \|\| plaintext
”h]”hÉ)”}”(hŒ)AEAD encryption input: AAD \|\| plaintext”h]”hŒ)AEAD encryption input: AAD  | | plaintext”…””}”(hj)  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj%  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj"  hžhhŸh¶h NubjN  )”}”(hŒCAEAD decryption input: AAD \|\| ciphertext \|\| authentication tag
”h]”hÉ)”}”(hŒBAEAD decryption input: AAD \|\| ciphertext \|\| authentication tag”h]”hŒBAEAD decryption input: AAD  | | ciphertext  | | authentication tag”…””}”(hjA  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj=  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj"  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Mhj–  hžhubhÉ)”}”(hŒfThe output buffer the user space caller provides must be at least as
large to hold the following data:”h]”hŒfThe output buffer the user space caller provides must be at least as
large to hold the following data:”…””}”(hj[  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj–  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒ;AEAD encryption output: ciphertext \|\| authentication tag
”h]”hÉ)”}”(hŒ:AEAD encryption output: ciphertext \|\| authentication tag”h]”hŒ:AEAD encryption output: ciphertext  | | authentication tag”…””}”(hjp  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhjl  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hji  hžhhŸh¶h NubjN  )”}”(hŒ"AEAD decryption output: plaintext
”h]”hÉ)”}”(hŒ!AEAD decryption output: plaintext”h]”hŒ!AEAD decryption output: plaintext”…””}”(hjˆ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj„  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hji  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Mhj–  hžhubeh}”(h]”Œaead-memory-structure”ah ]”h"]”Œaead memory structure”ah$]”h&]”uh1h¡hjN  hžhhŸh¶h Mubeh}”(h]”Œaead-cipher-api”ah ]”h"]”Œaead cipher api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h KÁubh¢)”}”(hhh]”(h§)”}”(hŒRandom Number Generator API”h]”hŒRandom Number Generator API”…””}”(hjµ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hj²  hžhhŸh¶h M!ubhÉ)”}”(hŒŒAgain, the operation is very similar to the other APIs. During
initialization, the struct sockaddr data structure must be filled as
follows:”h]”hŒŒAgain, the operation is very similar to the other APIs. During
initialization, the struct sockaddr data structure must be filled as
follows:”…””}”(hjÃ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M#hj²  hžhubjÆ  )”}”(hŒ¾struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "rng", /* this selects the random number generator */
    .salg_name = "drbg_nopr_sha256" /* this is the RNG name */
};”h]”hŒ¾struct sockaddr_alg sa = {
    .salg_family = AF_ALG,
    .salg_type = "rng", /* this selects the random number generator */
    .salg_name = "drbg_nopr_sha256" /* this is the RNG name */
};”…””}”hjÑ  sbah}”(h]”h ]”h"]”h$]”h&]”jÕ  jÖ  uh1jÅ  hŸh¶h M)hj²  hžhubhÉ)”}”(hX)  Depending on the RNG type, the RNG must be seeded. The seed is provided
using the setsockopt interface to set the key. For example, the
ansi_cprng requires a seed. The 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]”(hŒôDepending on the RNG type, the RNG must be seeded. The seed is provided
using the setsockopt interface to set the key. For example, the
ansi_cprng requires a seed. The DRBGs do not require a seed, but may be
seeded. The seed is also known as a ”…””}”(hjß  hžhhŸNh NubhŒemphasis”“”)”}”(hŒ*Personalization String*”h]”hŒPersonalization String”…””}”(hjé  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jç  hjß  ubhŒ in NIST SP 800-90A
standard.”…””}”(hjß  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M0hj²  hžhubhÉ)”}”(hŒÏUsing 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]”hŒÏUsing 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M6hj²  hžhubhÉ)”}”(hŒ¥WARNING: 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]”hŒ¥WARNING: 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M:hj²  hžhubhÉ)”}”(hŒhFollowing CAVP testing interfaces are enabled when kernel is built with
CRYPTO_USER_API_RNG_CAVP option:”h]”hŒhFollowing CAVP testing interfaces are enabled when kernel is built with
CRYPTO_USER_API_RNG_CAVP option:”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M>hj²  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒ¬the 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É)”}”(hŒ«the 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Œthe concatenation of ”…””}”(hj2  hžhhŸNh Nubjè  )”}”(hŒ	*Entropy*”h]”hŒEntropy”…””}”(hj:  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jç  hj2  ubhŒ and ”…””}”(hj2  hžhhŸNh Nubjè  )”}”(hŒ*Nonce*”h]”hŒNonce”…””}”(hjL  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jç  hj2  ubhŒ can be provided to the RNG via
ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires
CAP_SYS_ADMIN permission.”…””}”(hj2  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MAhj.  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj+  hžhhŸh¶h NubjN  )”}”(hŒt*Additional Data* can be provided using the send()/sendmsg() system calls,
but only after the entropy has been set.
”h]”hÉ)”}”(hŒs*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]”hŒAdditional Data”…””}”(hjr  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jç  hjn  ubhŒb can be provided using the send()/sendmsg() system calls,
but only after the entropy has been set.”…””}”(hjn  hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MEhjj  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj+  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h MAhj²  hžhubeh}”(h]”Œrandom-number-generator-api”ah ]”h"]”Œrandom number generator api”ah$]”h&]”uh1h¡hh£hžhhŸh¶h M!ubh¢)”}”(hhh]”(h§)”}”(hŒZero-Copy Interface”h]”hŒZero-Copy Interface”…””}”(hj¡  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjž  hžhhŸh¶h MIubhÉ)”}”(hŒæIn addition to the send/write/read/recv system call family, the AF_ALG
interface can be accessed with the zero-copy interface of
splice/vmsplice. As the name indicates, the kernel tries to avoid a copy
operation into kernel space.”h]”hŒæIn addition to the send/write/read/recv system call family, the AF_ALG
interface can be accessed with the zero-copy interface of
splice/vmsplice. As the name indicates, the kernel tries to avoid a copy
operation into kernel space.”…””}”(hj¯  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MKhjž  hžhubhÉ)”}”(hŒçThe zero-copy operation requires data to be aligned at the page
boundary. Non-aligned data can be used as well, but may require more
operations of the kernel which would defeat the speed gains obtained
from the zero-copy interface.”h]”hŒçThe zero-copy operation requires data to be aligned at the page
boundary. Non-aligned data can be used as well, but may require more
operations of the kernel which would defeat the speed gains obtained
from the zero-copy interface.”…””}”(hj½  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MPhjž  hžhubhÉ)”}”(hŒÃThe system-inherent limit for the size of one zero-copy operation is 16
pages. If more data is to be sent to AF_ALG, user space must slice the
input into segments with a maximum size of 16 pages.”h]”hŒÃThe system-inherent limit for the size of one zero-copy operation is 16
pages. If more data is to be sent to AF_ALG, user space must slice the
input into segments with a maximum size of 16 pages.”…””}”(hjË  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MUhjž  hžhubhÉ)”}”(hŒmZero-copy can be used with the following code example (a complete
working example is provided with libkcapi):”h]”hŒmZero-copy can be used with the following code example (a complete
working example is provided with libkcapi):”…””}”(hjÙ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MYhjž  hžhubjÆ  )”}”(hŒíint pipes[2];

pipe(pipes);
/* input data in iov */
vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
/* opfd is the file descriptor returned from accept() system call */
splice(pipes[0], NULL, opfd, NULL, ret, 0);
read(opfd, out, outlen);”h]”hŒíint pipes[2];

pipe(pipes);
/* input data in iov */
vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
/* opfd is the file descriptor returned from accept() system call */
splice(pipes[0], NULL, opfd, NULL, ret, 0);
read(opfd, out, outlen);”…””}”hjç  sbah}”(h]”h ]”h"]”h$]”h&]”jÕ  jÖ  uh1jÅ  hŸh¶h M^hjž  hžhubeh}”(h]”Œzero-copy-interface”ah ]”h"]”Œzero-copy interface”ah$]”h&]”uh1h¡hh£hžhhŸh¶h MIubh¢)”}”(hhh]”(h§)”}”(hŒSetsockopt Interface”h]”hŒSetsockopt Interface”…””}”(hj   hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjý  hžhhŸh¶h MiubhÉ)”}”(hX‘  In 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]”hX‘  In 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j  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mkhjý  hžhubhÉ)”}”(hŒ6Each setsockopt invocation must use the level SOL_ALG.”h]”hŒ6Each setsockopt invocation must use the level SOL_ALG.”…””}”(hj  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mrhjý  hžhubhÉ)”}”(hŒWThe setsockopt interface allows setting the following data using the
mentioned optname:”h]”hŒWThe setsockopt interface allows setting the following data using the
mentioned optname:”…””}”(hj*  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mthjý  hžhubjI  )”}”(hhh]”(jN  )”}”(hŒåALG_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:”…””}”(hj?  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mwhj;  ubjI  )”}”(hhh]”(jN  )”}”(hŒ-the skcipher cipher type (symmetric ciphers)
”h]”hÉ)”}”(hŒ,the skcipher cipher type (symmetric ciphers)”h]”hŒ,the skcipher cipher type (symmetric ciphers)”…””}”(hjT  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MyhjP  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjM  ubjN  )”}”(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)”…””}”(hjl  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M{hjh  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjM  ubjN  )”}”(hŒthe AEAD cipher type
”h]”hÉ)”}”(hŒthe AEAD cipher type”h]”hŒthe AEAD cipher type”…””}”(hj„  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M}hj€  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjM  ubjN  )”}”(hŒ(the RNG cipher type to provide the seed
”h]”hÉ)”}”(hŒ'the RNG cipher type to provide the seed”h]”hŒ'the RNG cipher type to provide the seed”…””}”(hjœ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj˜  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hjM  ubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Myhj;  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj8  hžhhŸNh NubjN  )”}”(hX”  ALG_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]”hŒdefinition_list”“”)”}”(hhh]”hŒdefinition_list_item”“”)”}”(hXŽ  ALG_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]”(hŒterm”“”)”}”(hŒFALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t.”h]”hŒFALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t.”…””}”(hjÍ  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1jË  hŸh¶h MˆhjÇ  ubhŒ
definition”“”)”}”(hhh]”(hÉ)”}”(hŒ˜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.”h]”hŒ˜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.”…””}”(hjà  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M‚hjÝ  ubhÉ)”}”(hŒ¬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]”hŒ¬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jî  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M†hjÝ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÛ  hjÇ  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1jÅ  hŸh¶h MˆhjÂ  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jÀ  hj¼  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj8  hžhhŸNh NubjN  )”}”(hXG  ALG_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É)”}”(hXF  ALG_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XF  ALG_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j	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MŠhj	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj8  hžhhŸh¶h NubjN  )”}”(hŒALG_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.”…””}”(hj0	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h Mhj,	  ubah}”(h]”h ]”h"]”h$]”h&]”uh1jM  hj8  hžhhŸh¶h Nubeh}”(h]”h ]”h"]”h$]”h&]”jµ  j¶  uh1jH  hŸh¶h Mwhjý  hžhubeh}”(h]”Œsetsockopt-interface”ah ]”h"]”Œsetsockopt interface”ah$]”h&]”uh1h¡hh£hžhhŸh¶h Miubh¢)”}”(hhh]”(h§)”}”(hŒUser space API example”h]”hŒUser space API example”…””}”(hjU	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¦hjR	  hžhhŸh¶h M”ubhÉ)”}”(hŒ¿Please 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]”hŒ¿Please 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jc	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h M–hjR	  hžhubhÉ)”}”(hŒ([1] https://www.chronox.de/libkcapi.html”h]”(hŒ[1] ”…””}”(hjq	  hžhhŸNh Nubj  )”}”(hŒ$https://www.chronox.de/libkcapi.html”h]”hŒ$https://www.chronox.de/libkcapi.html”…””}”(hjy	  hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j{	  uh1j
  hjq	  ubeh}”(h]”h ]”h"]”h$]”h&]”uh1hÈhŸh¶h MšhjR	  hžhubeh}”(h]”Œuser-space-api-example”ah ]”h"]”Œuser space api example”ah$]”h&]”uh1h¡hh£hžhhŸh¶h M”ubeh}”(h]”Œuser-space-interface”ah ]”h"]”Œuser space interface”ah$]”h&]”uh1h¡hhhžhhŸh¶h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h¶uh1hŒcurrent_source”NŒcurrent_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¦NŒ	generator”NŒ	datestamp”NŒsource_link”NŒ
source_url”NŒtoc_backlinks”Œentry”Œfootnote_backlinks”KŒsectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒstrip_classes”NŒreport_level”KŒ
halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ	traceback”ˆŒinput_encoding”Œ	utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jÁ	  Œerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œlanguage_code”Œen”Œrecord_dependencies”NŒconfig”NŒ	id_prefix”hŒauto_id_prefix”Œid”Œdump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h¶Œ_destination”NŒ_config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒraw_enabled”KŒline_length_limit”M'Œpep_references”NŒpep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒrfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ	tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œsmart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œdocinfo_xform”KŒsectsubtitle_xform”‰Œimage_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(j›	  j˜	  j&  j#  jl  ji  j¡  jž  j/  j,  jK  jH  j¯  j¬  j§  j¤  j›  j˜  jú  j÷  jO	  jL	  j“	  j	  uŒ	nametypes”}”(j›	  ‰j&  ‰jl  ‰j¡  ‰j/  ‰jK  ‰j¯  ‰j§  ‰j›  ‰jú  ‰jO	  ‰j“	  ‰uh}”(j˜	  h£j#  h·ji  j)  jž  jo  j,  j¤  jH  j2  j¬  jN  j¤  j–  j˜  j²  j÷  jž  jL	  jý  j	  jR	  uŒfootnote_refs”}”Œcitation_refs”}”Œautofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ	footnotes”]”Œ	citations”]”Œautofootnote_start”KŒsymbol_footnote_start”K Œ
id_counter”Œcollections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œtransformer”NŒinclude_log”]”Œ
decoration”Nhžhub.