~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

TOMOYO Linux Cross Reference
Linux/Documentation/crypto/userspace-if.rst

Version: ~ [ linux-6.12-rc7 ] ~ [ linux-6.11.7 ] ~ [ linux-6.10.14 ] ~ [ linux-6.9.12 ] ~ [ linux-6.8.12 ] ~ [ linux-6.7.12 ] ~ [ linux-6.6.60 ] ~ [ linux-6.5.13 ] ~ [ linux-6.4.16 ] ~ [ linux-6.3.13 ] ~ [ linux-6.2.16 ] ~ [ linux-6.1.116 ] ~ [ linux-6.0.19 ] ~ [ linux-5.19.17 ] ~ [ linux-5.18.19 ] ~ [ linux-5.17.15 ] ~ [ linux-5.16.20 ] ~ [ linux-5.15.171 ] ~ [ linux-5.14.21 ] ~ [ linux-5.13.19 ] ~ [ linux-5.12.19 ] ~ [ linux-5.11.22 ] ~ [ linux-5.10.229 ] ~ [ linux-5.9.16 ] ~ [ linux-5.8.18 ] ~ [ linux-5.7.19 ] ~ [ linux-5.6.19 ] ~ [ linux-5.5.19 ] ~ [ linux-5.4.285 ] ~ [ linux-5.3.18 ] ~ [ linux-5.2.21 ] ~ [ linux-5.1.21 ] ~ [ linux-5.0.21 ] ~ [ linux-4.20.17 ] ~ [ linux-4.19.323 ] ~ [ linux-4.18.20 ] ~ [ linux-4.17.19 ] ~ [ linux-4.16.18 ] ~ [ linux-4.15.18 ] ~ [ linux-4.14.336 ] ~ [ linux-4.13.16 ] ~ [ linux-4.12.14 ] ~ [ linux-4.11.12 ] ~ [ linux-4.10.17 ] ~ [ linux-4.9.337 ] ~ [ linux-4.4.302 ] ~ [ linux-3.10.108 ] ~ [ linux-2.6.32.71 ] ~ [ linux-2.6.0 ] ~ [ linux-2.4.37.11 ] ~ [ unix-v6-master ] ~ [ ccs-tools-1.8.12 ] ~ [ policy-sample ] ~
Architecture: ~ [ i386 ] ~ [ alpha ] ~ [ m68k ] ~ [ mips ] ~ [ ppc ] ~ [ sparc ] ~ [ sparc64 ] ~

Diff markup

