1 .\" Copyright (c) 2020, Chelsio Inc
3 .\" Redistribution and use in source and binary forms, with or without
4 .\" modification, are permitted provided that the following conditions are met:
6 .\" 1. Redistributions of source code must retain the above copyright notice,
7 .\" this list of conditions and the following disclaimer.
9 .\" 2. Redistributions in binary form must reproduce the above copyright
10 .\" notice, this list of conditions and the following disclaimer in the
11 .\" documentation and/or other materials provided with the distribution.
13 .\" 3. Neither the name of the Chelsio Inc nor the names of its
14 .\" contributors may be used to endorse or promote products derived from
15 .\" this software without specific prior written permission.
17 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
18 .\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
19 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
20 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
21 .\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
22 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
23 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
24 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
25 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
26 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
27 .\" POSSIBILITY OF SUCH DAMAGE.
29 .\" * Other names and brands may be claimed as the property of others.
38 .Nd symmetric cryptographic operations
40 .In opencrypto/cryptodev.h
42 .Fn crypto_dispatch "struct cryptop *crp"
44 .Fn crypto_destroyreq "struct cryptop *crp"
46 .Fn crypto_freereq "struct cryptop *crp"
47 .Ft "struct cryptop *"
48 .Fn crypto_getreq "crypto_session_t cses" "int how"
50 .Fn crypto_initreq "crypto_session_t cses" "int how"
52 .Fn crypto_use_buf "struct cryptop *crp" "void *buf" "int len"
54 .Fn crypto_use_mbuf "struct cryptop *crp" "struct mbuf *m"
56 .Fn crypto_use_uio "struct cryptop *crp" "struct uio *uio"
58 .Fn crypto_use_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset"
60 .Fn crypto_use_output_buf "struct cryptop *crp" "void *buf" "int len"
62 .Fn crypto_use_output_mbuf "struct cryptop *crp" "struct mbuf *m"
64 .Fn crypto_use_output_uio "struct cryptop *crp" "struct uio *uio"
66 .Fn crypto_use_output_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset"
68 Each symmetric cryptographic operation in the kernel is described by
71 and is associated with an active session.
73 Requests can either be allocated dynamically or use caller-supplied
75 Dynamically allocated requests should be allocated by
79 once the request has completed.
80 Requests using caller-supplied storage should be initialized by
82 at the start of each operation and destroyed by
84 once the request has completed.
91 is a reference to an active session.
97 and should be set to either
102 Once a request has been initialized,
103 the caller should set fields in the structure to describe
104 request-specific parameters.
105 Unused fields should be left as-is.
108 passes a crypto request to the driver attached to the request's session.
109 If there are errors in the request's fields, this function may return
110 an error to the caller.
111 If errors are encountered while servicing the request, they will instead
112 be reported to the request's callback function
117 Note that a request's callback function may be invoked before
121 Once a request has signaled completion by invoking its callback function,
122 it should be freed via
123 .Fn crypto_destroyreq
127 Cryptographic operations include several fields to describe the request.
129 Requests can either specify a single data buffer that is modified in place
142 Note that separate input and output buffers are not supported for compression
145 All requests must have a valid
147 initialized by one of the following functions:
148 .Bl -tag -width "Fn crypto_use_vmpage"
149 .It Fn crypto_use_buf
155 .It Fn crypto_use_mbuf
156 Uses the network memory buffer
159 .It Fn crypto_use_uio
160 Uses the scatter/gather list
163 .It Fn crypto_use_vmpage
166 structures as the data buffer.
169 One of the following functions should be used to initialize
171 for requests that use separate input and output buffers:
172 .Bl -tag -width "Fn crypto_use_output_vmpage"
173 .It Fn crypto_use_output_buf
178 as the output buffer.
179 .It Fn crypto_use_output_mbuf
180 Uses the network memory buffer
182 as the output buffer.
183 .It Fn crypto_use_output_uio
184 Uses the scatter/gather list
186 as the output buffer.
187 .It Fn crypto_use_output_vmpage
190 structures as the output buffer.
193 Each request describes one or more regions in the data buffers.
194 Each region is described by an offset relative to the start of a
195 data buffer and a length.
196 The length of some regions is the same for all requests belonging to
198 Those lengths are set in the session parameters of the associated
200 All requests must define a payload region.
201 Other regions are only required for specific session modes.
203 For requests with separate input and output data buffers,
204 the AAD, IV, and payload regions are always defined as regions in the
206 and a separate payload output region is defined to hold the output of
207 encryption or decryption in the output buffer.
208 The digest region describes a region in the input data buffer for
209 requests that verify an existing digest.
210 For requests that compute a digest,
211 the digest region describes a region in the output data buffer.
212 Note that the only data written to the output buffer is the encryption
213 or decryption result and any computed digest.
214 AAD and IV regions are not copied from the input buffer into the output
215 buffer but are only used as inputs.
217 The following regions are defined:
218 .Bl -column "Payload Output" "Input/Output"
219 .It Sy Region Ta Sy Buffer Ta Sy Description
221 Embedded Additional Authenticated Data
224 .It Payload Ta Input Ta
225 Data to encrypt, decrypt, compress, or decompress
226 .It Payload Output Ta Output Ta
227 Encrypted or decrypted data
228 .It Digest Ta Input/Output Ta
229 Authentication digest, hash, or tag
231 .Bl -column "Payload Output" ".Fa crp_payload_output_start"
232 .It Sy Region Ta Sy Start Ta Sy Length
233 .It AAD Ta Fa crp_aad_start Ta Fa crp_aad_length
234 .It IV Ta Fa crp_iv_start Ta Fa csp_ivlen
235 .It Payload Ta Fa crp_payload_start Ta Fa crp_payload_length
236 .It Payload Output Ta Fa crp_payload_output_start Ta Fa crp_payload_length
237 .It Digest Ta Fa crp_digest_start Ta Fa csp_auth_mlen
240 Requests are permitted to operate on only a subset of the data buffer.
242 requests from IPsec operate on network packets that include headers not
243 used as either additional authentication data (AAD) or payload data.
244 .Ss Request Operations
245 All requests must specify the type of operation to perform in
247 Available operations depend on the session's mode.
249 Compression requests support the following operations:
250 .Bl -tag -width CRYPTO_OP_DECOMPRESS
251 .It Dv CRYPTO_OP_COMPRESS
252 Compress the data in the payload region of the data buffer.
253 .It Dv CRYPTO_OP_DECOMPRESS
254 Decompress the data in the payload region of the data buffer.
257 Cipher requests support the following operations:
258 .Bl -tag -width CRYPTO_OP_DECRYPT
259 .It Dv CRYPTO_OP_ENCRYPT
260 Encrypt the data in the payload region of the data buffer.
261 .It Dv CRYPTO_OP_DECRYPT
262 Decrypt the data in the payload region of the data buffer.
265 Digest requests support the following operations:
266 .Bl -tag -width CRYPTO_OP_COMPUTE_DIGEST
267 .It Dv CRYPTO_OP_COMPUTE_DIGEST
268 Calculate a digest over the payload region of the data buffer
269 and store the result in the digest region.
270 .It Dv CRYPTO_OP_VERIFY_DIGEST
271 Calculate a digest over the payload region of the data buffer.
272 Compare the calculated digest to the existing digest from the digest region.
273 If the digests match,
274 complete the request successfully.
275 If the digests do not match,
276 fail the request with
280 AEAD and Encrypt-then-Authenticate requests support the following
282 .Bl -tag -width CRYPTO_OP
283 .It Dv CRYPTO_OP_ENCRYPT | Dv CRYPTO_OP_COMPUTE_DIGEST
284 Encrypt the data in the payload region of the data buffer.
285 Calculate a digest over the AAD and payload regions and store the
286 result in the data buffer.
287 .It Dv CRYPTO_OP_DECRYPT | Dv CRYPTO_OP_VERIFY_DIGEST
288 Calculate a digest over the AAD and payload regions of the data buffer.
289 Compare the calculated digest to the existing digest from the digest region.
290 If the digests match,
291 decrypt the payload region.
292 If the digests do not match,
293 fail the request with
297 AEAD and Encrypt-then-Authenticate requests may optionally include
298 Additional Authenticated Data.
299 AAD may either be supplied in the AAD region of the input buffer or
300 as a single buffer pointed to by
304 always indicates the amount of AAD in bytes.
305 .Ss Request IV and/or Nonce
306 Some cryptographic operations require an IV or nonce as an input.
307 An IV may be stored either in the IV region of the data buffer or in
310 the IV is assumed to be stored in the IV region.
311 If the IV is stored in
313 .Dv CRYPTO_F_IV_SEPARATE
318 should be left as zero.
320 Requests that store part, but not all, of the IV in the data buffer should
321 store the partial IV in the data buffer and pass the full IV separately in
323 .Ss Request and Callback Scheduling
324 The crypto framework provides multiple methods of scheduling the dispatch
325 of requests to drivers along with the processing of driver callbacks.
326 Requests use flags in
328 to select the desired scheduling methods.
331 can pass the request to the session's driver via three different methods:
334 The request is queued to a taskqueue backed by a pool of worker threads.
335 By default the pool is sized to provide one thread for each CPU.
336 Worker threads dequeue requests and pass them to the driver
339 The request is passed to the driver synchronously in the context of the
341 .Fn crypto_dispatch .
343 The request is queued to a queue of pending requests.
344 A single worker thread dequeues requests and passes them to the driver
348 To select the first method (taskqueue backed by multiple threads),
351 To always use the third method (queue to single worker thread),
354 If both flags are set,
357 If neither flag is set,
359 will first attempt the second method (invoke driver synchronously).
360 If the driver is blocked,
361 the request will be queued using the third method.
362 One caveat is that the first method is only used for requests using software
363 drivers which use host CPUs to process requests.
364 Requests whose session is associated with a hardware driver will ignore
368 to determine how requests should be scheduled.
370 In addition to bypassing synchronous dispatch in
371 .Fn crypto_dispatch ,
373 requests additional changes aimed at optimizing batches of requests to
375 When the worker thread processes a request with
377 it will search the pending request queue for any other requests for the same
379 including requests from different sessions.
380 If any other requests are present,
382 is passed to the driver's process method.
383 Drivers may use this to batch completion interrupts.
385 Callback function scheduling is simpler than request scheduling.
386 Callbacks can either be invoked synchronously from
388 or they can be queued to a pool of worker threads.
389 This pool of worker threads is also sized to provide one worker thread
390 for each CPU by default.
391 Note that a callback function invoked synchronously from
393 must follow the same restrictions placed on threaded interrupt handlers.
396 callbacks are invoked asynchronously by a worker thread.
400 the callback is always invoked synchronously from
403 .Dv CRYPTO_F_CBIFSYNC
405 the callback is invoked synchronously if the request was processed by a
406 software driver or asynchronously if the request was processed by a
409 If a request was scheduled to the taskqueue via
411 callbacks are always invoked asynchronously ignoring
414 .Dv CRYPTO_F_CBIFSYNC .
416 .Dv CRYPTO_F_ASYNC_KEEPORDER
417 may be set to ensure that callbacks for requests on a given session are
418 invoked in the same order that requests were queued to the session via
419 .Fn crypto_dispatch .
420 This flag is used by IPsec to ensure that decrypted network packets are
421 passed up the network stack in roughly the same order they were received.
423 .Ss Other Request Fields
424 In addition to the fields and flags enumerated above,
426 includes the following:
427 .Bl -tag -width crp_payload_length
429 A reference to the active session.
430 This is set when the request is created by
432 and should not be modified.
433 Drivers can use this to fetch driver-specific session state or
437 Either zero on success, or an error if a request fails.
438 Set by drivers prior to completing a request via
442 The following flags are available in addition to flags discussed previously:
443 .Bl -tag -width CRYPTO_F_DONE
449 This flag is not very useful and will likely be removed in the future.
450 It can only be safely checked from the callback routine at which point
453 .It Fa crp_cipher_key
454 Pointer to a request-specific encryption key.
455 If this value is not set,
456 the request uses the session encryption key.
458 Pointer to a request-specific authentication key.
459 If this value is not set,
460 the request uses the session authentication key.
463 This pointer permits users of the cryptographic framework to store
464 information about a request to be used in the callback.
467 This must point to a callback function of type
468 .Vt void (*)(struct cryptop *) .
469 The callback function should inspect
471 to determine the status of the completed operation.
472 It should also arrange for the request to be freed via
475 Used with compression and decompression requests to describe the updated
476 length of the payload region in the data buffer.
478 If a compression request increases the size of the payload,
479 then the data buffer is unmodified, the request completes successfully,
482 is set to the size the compressed data would have used.
483 Callers can compare this to the payload region length to determine if
484 the compressed data was discarded.
488 returns an error if the request contained invalid fields,
489 or zero if the request was valid.
491 returns a pointer to a new request structure on success,
496 can only be returned if
504 .Xr crypto_session 9 ,
508 Not all drivers properly handle mixing session and per-request keys
509 within a single session.
510 Consumers should either use a single key for a session specified in
511 the session parameters or always use per-request keys.