xref: /freebsd/share/man/man9/crypto_request.9 (revision c66ec88fed842fbaad62c30d510644ceb7bd2d71)
1.\" Copyright (c) 2020, Chelsio Inc
2.\"
3.\" Redistribution and use in source and binary forms, with or without
4.\" modification, are permitted provided that the following conditions are met:
5.\"
6.\" 1. Redistributions of source code must retain the above copyright notice,
7.\"    this list of conditions and the following disclaimer.
8.\"
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.
12.\"
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.
16.\"
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.
28.\"
29.\" * Other names and brands may be claimed as the property of others.
30.\"
31.\" $FreeBSD$
32.\"
33.Dd August 12, 2020
34.Dt CRYPTO_REQUEST 9
35.Os
36.Sh NAME
37.Nm crypto_request
38.Nd symmetric cryptographic operations
39.Sh SYNOPSIS
40.In opencrypto/cryptodev.h
41.Ft int
42.Fn crypto_dispatch "struct cryptop *crp"
43.Ft void
44.Fn crypto_destroyreq "struct cryptop *crp"
45.Ft void
46.Fn crypto_freereq "struct cryptop *crp"
47.Ft "struct cryptop *"
48.Fn crypto_getreq "crypto_session_t cses" "int how"
49.Ft void
50.Fn crypto_initreq "crypto_session_t cses" "int how"
51.Ft void
52.Fn crypto_use_buf "struct cryptop *crp" "void *buf" "int len"
53.Ft void
54.Fn crypto_use_mbuf "struct cryptop *crp" "struct mbuf *m"
55.Ft void
56.Fn crypto_use_uio "struct cryptop *crp" "struct uio *uio"
57.Ft void
58.Fn crypto_use_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset"
59.Ft void
60.Fn crypto_use_output_buf "struct cryptop *crp" "void *buf" "int len"
61.Ft void
62.Fn crypto_use_output_mbuf "struct cryptop *crp" "struct mbuf *m"
63.Ft void
64.Fn crypto_use_output_uio "struct cryptop *crp" "struct uio *uio"
65.Ft void
66.Fn crypto_use_output_vmpage "struct cryptop *crp" "vm_page_t *pages" "int len" "int offset"
67.Sh DESCRIPTION
68Each symmetric cryptographic operation in the kernel is described by
69an instance of
70.Vt struct cryptop
71and is associated with an active session.
72.Pp
73Requests can either be allocated dynamically or use caller-supplied
74storage.
75Dynamically allocated requests should be allocated by
76.Fn crypto_getreq
77and freed by
78.Fn crypto_freereq
79once the request has completed.
80Requests using caller-supplied storage should be initialized by
81.Fn crypto_initreq
82at the start of each operation and destroyed by
83.Fn crypto_destroyreq
84once the request has completed.
85.Pp
86For both
87.Fn crypto_getreq
88and
89.Fn crypto_initreq ,
90.Fa cses
91is a reference to an active session.
92For
93.Fn crypto_getreq ,
94.Fa how
95is passed to
96.Xr malloc 9
97and should be set to either
98.Dv M_NOWAIT
99or
100.Dv M_WAITOK .
101.Pp
102Once a request has been initialized,
103the caller should set fields in the structure to describe
104request-specific parameters.
105Unused fields should be left as-is.
106.Pp
107.Fn crypto_dispatch
108passes a crypto request to the driver attached to the request's session.
109If there are errors in the request's fields, this function may return
110an error to the caller.
111If errors are encountered while servicing the request, they will instead
112be reported to the request's callback function
113.Pq Fa crp_callback
114via
115.Fa crp_etype .
116.Pp
117Note that a request's callback function may be invoked before
118.Fn crypto_dispatch
119returns.
120.Pp
121Once a request has signaled completion by invoking its callback function,
122it should be freed via
123.Fn crypto_destroyreq
124or
125.Fn crypto_freereq .
126.Pp
127Cryptographic operations include several fields to describe the request.
128.Ss Request Buffers
129Requests can either specify a single data buffer that is modified in place
130.Po
131.Fa crp_buf
132.Pc
133or separate input
134.Po
135.Fa crp_buf
136.Pc
137and output
138.Po
139.Fa crp_obuf
140.Pc
141buffers.
142Note that separate input and output buffers are not supported for compression
143mode requests.
144.Pp
145All requests must have a valid
146.Fa crp_buf
147initialized by one of the following functions:
148.Bl -tag -width "Fn crypto_use_vmpage"
149.It Fn crypto_use_buf
150Uses an array of
151.Fa len
152bytes pointed to by
153.Fa buf
154as the data buffer.
155.It Fn crypto_use_mbuf
156Uses the network memory buffer
157.Fa m
158as the data buffer.
159.It Fn crypto_use_uio
160Uses the scatter/gather list
161.Fa uio
162as the data buffer.
163.It Fn crypto_use_vmpage
164Uses the array of
165.Vt vm_page_t
166structures as the data buffer.
167.El
168.Pp
169One of the following functions should be used to initialize
170.Fa crp_obuf
171for requests that use separate input and output buffers:
172.Bl -tag -width "Fn crypto_use_output_vmpage"
173.It Fn crypto_use_output_buf
174Uses an array of
175.Fa len
176bytes pointed to by
177.Fa buf
178as the output buffer.
179.It Fn crypto_use_output_mbuf
180Uses the network memory buffer
181.Fa m
182as the output buffer.
183.It Fn crypto_use_output_uio
184Uses the scatter/gather list
185.Fa uio
186as the output buffer.
187.It Fn crypto_use_output_vmpage
188Uses the array of
189.Vt vm_page_t
190structures as the output buffer.
191.El
192.Ss Request Regions
193Each request describes one or more regions in the data buffers.
194Each region is described by an offset relative to the start of a
195data buffer and a length.
196The length of some regions is the same for all requests belonging to
197a session.
198Those lengths are set in the session parameters of the associated
199session.
200All requests must define a payload region.
201Other regions are only required for specific session modes.
202.Pp
203For requests with separate input and output data buffers,
204the AAD, IV, and payload regions are always defined as regions in the
205input buffer,
206and a separate payload output region is defined to hold the output of
207encryption or decryption in the output buffer.
208The digest region describes a region in the input data buffer for
209requests that verify an existing digest.
210For requests that compute a digest,
211the digest region describes a region in the output data buffer.
212Note that the only data written to the output buffer is the encryption
213or decryption result and any computed digest.
214AAD and IV regions are not copied from the input buffer into the output
215buffer but are only used as inputs.
216.Pp
217The following regions are defined:
218.Bl -column "Payload Output" "Input/Output"
219.It Sy Region Ta Sy Buffer Ta Sy Description
220.It AAD Ta Input Ta
221Embedded Additional Authenticated Data
222.It IV Ta Input Ta
223Embedded IV or nonce
224.It Payload Ta Input Ta
225Data to encrypt, decrypt, compress, or decompress
226.It Payload Output Ta Output Ta
227Encrypted or decrypted data
228.It Digest Ta Input/Output Ta
229Authentication digest, hash, or tag
230.El
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
238.El
239.Pp
240Requests are permitted to operate on only a subset of the data buffer.
241For example,
242requests from IPsec operate on network packets that include headers not
243used as either additional authentication data (AAD) or payload data.
244.Ss Request Operations
245All requests must specify the type of operation to perform in
246.Fa crp_op .
247Available operations depend on the session's mode.
248.Pp
249Compression requests support the following operations:
250.Bl -tag -width CRYPTO_OP_DECOMPRESS
251.It Dv CRYPTO_OP_COMPRESS
252Compress the data in the payload region of the data buffer.
253.It Dv CRYPTO_OP_DECOMPRESS
254Decompress the data in the payload region of the data buffer.
255.El
256.Pp
257Cipher requests support the following operations:
258.Bl -tag -width CRYPTO_OP_DECRYPT
259.It Dv CRYPTO_OP_ENCRYPT
260Encrypt the data in the payload region of the data buffer.
261.It Dv CRYPTO_OP_DECRYPT
262Decrypt the data in the payload region of the data buffer.
263.El
264.Pp
265Digest requests support the following operations:
266.Bl -tag -width CRYPTO_OP_COMPUTE_DIGEST
267.It Dv CRYPTO_OP_COMPUTE_DIGEST
268Calculate a digest over the payload region of the data buffer
269and store the result in the digest region.
270.It Dv CRYPTO_OP_VERIFY_DIGEST
271Calculate a digest over the payload region of the data buffer.
272Compare the calculated digest to the existing digest from the digest region.
273If the digests match,
274complete the request successfully.
275If the digests do not match,
276fail the request with
277.Er EBADMSG .
278.El
279.Pp
280AEAD and Encrypt-then-Authenticate requests support the following
281operations:
282.Bl -tag -width CRYPTO_OP
283.It Dv CRYPTO_OP_ENCRYPT | Dv CRYPTO_OP_COMPUTE_DIGEST
284Encrypt the data in the payload region of the data buffer.
285Calculate a digest over the AAD and payload regions and store the
286result in the data buffer.
287.It Dv CRYPTO_OP_DECRYPT | Dv CRYPTO_OP_VERIFY_DIGEST
288Calculate a digest over the AAD and payload regions of the data buffer.
289Compare the calculated digest to the existing digest from the digest region.
290If the digests match,
291decrypt the payload region.
292If the digests do not match,
293fail the request with
294.Er EBADMSG .
295.El
296.Ss Request AAD
297AEAD and Encrypt-then-Authenticate requests may optionally include
298Additional Authenticated Data.
299AAD may either be supplied in the AAD region of the input buffer or
300as a single buffer pointed to by
301.Fa crp_aad .
302In either case,
303.Fa crp_aad_length
304always indicates the amount of AAD in bytes.
305.Ss Request ESN
306IPsec requests may optionally include Extended Sequence Numbers (ESN).
307ESN may either be supplied in
308.Fa crp_esn
309or as part of the AAD pointed to by
310.Fa crp_aad .
311.Pp
312If the ESN is stored in
313.Fa crp_esn ,
314.Dv CSP_F_ESN
315should be set in
316.Fa csp_flags .
317This use case is dedicated for encrypt and authenticate mode, since the
318high-order 32 bits of the sequence number are appended after the Next Header
319(RFC 4303).
320.Pp
321AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5
322AAD Construction).
323.Ss Request IV and/or Nonce
324Some cryptographic operations require an IV or nonce as an input.
325An IV may be stored either in the IV region of the data buffer or in
326.Fa crp_iv .
327By default,
328the IV is assumed to be stored in the IV region.
329If the IV is stored in
330.Fa crp_iv ,
331.Dv CRYPTO_F_IV_SEPARATE
332should be set in
333.Fa crp_flags
334and
335.Fa crp_iv_start
336should be left as zero.
337.Pp
338Requests that store part, but not all, of the IV in the data buffer should
339store the partial IV in the data buffer and pass the full IV separately in
340.Fa crp_iv .
341.Ss Request and Callback Scheduling
342The crypto framework provides multiple methods of scheduling the dispatch
343of requests to drivers along with the processing of driver callbacks.
344Requests use flags in
345.Fa crp_flags
346to select the desired scheduling methods.
347.Pp
348.Fn crypto_dispatch
349can pass the request to the session's driver via three different methods:
350.Bl -enum
351.It
352The request is queued to a taskqueue backed by a pool of worker threads.
353By default the pool is sized to provide one thread for each CPU.
354Worker threads dequeue requests and pass them to the driver
355asynchronously.
356.It
357The request is passed to the driver synchronously in the context of the
358thread invoking
359.Fn crypto_dispatch .
360.It
361The request is queued to a queue of pending requests.
362A single worker thread dequeues requests and passes them to the driver
363asynchronously.
364.El
365.Pp
366To select the first method (taskqueue backed by multiple threads),
367requests should set
368.Dv CRYPTO_F_ASYNC .
369To always use the third method (queue to single worker thread),
370requests should set
371.Dv CRYPTO_F_BATCH .
372If both flags are set,
373.Dv CRYPTO_F_ASYNC
374takes precedence.
375If neither flag is set,
376.Fn crypto_dispatch
377will first attempt the second method (invoke driver synchronously).
378If the driver is blocked,
379the request will be queued using the third method.
380One caveat is that the first method is only used for requests using software
381drivers which use host CPUs to process requests.
382Requests whose session is associated with a hardware driver will ignore
383.Dv CRYPTO_F_ASYNC
384and only use
385.Dv CRYPTO_F_BATCH
386to determine how requests should be scheduled.
387.Pp
388In addition to bypassing synchronous dispatch in
389.Fn crypto_dispatch ,
390.Dv CRYPTO_F_BATCH
391requests additional changes aimed at optimizing batches of requests to
392the same driver.
393When the worker thread processes a request with
394.Dv CRYPTO_F_BATCH ,
395it will search the pending request queue for any other requests for the same
396driver,
397including requests from different sessions.
398If any other requests are present,
399.Dv CRYPTO_HINT_MORE
400is passed to the driver's process method.
401Drivers may use this to batch completion interrupts.
402.Pp
403Callback function scheduling is simpler than request scheduling.
404Callbacks can either be invoked synchronously from
405.Fn crypto_done ,
406or they can be queued to a pool of worker threads.
407This pool of worker threads is also sized to provide one worker thread
408for each CPU by default.
409Note that a callback function invoked synchronously from
410.Fn crypto_done
411must follow the same restrictions placed on threaded interrupt handlers.
412.Pp
413By default,
414callbacks are invoked asynchronously by a worker thread.
415If
416.Dv CRYPTO_F_CBIMM
417is set,
418the callback is always invoked synchronously from
419.Fn crypto_done .
420If
421.Dv CRYPTO_F_CBIFSYNC
422is set,
423the callback is invoked synchronously if the request was processed by a
424software driver or asynchronously if the request was processed by a
425hardware driver.
426.Pp
427If a request was scheduled to the taskqueue via
428.Dv CRYPTO_F_ASYNC ,
429callbacks are always invoked asynchronously ignoring
430.Dv CRYPTO_F_CBIMM
431and
432.Dv CRYPTO_F_CBIFSYNC .
433In this case,
434.Dv CRYPTO_F_ASYNC_KEEPORDER
435may be set to ensure that callbacks for requests on a given session are
436invoked in the same order that requests were queued to the session via
437.Fn crypto_dispatch .
438This flag is used by IPsec to ensure that decrypted network packets are
439passed up the network stack in roughly the same order they were received.
440.Pp
441.Ss Other Request Fields
442In addition to the fields and flags enumerated above,
443.Vt struct cryptop
444includes the following:
445.Bl -tag -width crp_payload_length
446.It Fa crp_session
447A reference to the active session.
448This is set when the request is created by
449.Fn crypto_getreq
450and should not be modified.
451Drivers can use this to fetch driver-specific session state or
452session parameters.
453.It Fa crp_etype
454Error status.
455Either zero on success, or an error if a request fails.
456Set by drivers prior to completing a request via
457.Fn crypto_done .
458.It Fa crp_flags
459A bitmask of flags.
460The following flags are available in addition to flags discussed previously:
461.Bl -tag -width CRYPTO_F_DONE
462.It Dv CRYPTO_F_DONE
463Set by
464.Fa crypto_done
465before calling
466.Fa crp_callback .
467This flag is not very useful and will likely be removed in the future.
468It can only be safely checked from the callback routine at which point
469it is always set.
470.El
471.It Fa crp_cipher_key
472Pointer to a request-specific encryption key.
473If this value is not set,
474the request uses the session encryption key.
475.It Fa crp_auth_key
476Pointer to a request-specific authentication key.
477If this value is not set,
478the request uses the session authentication key.
479.It Fa crp_opaque
480An opaque pointer.
481This pointer permits users of the cryptographic framework to store
482information about a request to be used in the callback.
483.It Fa crp_callback
484Callback function.
485This must point to a callback function of type
486.Vt void (*)(struct cryptop *) .
487The callback function should inspect
488.Fa crp_etype
489to determine the status of the completed operation.
490It should also arrange for the request to be freed via
491.Fn crypto_freereq .
492.It Fa crp_olen
493Used with compression and decompression requests to describe the updated
494length of the payload region in the data buffer.
495.Pp
496If a compression request increases the size of the payload,
497then the data buffer is unmodified, the request completes successfully,
498and
499.Fa crp_olen
500is set to the size the compressed data would have used.
501Callers can compare this to the payload region length to determine if
502the compressed data was discarded.
503.El
504.Sh RETURN VALUES
505.Fn crypto_dispatch
506returns an error if the request contained invalid fields,
507or zero if the request was valid.
508.Fn crypto_getreq
509returns a pointer to a new request structure on success,
510or
511.Dv NULL
512on failure.
513.Dv NULL
514can only be returned if
515.Dv M_NOWAIT
516was passed in
517.Fa how .
518.Sh SEE ALSO
519.Xr ipsec 4 ,
520.Xr crypto 7 ,
521.Xr crypto 9 ,
522.Xr crypto_session 9 ,
523.Xr mbuf 9
524.Xr uio 9
525.Sh BUGS
526Not all drivers properly handle mixing session and per-request keys
527within a single session.
528Consumers should either use a single key for a session specified in
529the session parameters or always use per-request keys.
530