Differences between /Documentation/crypto/userspace-if.rst (Version linux-6.12-rc7) and /Documentation/crypto/userspace-if.rst (Version linux-5.5.19)


  1 User Space Interface                                1 User Space Interface
  2 ====================                                2 ====================
  3                                                     3 
  4 Introduction                                        4 Introduction
  5 ------------                                        5 ------------
  6                                                     6 
  7 The concepts of the kernel crypto API visible       7 The concepts of the kernel crypto API visible to kernel space is fully
  8 applicable to the user space interface as well      8 applicable to the user space interface as well. Therefore, the kernel
  9 crypto API high level discussion for the in-ke      9 crypto API high level discussion for the in-kernel use cases applies
 10 here as well.                                      10 here as well.
 11                                                    11 
 12 The major difference, however, is that user sp     12 The major difference, however, is that user space can only act as a
 13 consumer and never as a provider of a transfor     13 consumer and never as a provider of a transformation or cipher
 14 algorithm.                                         14 algorithm.
 15                                                    15 
 16 The following covers the user space interface      16 The following covers the user space interface exported by the kernel
 17 crypto API. A working example of this descript     17 crypto API. A working example of this description is libkcapi that can
 18 be obtained from [1]. That library can be used     18 be obtained from [1]. That library can be used by user space
 19 applications that require cryptographic servic     19 applications that require cryptographic services from the kernel.
 20                                                    20 
 21 Some details of the in-kernel kernel crypto AP     21 Some details of the in-kernel kernel crypto API aspects do not apply to
 22 user space, however. This includes the differe     22 user space, however. This includes the difference between synchronous
 23 and asynchronous invocations. The user space A     23 and asynchronous invocations. The user space API call is fully
 24 synchronous.                                       24 synchronous.
 25                                                    25 
 26 [1] https://www.chronox.de/libkcapi.html       !!  26 [1] http://www.chronox.de/libkcapi.html
 27                                                    27 
 28 User Space API General Remarks                     28 User Space API General Remarks
 29 ------------------------------                     29 ------------------------------
 30                                                    30 
 31 The kernel crypto API is accessible from user      31 The kernel crypto API is accessible from user space. Currently, the
 32 following ciphers are accessible:                  32 following ciphers are accessible:
 33                                                    33 
 34 -  Message digest including keyed message dige     34 -  Message digest including keyed message digest (HMAC, CMAC)
 35                                                    35 
 36 -  Symmetric ciphers                               36 -  Symmetric ciphers
 37                                                    37 
 38 -  AEAD ciphers                                    38 -  AEAD ciphers
 39                                                    39 
 40 -  Random Number Generators                        40 -  Random Number Generators
 41                                                    41 
 42 The interface is provided via socket type usin     42 The interface is provided via socket type using the type AF_ALG. In
 43 addition, the setsockopt option type is SOL_AL     43 addition, the setsockopt option type is SOL_ALG. In case the user space
 44 header files do not export these flags yet, us     44 header files do not export these flags yet, use the following macros:
 45                                                    45 
 46 ::                                                 46 ::
 47                                                    47 
 48     #ifndef AF_ALG                                 48     #ifndef AF_ALG
 49     #define AF_ALG 38                              49     #define AF_ALG 38
 50     #endif                                         50     #endif
 51     #ifndef SOL_ALG                                51     #ifndef SOL_ALG
 52     #define SOL_ALG 279                            52     #define SOL_ALG 279
 53     #endif                                         53     #endif
 54                                                    54 
 55                                                    55 
 56 A cipher is accessed with the same name as don     56 A cipher is accessed with the same name as done for the in-kernel API
 57 calls. This includes the generic vs. unique na     57 calls. This includes the generic vs. unique naming schema for ciphers as
 58 well as the enforcement of priorities for gene     58 well as the enforcement of priorities for generic names.
 59                                                    59 
 60 To interact with the kernel crypto API, a sock     60 To interact with the kernel crypto API, a socket must be created by the
 61 user space application. User space invokes the     61 user space application. User space invokes the cipher operation with the
 62 send()/write() system call family. The result      62 send()/write() system call family. The result of the cipher operation is
 63 obtained with the read()/recv() system call fa     63 obtained with the read()/recv() system call family.
 64                                                    64 
 65 The following API calls assume that the socket     65 The following API calls assume that the socket descriptor is already
 66 opened by the user space application and discu     66 opened by the user space application and discusses only the kernel
 67 crypto API specific invocations.                   67 crypto API specific invocations.
 68                                                    68 
 69 To initialize the socket interface, the follow     69 To initialize the socket interface, the following sequence has to be
 70 performed by the consumer:                         70 performed by the consumer:
 71                                                    71 
 72 1. Create a socket of type AF_ALG with the str     72 1. Create a socket of type AF_ALG with the struct sockaddr_alg
 73    parameter specified below for the different     73    parameter specified below for the different cipher types.
 74                                                    74 
 75 2. Invoke bind with the socket descriptor          75 2. Invoke bind with the socket descriptor
 76                                                    76 
 77 3. Invoke accept with the socket descriptor. T     77 3. Invoke accept with the socket descriptor. The accept system call
 78    returns a new file descriptor that is to be     78    returns a new file descriptor that is to be used to interact with the
 79    particular cipher instance. When invoking s     79    particular cipher instance. When invoking send/write or recv/read
 80    system calls to send data to the kernel or      80    system calls to send data to the kernel or obtain data from the
 81    kernel, the file descriptor returned by acc     81    kernel, the file descriptor returned by accept must be used.
 82                                                    82 
 83 In-place Cipher operation                          83 In-place Cipher operation
 84 -------------------------                          84 -------------------------
 85                                                    85 
 86 Just like the in-kernel operation of the kerne     86 Just like the in-kernel operation of the kernel crypto API, the user
 87 space interface allows the cipher operation in     87 space interface allows the cipher operation in-place. That means that
 88 the input buffer used for the send/write syste     88 the input buffer used for the send/write system call and the output
 89 buffer used by the read/recv system call may b     89 buffer used by the read/recv system call may be one and the same. This
 90 is of particular interest for symmetric cipher     90 is of particular interest for symmetric cipher operations where a
 91 copying of the output data to its final destin     91 copying of the output data to its final destination can be avoided.
 92                                                    92 
 93 If a consumer on the other hand wants to maint     93 If a consumer on the other hand wants to maintain the plaintext and the
 94 ciphertext in different memory locations, all      94 ciphertext in different memory locations, all a consumer needs to do is
 95 to provide different memory pointers for the e     95 to provide different memory pointers for the encryption and decryption
 96 operation.                                         96 operation.
 97                                                    97 
 98 Message Digest API                                 98 Message Digest API
 99 ------------------                                 99 ------------------
