share/man/man9/crypto_request.9

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