13b72c814SStephan MuellerUser Space Interface 23b72c814SStephan Mueller==================== 33b72c814SStephan Mueller 43b72c814SStephan MuellerIntroduction 53b72c814SStephan Mueller------------ 63b72c814SStephan Mueller 73b72c814SStephan MuellerThe concepts of the kernel crypto API visible to kernel space is fully 83b72c814SStephan Muellerapplicable to the user space interface as well. Therefore, the kernel 93b72c814SStephan Muellercrypto API high level discussion for the in-kernel use cases applies 103b72c814SStephan Muellerhere as well. 113b72c814SStephan Mueller 123b72c814SStephan MuellerThe major difference, however, is that user space can only act as a 133b72c814SStephan Muellerconsumer and never as a provider of a transformation or cipher 143b72c814SStephan Muelleralgorithm. 153b72c814SStephan Mueller 163b72c814SStephan MuellerThe following covers the user space interface exported by the kernel 173b72c814SStephan Muellercrypto API. A working example of this description is libkcapi that can 183b72c814SStephan Muellerbe obtained from [1]. That library can be used by user space 193b72c814SStephan Muellerapplications that require cryptographic services from the kernel. 203b72c814SStephan Mueller 213b72c814SStephan MuellerSome details of the in-kernel kernel crypto API aspects do not apply to 223b72c814SStephan Muelleruser space, however. This includes the difference between synchronous 233b72c814SStephan Muellerand asynchronous invocations. The user space API call is fully 243b72c814SStephan Muellersynchronous. 253b72c814SStephan Mueller 269332a9e7SAlexander A. Klimov[1] https://www.chronox.de/libkcapi.html 273b72c814SStephan Mueller 283b72c814SStephan MuellerUser Space API General Remarks 293b72c814SStephan Mueller------------------------------ 303b72c814SStephan Mueller 313b72c814SStephan MuellerThe kernel crypto API is accessible from user space. Currently, the 323b72c814SStephan Muellerfollowing ciphers are accessible: 333b72c814SStephan Mueller 343b72c814SStephan Mueller- Message digest including keyed message digest (HMAC, CMAC) 353b72c814SStephan Mueller 363b72c814SStephan Mueller- Symmetric ciphers 373b72c814SStephan Mueller 383b72c814SStephan Mueller- AEAD ciphers 393b72c814SStephan Mueller 403b72c814SStephan Mueller- Random Number Generators 413b72c814SStephan Mueller 423b72c814SStephan MuellerThe interface is provided via socket type using the type AF_ALG. In 433b72c814SStephan Muelleraddition, the setsockopt option type is SOL_ALG. In case the user space 443b72c814SStephan Muellerheader files do not export these flags yet, use the following macros: 453b72c814SStephan Mueller 463b72c814SStephan Mueller:: 473b72c814SStephan Mueller 483b72c814SStephan Mueller #ifndef AF_ALG 493b72c814SStephan Mueller #define AF_ALG 38 503b72c814SStephan Mueller #endif 513b72c814SStephan Mueller #ifndef SOL_ALG 523b72c814SStephan Mueller #define SOL_ALG 279 533b72c814SStephan Mueller #endif 543b72c814SStephan Mueller 553b72c814SStephan Mueller 563b72c814SStephan MuellerA cipher is accessed with the same name as done for the in-kernel API 573b72c814SStephan Muellercalls. This includes the generic vs. unique naming schema for ciphers as 583b72c814SStephan Muellerwell as the enforcement of priorities for generic names. 593b72c814SStephan Mueller 603b72c814SStephan MuellerTo interact with the kernel crypto API, a socket must be created by the 613b72c814SStephan Muelleruser space application. User space invokes the cipher operation with the 623b72c814SStephan Muellersend()/write() system call family. The result of the cipher operation is 633b72c814SStephan Muellerobtained with the read()/recv() system call family. 643b72c814SStephan Mueller 653b72c814SStephan MuellerThe following API calls assume that the socket descriptor is already 663b72c814SStephan Muelleropened by the user space application and discusses only the kernel 673b72c814SStephan Muellercrypto API specific invocations. 683b72c814SStephan Mueller 693b72c814SStephan MuellerTo initialize the socket interface, the following sequence has to be 703b72c814SStephan Muellerperformed by the consumer: 713b72c814SStephan Mueller 723b72c814SStephan Mueller1. Create a socket of type AF_ALG with the struct sockaddr_alg 733b72c814SStephan Mueller parameter specified below for the different cipher types. 743b72c814SStephan Mueller 753b72c814SStephan Mueller2. Invoke bind with the socket descriptor 763b72c814SStephan Mueller 773b72c814SStephan Mueller3. Invoke accept with the socket descriptor. The accept system call 783b72c814SStephan Mueller returns a new file descriptor that is to be used to interact with the 793b72c814SStephan Mueller particular cipher instance. When invoking send/write or recv/read 803b72c814SStephan Mueller system calls to send data to the kernel or obtain data from the 813b72c814SStephan Mueller kernel, the file descriptor returned by accept must be used. 823b72c814SStephan Mueller 833b72c814SStephan MuellerIn-place Cipher operation 843b72c814SStephan Mueller------------------------- 853b72c814SStephan Mueller 863b72c814SStephan MuellerJust like the in-kernel operation of the kernel crypto API, the user 873b72c814SStephan Muellerspace interface allows the cipher operation in-place. That means that 883b72c814SStephan Muellerthe input buffer used for the send/write system call and the output 893b72c814SStephan Muellerbuffer used by the read/recv system call may be one and the same. This 903b72c814SStephan Muelleris of particular interest for symmetric cipher operations where a 913b72c814SStephan Muellercopying of the output data to its final destination can be avoided. 923b72c814SStephan Mueller 933b72c814SStephan MuellerIf a consumer on the other hand wants to maintain the plaintext and the 943b72c814SStephan Muellerciphertext in different memory locations, all a consumer needs to do is 953b72c814SStephan Muellerto provide different memory pointers for the encryption and decryption 963b72c814SStephan Muelleroperation. 973b72c814SStephan Mueller 983b72c814SStephan MuellerMessage Digest API 993b72c814SStephan Mueller------------------ 1003b72c814SStephan Mueller 1013b72c814SStephan MuellerThe message digest type to be used for the cipher operation is selected 1023b72c814SStephan Muellerwhen invoking the bind syscall. bind requires the caller to provide a 1033b72c814SStephan Muellerfilled struct sockaddr data structure. This data structure must be 1043b72c814SStephan Muellerfilled as follows: 1053b72c814SStephan Mueller 1063b72c814SStephan Mueller:: 1073b72c814SStephan Mueller 1083b72c814SStephan Mueller struct sockaddr_alg sa = { 1093b72c814SStephan Mueller .salg_family = AF_ALG, 1103b72c814SStephan Mueller .salg_type = "hash", /* this selects the hash logic in the kernel */ 1113b72c814SStephan Mueller .salg_name = "sha1" /* this is the cipher name */ 1123b72c814SStephan Mueller }; 1133b72c814SStephan Mueller 1143b72c814SStephan Mueller 1153b72c814SStephan MuellerThe salg_type value "hash" applies to message digests and keyed message 1163b72c814SStephan Muellerdigests. Though, a keyed message digest is referenced by the appropriate 1173b72c814SStephan Muellersalg_name. Please see below for the setsockopt interface that explains 1183b72c814SStephan Muellerhow the key can be set for a keyed message digest. 1193b72c814SStephan Mueller 1203b72c814SStephan MuellerUsing the send() system call, the application provides the data that 1213b72c814SStephan Muellershould be processed with the message digest. The send system call allows 1223b72c814SStephan Muellerthe following flags to be specified: 1233b72c814SStephan Mueller 1243b72c814SStephan Mueller- MSG_MORE: If this flag is set, the send system call acts like a 1253b72c814SStephan Mueller message digest update function where the final hash is not yet 1263b72c814SStephan Mueller calculated. If the flag is not set, the send system call calculates 1273b72c814SStephan Mueller the final message digest immediately. 1283b72c814SStephan Mueller 1293b72c814SStephan MuellerWith the recv() system call, the application can read the message digest 1303b72c814SStephan Muellerfrom the kernel crypto API. If the buffer is too small for the message 1313b72c814SStephan Muellerdigest, the flag MSG_TRUNC is set by the kernel. 1323b72c814SStephan Mueller 1333b72c814SStephan MuellerIn order to set a message digest key, the calling application must use 134*7984ceb1SFrederick Lawlerthe setsockopt() option of ALG_SET_KEY or ALG_SET_KEY_BY_KEY_SERIAL. If the 135*7984ceb1SFrederick Lawlerkey is not set the HMAC operation is performed without the initial HMAC state 136*7984ceb1SFrederick Lawlerchange caused by the key. 1373b72c814SStephan Mueller 1383b72c814SStephan MuellerSymmetric Cipher API 1393b72c814SStephan Mueller-------------------- 1403b72c814SStephan Mueller 1413b72c814SStephan MuellerThe operation is very similar to the message digest discussion. During 1423b72c814SStephan Muellerinitialization, the struct sockaddr data structure must be filled as 1433b72c814SStephan Muellerfollows: 1443b72c814SStephan Mueller 1453b72c814SStephan Mueller:: 1463b72c814SStephan Mueller 1473b72c814SStephan Mueller struct sockaddr_alg sa = { 1483b72c814SStephan Mueller .salg_family = AF_ALG, 1493b72c814SStephan Mueller .salg_type = "skcipher", /* this selects the symmetric cipher */ 1503b72c814SStephan Mueller .salg_name = "cbc(aes)" /* this is the cipher name */ 1513b72c814SStephan Mueller }; 1523b72c814SStephan Mueller 1533b72c814SStephan Mueller 1543b72c814SStephan MuellerBefore data can be sent to the kernel using the write/send system call 1553b72c814SStephan Muellerfamily, the consumer must set the key. The key setting is described with 1563b72c814SStephan Muellerthe setsockopt invocation below. 1573b72c814SStephan Mueller 1583b72c814SStephan MuellerUsing the sendmsg() system call, the application provides the data that 1593b72c814SStephan Muellershould be processed for encryption or decryption. In addition, the IV is 1603b72c814SStephan Muellerspecified with the data structure provided by the sendmsg() system call. 1613b72c814SStephan Mueller 1623b72c814SStephan MuellerThe sendmsg system call parameter of struct msghdr is embedded into the 1633b72c814SStephan Muellerstruct cmsghdr data structure. See recv(2) and cmsg(3) for more 1643b72c814SStephan Muellerinformation on how the cmsghdr data structure is used together with the 1653b72c814SStephan Muellersend/recv system call family. That cmsghdr data structure holds the 1663b72c814SStephan Muellerfollowing information specified with a separate header instances: 1673b72c814SStephan Mueller 1683b72c814SStephan Mueller- specification of the cipher operation type with one of these flags: 1693b72c814SStephan Mueller 1703b72c814SStephan Mueller - ALG_OP_ENCRYPT - encryption of data 1713b72c814SStephan Mueller 1723b72c814SStephan Mueller - ALG_OP_DECRYPT - decryption of data 1733b72c814SStephan Mueller 1743b72c814SStephan Mueller- specification of the IV information marked with the flag ALG_SET_IV 1753b72c814SStephan Mueller 1763b72c814SStephan MuellerThe send system call family allows the following flag to be specified: 1773b72c814SStephan Mueller 1783b72c814SStephan Mueller- MSG_MORE: If this flag is set, the send system call acts like a 1793b72c814SStephan Mueller cipher update function where more input data is expected with a 1803b72c814SStephan Mueller subsequent invocation of the send system call. 1813b72c814SStephan Mueller 1823b72c814SStephan MuellerNote: The kernel reports -EINVAL for any unexpected data. The caller 1833b72c814SStephan Muellermust make sure that all data matches the constraints given in 1843b72c814SStephan Mueller/proc/crypto for the selected cipher. 1853b72c814SStephan Mueller 1863b72c814SStephan MuellerWith the recv() system call, the application can read the result of the 1873b72c814SStephan Muellercipher operation from the kernel crypto API. The output buffer must be 1883b72c814SStephan Muellerat least as large as to hold all blocks of the encrypted or decrypted 1893b72c814SStephan Muellerdata. If the output data size is smaller, only as many blocks are 1903b72c814SStephan Muellerreturned that fit into that output buffer size. 1913b72c814SStephan Mueller 1923b72c814SStephan MuellerAEAD Cipher API 1933b72c814SStephan Mueller--------------- 1943b72c814SStephan Mueller 1953b72c814SStephan MuellerThe operation is very similar to the symmetric cipher discussion. During 1963b72c814SStephan Muellerinitialization, the struct sockaddr data structure must be filled as 1973b72c814SStephan Muellerfollows: 1983b72c814SStephan Mueller 1993b72c814SStephan Mueller:: 2003b72c814SStephan Mueller 2013b72c814SStephan Mueller struct sockaddr_alg sa = { 2023b72c814SStephan Mueller .salg_family = AF_ALG, 2033b72c814SStephan Mueller .salg_type = "aead", /* this selects the symmetric cipher */ 2043b72c814SStephan Mueller .salg_name = "gcm(aes)" /* this is the cipher name */ 2053b72c814SStephan Mueller }; 2063b72c814SStephan Mueller 2073b72c814SStephan Mueller 2083b72c814SStephan MuellerBefore data can be sent to the kernel using the write/send system call 2093b72c814SStephan Muellerfamily, the consumer must set the key. The key setting is described with 2103b72c814SStephan Muellerthe setsockopt invocation below. 2113b72c814SStephan Mueller 2123b72c814SStephan MuellerIn addition, before data can be sent to the kernel using the write/send 2133b72c814SStephan Muellersystem call family, the consumer must set the authentication tag size. 2143b72c814SStephan MuellerTo set the authentication tag size, the caller must use the setsockopt 2153b72c814SStephan Muellerinvocation described below. 2163b72c814SStephan Mueller 2173b72c814SStephan MuellerUsing the sendmsg() system call, the application provides the data that 2183b72c814SStephan Muellershould be processed for encryption or decryption. In addition, the IV is 2193b72c814SStephan Muellerspecified with the data structure provided by the sendmsg() system call. 2203b72c814SStephan Mueller 2213b72c814SStephan MuellerThe sendmsg system call parameter of struct msghdr is embedded into the 2223b72c814SStephan Muellerstruct cmsghdr data structure. See recv(2) and cmsg(3) for more 2233b72c814SStephan Muellerinformation on how the cmsghdr data structure is used together with the 2243b72c814SStephan Muellersend/recv system call family. That cmsghdr data structure holds the 2253b72c814SStephan Muellerfollowing information specified with a separate header instances: 2263b72c814SStephan Mueller 2273b72c814SStephan Mueller- specification of the cipher operation type with one of these flags: 2283b72c814SStephan Mueller 2293b72c814SStephan Mueller - ALG_OP_ENCRYPT - encryption of data 2303b72c814SStephan Mueller 2313b72c814SStephan Mueller - ALG_OP_DECRYPT - decryption of data 2323b72c814SStephan Mueller 2333b72c814SStephan Mueller- specification of the IV information marked with the flag ALG_SET_IV 2343b72c814SStephan Mueller 2353b72c814SStephan Mueller- specification of the associated authentication data (AAD) with the 2363b72c814SStephan Mueller flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together 2373b72c814SStephan Mueller with the plaintext / ciphertext. See below for the memory structure. 2383b72c814SStephan Mueller 2393b72c814SStephan MuellerThe send system call family allows the following flag to be specified: 2403b72c814SStephan Mueller 2413b72c814SStephan Mueller- MSG_MORE: If this flag is set, the send system call acts like a 2423b72c814SStephan Mueller cipher update function where more input data is expected with a 2433b72c814SStephan Mueller subsequent invocation of the send system call. 2443b72c814SStephan Mueller 2453b72c814SStephan MuellerNote: The kernel reports -EINVAL for any unexpected data. The caller 2463b72c814SStephan Muellermust make sure that all data matches the constraints given in 2473b72c814SStephan Mueller/proc/crypto for the selected cipher. 2483b72c814SStephan Mueller 2493b72c814SStephan MuellerWith the recv() system call, the application can read the result of the 2503b72c814SStephan Muellercipher operation from the kernel crypto API. The output buffer must be 2513b72c814SStephan Muellerat least as large as defined with the memory structure below. If the 2523b72c814SStephan Muelleroutput data size is smaller, the cipher operation is not performed. 2533b72c814SStephan Mueller 2543b72c814SStephan MuellerThe authenticated decryption operation may indicate an integrity error. 2553b72c814SStephan MuellerSuch breach in integrity is marked with the -EBADMSG error code. 2563b72c814SStephan Mueller 2573b72c814SStephan MuellerAEAD Memory Structure 2583b72c814SStephan Mueller~~~~~~~~~~~~~~~~~~~~~ 2593b72c814SStephan Mueller 2603b72c814SStephan MuellerThe AEAD cipher operates with the following information that is 2613b72c814SStephan Muellercommunicated between user and kernel space as one data stream: 2623b72c814SStephan Mueller 2633b72c814SStephan Mueller- plaintext or ciphertext 2643b72c814SStephan Mueller 2653b72c814SStephan Mueller- associated authentication data (AAD) 2663b72c814SStephan Mueller 2673b72c814SStephan Mueller- authentication tag 2683b72c814SStephan Mueller 2693b72c814SStephan MuellerThe sizes of the AAD and the authentication tag are provided with the 2703b72c814SStephan Muellersendmsg and setsockopt calls (see there). As the kernel knows the size 2713b72c814SStephan Muellerof the entire data stream, the kernel is now able to calculate the right 2723b72c814SStephan Muelleroffsets of the data components in the data stream. 2733b72c814SStephan Mueller 2743b72c814SStephan MuellerThe user space caller must arrange the aforementioned information in the 2753b72c814SStephan Muellerfollowing order: 2763b72c814SStephan Mueller 2773b72c814SStephan Mueller- AEAD encryption input: AAD \|\| plaintext 2783b72c814SStephan Mueller 2793b72c814SStephan Mueller- AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag 2803b72c814SStephan Mueller 2813b72c814SStephan MuellerThe output buffer the user space caller provides must be at least as 2823b72c814SStephan Muellerlarge to hold the following data: 2833b72c814SStephan Mueller 2843b72c814SStephan Mueller- AEAD encryption output: ciphertext \|\| authentication tag 2853b72c814SStephan Mueller 2863b72c814SStephan Mueller- AEAD decryption output: plaintext 2873b72c814SStephan Mueller 2883b72c814SStephan MuellerRandom Number Generator API 2893b72c814SStephan Mueller--------------------------- 2903b72c814SStephan Mueller 2913b72c814SStephan MuellerAgain, the operation is very similar to the other APIs. During 2923b72c814SStephan Muellerinitialization, the struct sockaddr data structure must be filled as 2933b72c814SStephan Muellerfollows: 2943b72c814SStephan Mueller 2953b72c814SStephan Mueller:: 2963b72c814SStephan Mueller 2973b72c814SStephan Mueller struct sockaddr_alg sa = { 2983b72c814SStephan Mueller .salg_family = AF_ALG, 29977ebdabeSElena Petrova .salg_type = "rng", /* this selects the random number generator */ 30077ebdabeSElena Petrova .salg_name = "drbg_nopr_sha256" /* this is the RNG name */ 3013b72c814SStephan Mueller }; 3023b72c814SStephan Mueller 3033b72c814SStephan Mueller 3043b72c814SStephan MuellerDepending on the RNG type, the RNG must be seeded. The seed is provided 3053b72c814SStephan Muellerusing the setsockopt interface to set the key. For example, the 3063b72c814SStephan Muelleransi_cprng requires a seed. The DRBGs do not require a seed, but may be 30777ebdabeSElena Petrovaseeded. The seed is also known as a *Personalization String* in NIST SP 800-90A 30877ebdabeSElena Petrovastandard. 3093b72c814SStephan Mueller 3103b72c814SStephan MuellerUsing the read()/recvmsg() system calls, random numbers can be obtained. 3113b72c814SStephan MuellerThe kernel generates at most 128 bytes in one call. If user space 3123b72c814SStephan Muellerrequires more data, multiple calls to read()/recvmsg() must be made. 3133b72c814SStephan Mueller 3143b72c814SStephan MuellerWARNING: The user space caller may invoke the initially mentioned accept 3153b72c814SStephan Muellersystem call multiple times. In this case, the returned file descriptors 3163b72c814SStephan Muellerhave the same state. 3173b72c814SStephan Mueller 31877ebdabeSElena PetrovaFollowing CAVP testing interfaces are enabled when kernel is built with 31977ebdabeSElena PetrovaCRYPTO_USER_API_RNG_CAVP option: 32077ebdabeSElena Petrova 32177ebdabeSElena Petrova- the concatenation of *Entropy* and *Nonce* can be provided to the RNG via 32277ebdabeSElena Petrova ALG_SET_DRBG_ENTROPY setsockopt interface. Setting the entropy requires 32377ebdabeSElena Petrova CAP_SYS_ADMIN permission. 32477ebdabeSElena Petrova 32577ebdabeSElena Petrova- *Additional Data* can be provided using the send()/sendmsg() system calls, 32677ebdabeSElena Petrova but only after the entropy has been set. 32777ebdabeSElena Petrova 3283b72c814SStephan MuellerZero-Copy Interface 3293b72c814SStephan Mueller------------------- 3303b72c814SStephan Mueller 3313b72c814SStephan MuellerIn addition to the send/write/read/recv system call family, the AF_ALG 3323b72c814SStephan Muellerinterface can be accessed with the zero-copy interface of 3333b72c814SStephan Muellersplice/vmsplice. As the name indicates, the kernel tries to avoid a copy 3343b72c814SStephan Muelleroperation into kernel space. 3353b72c814SStephan Mueller 3363b72c814SStephan MuellerThe zero-copy operation requires data to be aligned at the page 3373b72c814SStephan Muellerboundary. Non-aligned data can be used as well, but may require more 3383b72c814SStephan Muelleroperations of the kernel which would defeat the speed gains obtained 3393b72c814SStephan Muellerfrom the zero-copy interface. 3403b72c814SStephan Mueller 3418bd1d400SBenjamin PetersonThe system-inherent limit for the size of one zero-copy operation is 16 3423b72c814SStephan Muellerpages. If more data is to be sent to AF_ALG, user space must slice the 3433b72c814SStephan Muellerinput into segments with a maximum size of 16 pages. 3443b72c814SStephan Mueller 3453b72c814SStephan MuellerZero-copy can be used with the following code example (a complete 3463b72c814SStephan Muellerworking example is provided with libkcapi): 3473b72c814SStephan Mueller 3483b72c814SStephan Mueller:: 3493b72c814SStephan Mueller 3503b72c814SStephan Mueller int pipes[2]; 3513b72c814SStephan Mueller 3523b72c814SStephan Mueller pipe(pipes); 3533b72c814SStephan Mueller /* input data in iov */ 3543b72c814SStephan Mueller vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT); 3553b72c814SStephan Mueller /* opfd is the file descriptor returned from accept() system call */ 3563b72c814SStephan Mueller splice(pipes[0], NULL, opfd, NULL, ret, 0); 3573b72c814SStephan Mueller read(opfd, out, outlen); 3583b72c814SStephan Mueller 3593b72c814SStephan Mueller 3603b72c814SStephan MuellerSetsockopt Interface 3613b72c814SStephan Mueller-------------------- 3623b72c814SStephan Mueller 3633b72c814SStephan MuellerIn addition to the read/recv and send/write system call handling to send 3643b72c814SStephan Muellerand retrieve data subject to the cipher operation, a consumer also needs 3653b72c814SStephan Muellerto set the additional information for the cipher operation. This 3663b72c814SStephan Muelleradditional information is set using the setsockopt system call that must 3673b72c814SStephan Muellerbe invoked with the file descriptor of the open cipher (i.e. the file 3683b72c814SStephan Muellerdescriptor returned by the accept system call). 3693b72c814SStephan Mueller 3703b72c814SStephan MuellerEach setsockopt invocation must use the level SOL_ALG. 3713b72c814SStephan Mueller 3723b72c814SStephan MuellerThe setsockopt interface allows setting the following data using the 3733b72c814SStephan Muellermentioned optname: 3743b72c814SStephan Mueller 3753b72c814SStephan Mueller- ALG_SET_KEY -- Setting the key. Key setting is applicable to: 3763b72c814SStephan Mueller 3773b72c814SStephan Mueller - the skcipher cipher type (symmetric ciphers) 3783b72c814SStephan Mueller 3793b72c814SStephan Mueller - the hash cipher type (keyed message digests) 3803b72c814SStephan Mueller 3813b72c814SStephan Mueller - the AEAD cipher type 3823b72c814SStephan Mueller 3833b72c814SStephan Mueller - the RNG cipher type to provide the seed 3843b72c814SStephan Mueller 385*7984ceb1SFrederick Lawler- ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key via keyring key_serial_t. 386*7984ceb1SFrederick Lawler This operation behaves the same as ALG_SET_KEY. The decrypted 387*7984ceb1SFrederick Lawler data is copied from a keyring key, and uses that data as the 388*7984ceb1SFrederick Lawler key for symmetric encryption. 389*7984ceb1SFrederick Lawler 390*7984ceb1SFrederick Lawler The passed in key_serial_t must have the KEY_(POS|USR|GRP|OTH)_SEARCH 391*7984ceb1SFrederick Lawler permission set, otherwise -EPERM is returned. Supports key types: user, 392*7984ceb1SFrederick Lawler logon, encrypted, and trusted. 393*7984ceb1SFrederick Lawler 3943b72c814SStephan Mueller- ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for 3953b72c814SStephan Mueller AEAD ciphers. For a encryption operation, the authentication tag of 3963b72c814SStephan Mueller the given size will be generated. For a decryption operation, the 3973b72c814SStephan Mueller provided ciphertext is assumed to contain an authentication tag of 3983b72c814SStephan Mueller the given size (see section about AEAD memory layout below). 3993b72c814SStephan Mueller 40077ebdabeSElena Petrova- ALG_SET_DRBG_ENTROPY -- Setting the entropy of the random number generator. 40177ebdabeSElena Petrova This option is applicable to RNG cipher type only. 40277ebdabeSElena Petrova 4033b72c814SStephan MuellerUser space API example 4043b72c814SStephan Mueller---------------------- 4053b72c814SStephan Mueller 4063b72c814SStephan MuellerPlease see [1] for libkcapi which provides an easy-to-use wrapper around 4073b72c814SStephan Muellerthe aforementioned Netlink kernel interface. [1] also contains a test 4083b72c814SStephan Muellerapplication that invokes all libkcapi API calls. 4093b72c814SStephan Mueller 4109332a9e7SAlexander A. Klimov[1] https://www.chronox.de/libkcapi.html 411