100                                                   100 
101 The message digest type to be used for the cip    101 The message digest type to be used for the cipher operation is selected
102 when invoking the bind syscall. bind requires     102 when invoking the bind syscall. bind requires the caller to provide a
103 filled struct sockaddr data structure. This da    103 filled struct sockaddr data structure. This data structure must be
104 filled as follows:                                104 filled as follows:
105                                                   105 
106 ::                                                106 ::
107                                                   107 
108     struct sockaddr_alg sa = {                    108     struct sockaddr_alg sa = {
109         .salg_family = AF_ALG,                    109         .salg_family = AF_ALG,
110         .salg_type = "hash", /* this selects t    110         .salg_type = "hash", /* this selects the hash logic in the kernel */
111         .salg_name = "sha1" /* this is the cip    111         .salg_name = "sha1" /* this is the cipher name */
112     };                                            112     };
113                                                   113 
114                                                   114 
115 The salg_type value "hash" applies to message     115 The salg_type value "hash" applies to message digests and keyed message
116 digests. Though, a keyed message digest is ref    116 digests. Though, a keyed message digest is referenced by the appropriate
117 salg_name. Please see below for the setsockopt    117 salg_name. Please see below for the setsockopt interface that explains
118 how the key can be set for a keyed message dig    118 how the key can be set for a keyed message digest.
119                                                   119 
120 Using the send() system call, the application     120 Using the send() system call, the application provides the data that
121 should be processed with the message digest. T    121 should be processed with the message digest. The send system call allows
122 the following flags to be specified:              122 the following flags to be specified:
123                                                   123 
124 -  MSG_MORE: If this flag is set, the send sys    124 -  MSG_MORE: If this flag is set, the send system call acts like a
125    message digest update function where the fi    125    message digest update function where the final hash is not yet
126    calculated. If the flag is not set, the sen    126    calculated. If the flag is not set, the send system call calculates
127    the final message digest immediately.          127    the final message digest immediately.
128                                                   128 
129 With the recv() system call, the application c    129 With the recv() system call, the application can read the message digest
130 from the kernel crypto API. If the buffer is t    130 from the kernel crypto API. If the buffer is too small for the message
131 digest, the flag MSG_TRUNC is set by the kerne    131 digest, the flag MSG_TRUNC is set by the kernel.
132                                                   132 
133 In order to set a message digest key, the call    133 In order to set a message digest key, the calling application must use
134 the setsockopt() option of ALG_SET_KEY or ALG_ !! 134 the setsockopt() option of ALG_SET_KEY. If the key is not set the HMAC
135 key is not set the HMAC operation is performed !! 135 operation is performed without the initial HMAC state change caused by
136 change caused by the key.                      !! 136 the key.
137                                                   137 
138 Symmetric Cipher API                              138 Symmetric Cipher API
139 --------------------                              139 --------------------
140                                                   140 
141 The operation is very similar to the message d    141 The operation is very similar to the message digest discussion. During
142 initialization, the struct sockaddr data struc    142 initialization, the struct sockaddr data structure must be filled as
143 follows:                                          143 follows:
144                                                   144 
145 ::                                                145 ::
146                                                   146 
147     struct sockaddr_alg sa = {                    147     struct sockaddr_alg sa = {
148         .salg_family = AF_ALG,                    148         .salg_family = AF_ALG,
149         .salg_type = "skcipher", /* this selec    149         .salg_type = "skcipher", /* this selects the symmetric cipher */
150         .salg_name = "cbc(aes)" /* this is the    150         .salg_name = "cbc(aes)" /* this is the cipher name */
151     };                                            151     };
152                                                   152 
153                                                   153 
154 Before data can be sent to the kernel using th    154 Before data can be sent to the kernel using the write/send system call
155 family, the consumer must set the key. The key    155 family, the consumer must set the key. The key setting is described with
156 the setsockopt invocation below.                  156 the setsockopt invocation below.
157                                                   157 
158 Using the sendmsg() system call, the applicati    158 Using the sendmsg() system call, the application provides the data that
159 should be processed for encryption or decrypti    159 should be processed for encryption or decryption. In addition, the IV is
160 specified with the data structure provided by     160 specified with the data structure provided by the sendmsg() system call.
161                                                   161 
162 The sendmsg system call parameter of struct ms    162 The sendmsg system call parameter of struct msghdr is embedded into the
163 struct cmsghdr data structure. See recv(2) and    163 struct cmsghdr data structure. See recv(2) and cmsg(3) for more
164 information on how the cmsghdr data structure     164 information on how the cmsghdr data structure is used together with the
165 send/recv system call family. That cmsghdr dat    165 send/recv system call family. That cmsghdr data structure holds the
166 following information specified with a separat    166 following information specified with a separate header instances:
167                                                   167 
168 -  specification of the cipher operation type     168 -  specification of the cipher operation type with one of these flags:
169                                                   169 
170    -  ALG_OP_ENCRYPT - encryption of data         170    -  ALG_OP_ENCRYPT - encryption of data
171                                                   171 
172    -  ALG_OP_DECRYPT - decryption of data         172    -  ALG_OP_DECRYPT - decryption of data
173                                                   173 
174 -  specification of the IV information marked     174 -  specification of the IV information marked with the flag ALG_SET_IV
175                                                   175 
176 The send system call family allows the followi    176 The send system call family allows the following flag to be specified:
177                                                   177 
178 -  MSG_MORE: If this flag is set, the send sys    178 -  MSG_MORE: If this flag is set, the send system call acts like a
179    cipher update function where more input dat    179    cipher update function where more input data is expected with a
180    subsequent invocation of the send system ca    180    subsequent invocation of the send system call.
181                                                   181 
182 Note: The kernel reports -EINVAL for any unexp    182 Note: The kernel reports -EINVAL for any unexpected data. The caller
183 must make sure that all data matches the const    183 must make sure that all data matches the constraints given in
184 /proc/crypto for the selected cipher.             184 /proc/crypto for the selected cipher.
185                                                   185 
186 With the recv() system call, the application c    186 With the recv() system call, the application can read the result of the
187 cipher operation from the kernel crypto API. T    187 cipher operation from the kernel crypto API. The output buffer must be
188 at least as large as to hold all blocks of the    188 at least as large as to hold all blocks of the encrypted or decrypted
189 data. If the output data size is smaller, only    189 data. If the output data size is smaller, only as many blocks are
190 returned that fit into that output buffer size    190 returned that fit into that output buffer size.
191                                                   191 
192 AEAD Cipher API                                   192 AEAD Cipher API
193 ---------------                                   193 ---------------
194                                                   194 
195 The operation is very similar to the symmetric    195 The operation is very similar to the symmetric cipher discussion. During
196 initialization, the struct sockaddr data struc    196 initialization, the struct sockaddr data structure must be filled as
197 follows:                                          197 follows:
198                                                   198 
199 ::                                                199 ::
200                                                   200 
201     struct sockaddr_alg sa = {                    201     struct sockaddr_alg sa = {
202         .salg_family = AF_ALG,                    202         .salg_family = AF_ALG,
203         .salg_type = "aead", /* this selects t    203         .salg_type = "aead", /* this selects the symmetric cipher */
204         .salg_name = "gcm(aes)" /* this is the    204         .salg_name = "gcm(aes)" /* this is the cipher name */
205     };                                            205     };
206                                                   206 
207                                                   207 
208 Before data can be sent to the kernel using th    208 Before data can be sent to the kernel using the write/send system call
209 family, the consumer must set the key. The key    209 family, the consumer must set the key. The key setting is described with
210 the setsockopt invocation below.                  210 the setsockopt invocation below.
211                                                   211 
212 In addition, before data can be sent to the ke    212 In addition, before data can be sent to the kernel using the write/send
213 system call family, the consumer must set the     213 system call family, the consumer must set the authentication tag size.
214 To set the authentication tag size, the caller    214 To set the authentication tag size, the caller must use the setsockopt
215 invocation described below.                       215 invocation described below.
216                                                   216 
217 Using the sendmsg() system call, the applicati    217 Using the sendmsg() system call, the application provides the data that
218 should be processed for encryption or decrypti    218 should be processed for encryption or decryption. In addition, the IV is
219 specified with the data structure provided by     219 specified with the data structure provided by the sendmsg() system call.
220                                                   220 
221 The sendmsg system call parameter of struct ms    221 The sendmsg system call parameter of struct msghdr is embedded into the
222 struct cmsghdr data structure. See recv(2) and    222 struct cmsghdr data structure. See recv(2) and cmsg(3) for more
223 information on how the cmsghdr data structure     223 information on how the cmsghdr data structure is used together with the
224 send/recv system call family. That cmsghdr dat    224 send/recv system call family. That cmsghdr data structure holds the
225 following information specified with a separat    225 following information specified with a separate header instances:
226                                                   226 
227 -  specification of the cipher operation type     227 -  specification of the cipher operation type with one of these flags:
228                                                   228 
229    -  ALG_OP_ENCRYPT - encryption of data         229    -  ALG_OP_ENCRYPT - encryption of data
230                                                   230 
231    -  ALG_OP_DECRYPT - decryption of data         231    -  ALG_OP_DECRYPT - decryption of data
232                                                   232 
233 -  specification of the IV information marked     233 -  specification of the IV information marked with the flag ALG_SET_IV
234                                                   234 
235 -  specification of the associated authenticat    235 -  specification of the associated authentication data (AAD) with the
236    flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent    236    flag ALG_SET_AEAD_ASSOCLEN. The AAD is sent to the kernel together
237    with the plaintext / ciphertext. See below     237    with the plaintext / ciphertext. See below for the memory structure.
238                                                   238 
239 The send system call family allows the followi    239 The send system call family allows the following flag to be specified:
240                                                   240 
241 -  MSG_MORE: If this flag is set, the send sys    241 -  MSG_MORE: If this flag is set, the send system call acts like a
242    cipher update function where more input dat    242    cipher update function where more input data is expected with a
243    subsequent invocation of the send system ca    243    subsequent invocation of the send system call.
244                                                   244 
245 Note: The kernel reports -EINVAL for any unexp    245 Note: The kernel reports -EINVAL for any unexpected data. The caller
246 must make sure that all data matches the const    246 must make sure that all data matches the constraints given in
247 /proc/crypto for the selected cipher.             247 /proc/crypto for the selected cipher.
248                                                   248 
249 With the recv() system call, the application c    249 With the recv() system call, the application can read the result of the
250 cipher operation from the kernel crypto API. T    250 cipher operation from the kernel crypto API. The output buffer must be
251 at least as large as defined with the memory s    251 at least as large as defined with the memory structure below. If the
252 output data size is smaller, the cipher operat    252 output data size is smaller, the cipher operation is not performed.
253                                                   253 
254 The authenticated decryption operation may ind    254 The authenticated decryption operation may indicate an integrity error.
255 Such breach in integrity is marked with the -E    255 Such breach in integrity is marked with the -EBADMSG error code.
256                                                   256 
257 AEAD Memory Structure                             257 AEAD Memory Structure
258 ~~~~~~~~~~~~~~~~~~~~~                             258 ~~~~~~~~~~~~~~~~~~~~~
259                                                   259 
260 The AEAD cipher operates with the following in    260 The AEAD cipher operates with the following information that is
261 communicated between user and kernel space as     261 communicated between user and kernel space as one data stream:
262                                                   262 
263 -  plaintext or ciphertext                        263 -  plaintext or ciphertext
264                                                   264 
265 -  associated authentication data (AAD)           265 -  associated authentication data (AAD)
266                                                   266 
267 -  authentication tag                             267 -  authentication tag
268                                                   268 
269 The sizes of the AAD and the authentication ta    269 The sizes of the AAD and the authentication tag are provided with the
270 sendmsg and setsockopt calls (see there). As t    270 sendmsg and setsockopt calls (see there). As the kernel knows the size
271 of the entire data stream, the kernel is now a    271 of the entire data stream, the kernel is now able to calculate the right
272 offsets of the data components in the data str    272 offsets of the data components in the data stream.
273                                                   273 
274 The user space caller must arrange the aforeme    274 The user space caller must arrange the aforementioned information in the
275 following order:                                  275 following order:
276                                                   276 
277 -  AEAD encryption input: AAD \|\| plaintext      277 -  AEAD encryption input: AAD \|\| plaintext
278                                                   278 
279 -  AEAD decryption input: AAD \|\| ciphertext     279 -  AEAD decryption input: AAD \|\| ciphertext \|\| authentication tag
280                                                   280 
281 The output buffer the user space caller provid    281 The output buffer the user space caller provides must be at least as
282 large to hold the following data:                 282 large to hold the following data:
283                                                   283 
284 -  AEAD encryption output: ciphertext \|\| aut    284 -  AEAD encryption output: ciphertext \|\| authentication tag
285                                                   285 
286 -  AEAD decryption output: plaintext              286 -  AEAD decryption output: plaintext
287                                                   287 
288 Random Number Generator API                       288 Random Number Generator API
289 ---------------------------                       289 ---------------------------
290                                                   290 
291 Again, the operation is very similar to the ot    291 Again, the operation is very similar to the other APIs. During
292 initialization, the struct sockaddr data struc    292 initialization, the struct sockaddr data structure must be filled as
293 follows:                                          293 follows:
294                                                   294 
295 ::                                                295 ::
296                                                   296 
297     struct sockaddr_alg sa = {                    297     struct sockaddr_alg sa = {
298         .salg_family = AF_ALG,                    298         .salg_family = AF_ALG,
299         .salg_type = "rng", /* this selects th !! 299         .salg_type = "rng", /* this selects the symmetric cipher */
300         .salg_name = "drbg_nopr_sha256" /* thi !! 300         .salg_name = "drbg_nopr_sha256" /* this is the cipher name */
301     };                                            301     };
302                                                   302 
303                                                   303 
304 Depending on the RNG type, the RNG must be see    304 Depending on the RNG type, the RNG must be seeded. The seed is provided
305 using the setsockopt interface to set the key.    305 using the setsockopt interface to set the key. For example, the
306 ansi_cprng requires a seed. The DRBGs do not r    306 ansi_cprng requires a seed. The DRBGs do not require a seed, but may be
307 seeded. The seed is also known as a *Personali !! 307 seeded.
308 standard.                                      << 
309                                                   308 
310 Using the read()/recvmsg() system calls, rando    309 Using the read()/recvmsg() system calls, random numbers can be obtained.
311 The kernel generates at most 128 bytes in one     310 The kernel generates at most 128 bytes in one call. If user space
312 requires more data, multiple calls to read()/r    311 requires more data, multiple calls to read()/recvmsg() must be made.
313                                                   312 
314 WARNING: The user space caller may invoke the     313 WARNING: The user space caller may invoke the initially mentioned accept
315 system call multiple times. In this case, the     314 system call multiple times. In this case, the returned file descriptors
316 have the same state.                              315 have the same state.
317                                                   316 
318 Following CAVP testing interfaces are enabled  << 
319 CRYPTO_USER_API_RNG_CAVP option:               << 
320                                                << 
321 -  the concatenation of *Entropy* and *Nonce*  << 
322    ALG_SET_DRBG_ENTROPY setsockopt interface.  << 
323    CAP_SYS_ADMIN permission.                   << 
324                                                << 
325 -  *Additional Data* can be provided using the << 
326    but only after the entropy has been set.    << 
327                                                << 
328 Zero-Copy Interface                               317 Zero-Copy Interface
329 -------------------                               318 -------------------
330                                                   319 
331 In addition to the send/write/read/recv system    320 In addition to the send/write/read/recv system call family, the AF_ALG
332 interface can be accessed with the zero-copy i    321 interface can be accessed with the zero-copy interface of
333 splice/vmsplice. As the name indicates, the ke    322 splice/vmsplice. As the name indicates, the kernel tries to avoid a copy
334 operation into kernel space.                      323 operation into kernel space.
335                                                   324 
336 The zero-copy operation requires data to be al    325 The zero-copy operation requires data to be aligned at the page
337 boundary. Non-aligned data can be used as well    326 boundary. Non-aligned data can be used as well, but may require more
338 operations of the kernel which would defeat th    327 operations of the kernel which would defeat the speed gains obtained
339 from the zero-copy interface.                     328 from the zero-copy interface.
340                                                   329 
341 The system-inherent limit for the size of one     330 The system-inherent limit for the size of one zero-copy operation is 16
342 pages. If more data is to be sent to AF_ALG, u    331 pages. If more data is to be sent to AF_ALG, user space must slice the
343 input into segments with a maximum size of 16     332 input into segments with a maximum size of 16 pages.
344                                                   333 
345 Zero-copy can be used with the following code     334 Zero-copy can be used with the following code example (a complete
346 working example is provided with libkcapi):       335 working example is provided with libkcapi):
347                                                   336 
348 ::                                                337 ::
349                                                   338 
350     int pipes[2];                                 339     int pipes[2];
351                                                   340 
352     pipe(pipes);                                  341     pipe(pipes);
353     /* input data in iov */                       342     /* input data in iov */
354     vmsplice(pipes[1], iov, iovlen, SPLICE_F_G    343     vmsplice(pipes[1], iov, iovlen, SPLICE_F_GIFT);
355     /* opfd is the file descriptor returned fr    344     /* opfd is the file descriptor returned from accept() system call */
356     splice(pipes[0], NULL, opfd, NULL, ret, 0)    345     splice(pipes[0], NULL, opfd, NULL, ret, 0);
357     read(opfd, out, outlen);                      346     read(opfd, out, outlen);
358                                                   347 
359                                                   348 
360 Setsockopt Interface                              349 Setsockopt Interface
361 --------------------                              350 --------------------
362                                                   351 
363 In addition to the read/recv and send/write sy    352 In addition to the read/recv and send/write system call handling to send
364 and retrieve data subject to the cipher operat    353 and retrieve data subject to the cipher operation, a consumer also needs
365 to set the additional information for the ciph    354 to set the additional information for the cipher operation. This
366 additional information is set using the setsoc    355 additional information is set using the setsockopt system call that must
367 be invoked with the file descriptor of the ope    356 be invoked with the file descriptor of the open cipher (i.e. the file
368 descriptor returned by the accept system call)    357 descriptor returned by the accept system call).
369                                                   358 
370 Each setsockopt invocation must use the level     359 Each setsockopt invocation must use the level SOL_ALG.
371                                                   360 
372 The setsockopt interface allows setting the fo    361 The setsockopt interface allows setting the following data using the
373 mentioned optname:                                362 mentioned optname:
374                                                   363 
375 -  ALG_SET_KEY -- Setting the key. Key setting    364 -  ALG_SET_KEY -- Setting the key. Key setting is applicable to:
376                                                   365 
377    -  the skcipher cipher type (symmetric ciph    366    -  the skcipher cipher type (symmetric ciphers)
378                                                   367 
379    -  the hash cipher type (keyed message dige    368    -  the hash cipher type (keyed message digests)
380                                                   369 
381    -  the AEAD cipher type                        370    -  the AEAD cipher type
382                                                   371 
383    -  the RNG cipher type to provide the seed     372    -  the RNG cipher type to provide the seed
384                                                   373 
385 - ALG_SET_KEY_BY_KEY_SERIAL -- Setting the key << 
386    This operation behaves the same as ALG_SET_ << 
387    data is copied from a keyring key, and uses << 
388    key for symmetric encryption.               << 
389                                                << 
390    The passed in key_serial_t must have the KE << 
391    permission set, otherwise -EPERM is returne << 
392    logon, encrypted, and trusted.              << 
393                                                << 
394 -  ALG_SET_AEAD_AUTHSIZE -- Setting the authen    374 -  ALG_SET_AEAD_AUTHSIZE -- Setting the authentication tag size for
395    AEAD ciphers. For a encryption operation, t    375    AEAD ciphers. For a encryption operation, the authentication tag of
396    the given size will be generated. For a dec    376    the given size will be generated. For a decryption operation, the
397    provided ciphertext is assumed to contain a    377    provided ciphertext is assumed to contain an authentication tag of
398    the given size (see section about AEAD memo    378    the given size (see section about AEAD memory layout below).
399                                                   379 
400 -  ALG_SET_DRBG_ENTROPY -- Setting the entropy << 
401    This option is applicable to RNG cipher typ << 
402                                                << 
403 User space API example                            380 User space API example
404 ----------------------                            381 ----------------------
405                                                   382 
406 Please see [1] for libkcapi which provides an     383 Please see [1] for libkcapi which provides an easy-to-use wrapper around
407 the aforementioned Netlink kernel interface. [    384 the aforementioned Netlink kernel interface. [1] also contains a test
408 application that invokes all libkcapi API call    385 application that invokes all libkcapi API calls.
409                                                   386 
410 [1] https://www.chronox.de/libkcapi.html       !! 387 [1] http://www.chronox.de/libkcapi.html
                                                      

~ [ source navigation ] ~ [ diff markup ] ~ [ identifier search ] ~

kernel.org | git.kernel.org | LWN.net | Project Home | SVN repository | Mail admin

Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.

sflogo.php