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_freereq "struct cryptop *crp"
45 .Ft "struct cryptop *"
46 .Fn crypto_getreq "crypto_session_t cses" "int how"
48 Each symmetric cryptographic operation in the kernel is described by
51 and is associated with an active session.
53 New requests are allocated by
56 is a reference to an active session.
60 and should be set to either
64 The caller should then set fields in the returned structure to describe
65 request-specific parameters.
66 Unused fields should be left as-is.
69 passes a crypto request to the driver attached to the request's session.
70 If there are errors in the request's fields, this function may return
71 an error to the caller.
72 If errors are encountered while servicing the request, they will instead
73 be reported to the request's callback function
78 Note that a request's callback function may be invoked before
82 Once a request has signaled completion by invoking its callback function,
86 Cryptographic operations include several fields to describe the request.
88 Requests are associated with a single data buffer that is modified in place.
89 The type of the data buffer and the buffer itself are described by the
91 .Bl -tag -width crp_buf_type
93 The type of the data buffer.
94 The following types are supported:
95 .Bl -tag -width CRYPTO_BUF_CONTIG
96 .It Dv CRYPTO_BUF_CONTIG
97 An array of bytes mapped into the kernel's address space.
99 A scatter/gather list of kernel buffers as described in
101 .It Dv CRYPTO_BUF_MBUF
102 A network memory buffer as described in
106 A pointer to the start of a
107 .Dv CRYPTO_BUF_CONTIG
111 .Dv CRYPTO_BUF_CONTIG
117 .Dv CRYPTO_BUF_MBUF .
124 Used with compression and decompression requests to describe the updated
125 length of the payload region in the data buffer.
127 If a compression request increases the size of the payload,
128 then the data buffer is unmodified, the request completes successfully,
131 is set to the size the compressed data would have used.
132 Callers can compare this to the payload region length to determine if
133 the compressed data was discarded.
136 Each request describes one or more regions in the data buffer using.
137 Each region is described by an offset relative to the start of the
138 data buffer and a length.
139 The length of some regions is the same for all requests belonging to
141 Those lengths are set in the session parameters of the associated
143 All requests must define a payload region.
144 Other regions are only required for specific session modes.
145 The following regions are defined:
146 .Bl -column "Payload" "crp_payload_start" "crp_payload_length"
147 .It Sy Region Ta Sy Start Ta Sy Length Ta Sy Description
148 .It AAD Ta Fa crp_aad_start Ta Fa crp_aad_length Ta
149 Additional Authenticated Data
150 .It IV Ta Fa crp_iv_start Ta Fa csp_ivlen Ta
152 .It Payload Ta Fa crp_payload_start Ta Fa crp_payload_length Ta
153 Data to encrypt, decrypt, compress, or decompress
154 .It Digest Ta Fa crp_digest_start Ta Fa csp_auth_mlen Ta
155 Authentication digest, hash, or tag
158 Requests are permitted to operate on only a subset of the data buffer.
160 requests from IPsec operate on network packets that include headers not
161 used as either additional authentication data (AAD) or payload data.
162 .Ss Request Operations
163 All requests must specify the type of operation to perform in
165 Available operations depend on the session's mode.
167 Compression requests support the following operations:
168 .Bl -tag -width CRYPTO_OP_DECOMPRESS
169 .It Dv CRYPTO_OP_COMPRESS
170 Compress the data in the payload region of the data buffer.
171 .It Dv CRYPTO_OP_DECOMPRESS
172 Decompress the data in the payload region of the data buffer.
175 Cipher requests support the following operations:
176 .Bl -tag -width CRYPTO_OP_DECRYPT
177 .It Dv CRYPTO_OP_ENCRYPT
178 Encrypt the data in the payload region of the data buffer.
179 .It Dv CRYPTO_OP_DECRYPT
180 Decrypt the data in the payload region of the data buffer.
183 Digest requests support the following operations:
184 .Bl -tag -width CRYPTO_OP_COMPUTE_DIGEST
185 .It Dv CRYPTO_OP_COMPUTE_DIGEST
186 Calculate a digest over the payload region of the data buffer
187 and store the result in the digest region.
188 .It Dv CRYPTO_OP_VERIFY_DIGEST
189 Calculate a digest over the payload region of the data buffer.
190 Compare the calculated digest to the existing digest from the digest region.
191 If the digests match,
192 complete the request successfully.
193 If the digests do not match,
194 fail the request with
198 AEAD and Encrypt-then-Authenticate requests support the following
200 .Bl -tag -width CRYPTO_OP
201 .It Dv CRYPTO_OP_ENCRYPT | Dv CRYPTO_OP_COMPUTE_DIGEST
202 Encrypt the data in the payload region of the data buffer.
203 Calculate a digest over the AAD and payload regions and store the
204 result in the data buffer.
205 .It Dv CRYPTO_OP_DECRYPT | Dv CRYPTO_OP_VERIFY_DIGEST
206 Calculate a digest over the AAD and payload regions of the data buffer.
207 Compare the calculated digest to the existing digest from the digest region.
208 If the digests match,
209 decrypt the payload region.
210 If the digests do not match,
211 fail the request with
214 .Ss Request IV and/or Nonce
215 Some cryptographic operations require an IV or nonce as an input.
216 An IV may be stored either in the IV region of the data buffer or in
219 the IV is assumed to be stored in the IV region.
220 If the IV is stored in
222 .Dv CRYPTO_F_IV_SEPARATE
227 should be left as zero.
229 Requests that store part, but not all, of the IV in the data buffer should
230 store the partial IV in the data buffer and pass the full IV separately in
232 .Ss Request and Callback Scheduling
233 The crypto framework provides multiple methods of scheduling the dispatch
234 of requests to drivers along with the processing of driver callbacks.
235 Requests use flags in
237 to select the desired scheduling methods.
240 can pass the request to the session's driver via three different methods:
243 The request is queued to a taskqueue backed by a pool of worker threads.
244 By default the pool is sized to provide one thread for each CPU.
245 Worker threads dequeue requests and pass them to the driver
248 The request is passed to the driver synchronously in the context of the
250 .Fn crypto_dispatch .
252 The request is queued to a queue of pending requests.
253 A single worker thread dequeues requests and passes them to the driver
257 To select the first method (taskqueue backed by multiple threads),
260 To always use the third method (queue to single worker thread),
263 If both flags are set,
266 If neither flag is set,
268 will first attempt the second method (invoke driver synchronously).
269 If the driver is blocked,
270 the request will be queued using the third method.
271 One caveat is that the first method is only used for requests using software
272 drivers which use host CPUs to process requests.
273 Requests whose session is associated with a hardware driver will ignore
277 to determine how requests should be scheduled.
279 In addition to bypassing synchronous dispatch in
280 .Fn crypto_dispatch ,
282 requests additional changes aimed at optimizing batches of requests to
284 When the worker thread processes a request with
286 it will search the pending request queue for any other requests for the same
288 including requests from different sessions.
289 If any other requests are present,
291 is passed to the driver's process method.
292 Drivers may use this to batch completion interrupts.
294 Callback function scheduling is simpler than request scheduling.
295 Callbacks can either be invoked synchronously from
297 or they can be queued to a pool of worker threads.
298 This pool of worker threads is also sized to provide one worker thread
299 for each CPU by default.
300 Note that a callback function invoked synchronously from
302 must follow the same restrictions placed on threaded interrupt handlers.
305 callbacks are invoked asynchronously by a worker thread.
309 the callback is always invoked synchronously from
312 .Dv CRYPTO_F_CBIFSYNC
314 the callback is invoked synchronously if the request was processed by a
315 software driver or asynchronously if the request was processed by a
318 If a request was scheduled to the taskqueue via
320 callbacks are always invoked asynchronously ignoring
323 .Dv CRYPTO_F_CBIFSYNC .
325 .Dv CRYPTO_F_ASYNC_KEEPORDER
326 may be set to ensure that callbacks for requests on a given session are
327 invoked in the same order that requests were queued to the session via
328 .Fn crypto_dispatch .
329 This flag is used by IPsec to ensure that decrypted network packets are
330 passed up the network stack in roughly the same order they were received.
332 .Ss Other Request Fields
333 In addition to the fields and flags enumerated above,
335 includes the following:
336 .Bl -tag -width crp_payload_length
338 A reference to the active session.
339 This is set when the request is created by
341 and should not be modified.
342 Drivers can use this to fetch driver-specific session state or
346 Either zero on success, or an error if a request fails.
347 Set by drivers prior to completing a request via
351 The following flags are available in addition to flags discussed previously:
352 .Bl -tag -width CRYPTO_F_DONE
358 This flag is not very useful and will likely be removed in the future.
359 It can only be safely checked from the callback routine at which point
362 .It Fa crp_cipher_key
363 Pointer to a request-specific encryption key.
364 If this value is not set,
365 the request uses the session encryption key.
367 Pointer to a request-specific authentication key.
368 If this value is not set,
369 the request uses the session authentication key.
372 This pointer permits users of the cryptographic framework to store
373 information about a request to be used in the callback.
376 This must point to a callback function of type
377 .Vt void (*)(struct cryptop *) .
378 The callback function should inspect
380 to determine the status of the completed operation.
381 It should also arrange for the request to be freed via
386 returns an error if the request contained invalid fields,
387 or zero if the request was valid.
389 returns a pointer to a new request structure on success,
394 can only be returned if
402 .Xr crypto_session 9 ,
406 Not all drivers properly handle mixing session and per-request keys
407 within a single session.
408 Consumers should either use a single key for a session specified in
409 the session parameters or always use per-request keys.