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 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
  68 Each symmetric cryptographic operation in the kernel is described by
  69 an instance of
  70 .Vt struct cryptop
  71 and is associated with an active session.
  72 .Pp
  73 Requests can either be allocated dynamically or use caller-supplied
  74 storage.
  75 Dynamically allocated requests should be allocated by
  76 .Fn crypto_getreq
  77 and freed by
  78 .Fn crypto_freereq
  79 once the request has completed.
  80 Requests using caller-supplied storage should be initialized by
  81 .Fn crypto_initreq
  82 at the start of each operation and destroyed by
  83 .Fn crypto_destroyreq
  84 once the request has completed.
  85 .Pp
  86 For both
  87 .Fn crypto_getreq
  88 and
  89 .Fn crypto_initreq ,
  90 .Fa cses
  91 is a reference to an active session.
  92 For
  93 .Fn crypto_getreq ,
  94 .Fa how
  95 is passed to
  96 .Xr malloc 9
  97 and should be set to either
  98 .Dv M_NOWAIT
  99 or
 100 .Dv M_WAITOK .
 101 .Pp
 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.
 106 .Pp
 107 .Fn crypto_dispatch
 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
 113 .Pq Fa crp_callback
 114 via
 115 .Fa crp_etype .
 116 .Pp
 117 Note that a request's callback function may be invoked before
 118 .Fn crypto_dispatch
 119 returns.
 120 .Pp
 121 Once a request has signaled completion by invoking its callback function,
 122 it should be freed via
 123 .Fn crypto_destroyreq
 124 or
 125 .Fn crypto_freereq .
 126 .Pp
 127 Cryptographic operations include several fields to describe the request.
 128 .Ss Request Buffers
 129 Requests can either specify a single data buffer that is modified in place
 130 .Po
 131 .Fa crp_buf
 132 .Pc
 133 or separate input
 134 .Po
 135 .Fa crp_buf
 136 .Pc
 137 and output
 138 .Po
 139 .Fa crp_obuf
 140 .Pc
 141 buffers.
 142 Note that separate input and output buffers are not supported for compression
 143 mode requests.
 144 .Pp
 145 All requests must have a valid
 146 .Fa crp_buf
 147 initialized by one of the following functions:
 148 .Bl -tag -width "Fn crypto_use_vmpage"
 149 .It Fn crypto_use_buf
 150 Uses an array of
 151 .Fa len
 152 bytes pointed to by
 153 .Fa buf
 154 as the data buffer.
 155 .It Fn crypto_use_mbuf
 156 Uses the network memory buffer
 157 .Fa m
 158 as the data buffer.
 159 .It Fn crypto_use_uio
 160 Uses the scatter/gather list
 161 .Fa uio
 162 as the data buffer.
 163 .It Fn crypto_use_vmpage
 164 Uses the array of
 165 .Vt vm_page_t
 166 structures as the data buffer.
 167 .El
 168 .Pp
 169 One of the following functions should be used to initialize
 170 .Fa crp_obuf
 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
 174 Uses an array of
 175 .Fa len
 176 bytes pointed to by
 177 .Fa buf
 178 as the output buffer.
 179 .It Fn crypto_use_output_mbuf
 180 Uses the network memory buffer
 181 .Fa m
 182 as the output buffer.
 183 .It Fn crypto_use_output_uio
 184 Uses the scatter/gather list
 185 .Fa uio
 186 as the output buffer.
 187 .It Fn crypto_use_output_vmpage
 188 Uses the array of
 189 .Vt vm_page_t
 190 structures as the output buffer.
 191 .El
 192 .Ss Request Regions
 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
 197 a session.
 198 Those lengths are set in the session parameters of the associated
 199 session.
 200 All requests must define a payload region.
 201 Other regions are only required for specific session modes.
 202 .Pp
 203 For requests with separate input and output data buffers,
 204 the AAD, IV, and payload regions are always defined as regions in the
 205 input buffer,
 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.
 216 .Pp
 217 The 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
 221 Embedded Additional Authenticated Data
 222 .It IV Ta Input Ta
 223 Embedded IV or nonce
 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
 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
 240 Requests are permitted to operate on only a subset of the data buffer.
 241 For example,
 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
 246 .Fa crp_op .
 247 Available operations depend on the session's mode.
 248 .Pp
 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.
 255 .El
 256 .Pp
 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.
 263 .El
 264 .Pp
 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
 277 .Er EBADMSG .
 278 .El
 279 .Pp
 280 AEAD and Encrypt-then-Authenticate requests support the following
 281 operations:
 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
 294 .Er EBADMSG .
 295 .El
 296 .Ss Request AAD
 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
 301 .Fa crp_aad .
 302 In either case,
 303 .Fa crp_aad_length
 304 always indicates the amount of AAD in bytes.
 305 .Ss Request ESN
 306 IPsec requests may optionally include Extended Sequence Numbers (ESN).
 307 ESN may either be supplied in
 308 .Fa crp_esn
 309 or as part of the AAD pointed to by
 310 .Fa crp_aad .
 311 .Pp
 312 If the ESN is stored in
 313 .Fa crp_esn ,
 314 .Dv CSP_F_ESN
 315 should be set in
 316 .Fa csp_flags .
 317 This use case is dedicated for encrypt and authenticate mode, since the
 318 high-order 32 bits of the sequence number are appended after the Next Header
 319 (RFC 4303).
 320 .Pp
 321 AEAD modes supply the ESN in a separate AAD buffer (see e.g. RFC 4106, Chapter 5
 322 AAD Construction).
 323 .Ss Request IV and/or Nonce
 324 Some cryptographic operations require an IV or nonce as an input.
 325 An IV may be stored either in the IV region of the data buffer or in
 326 .Fa crp_iv .
 327 By default,
 328 the IV is assumed to be stored in the IV region.
 329 If the IV is stored in
 330 .Fa crp_iv ,
 331 .Dv CRYPTO_F_IV_SEPARATE
 332 should be set in
 333 .Fa crp_flags
 334 and
 335 .Fa crp_iv_start
 336 should be left as zero.
 337 .Pp
 338 Requests that store part, but not all, of the IV in the data buffer should
 339 store the partial IV in the data buffer and pass the full IV separately in
 340 .Fa crp_iv .
 341 .Ss Request and Callback Scheduling
 342 The crypto framework provides multiple methods of scheduling the dispatch
 343 of requests to drivers along with the processing of driver callbacks.
 344 Requests use flags in
 345 .Fa crp_flags
 346 to select the desired scheduling methods.
 347 .Pp
 348 .Fn crypto_dispatch
 349 can pass the request to the session's driver via three different methods:
 350 .Bl -enum
 351 .It
 352 The request is queued to a taskqueue backed by a pool of worker threads.
 353 By default the pool is sized to provide one thread for each CPU.
 354 Worker threads dequeue requests and pass them to the driver
 355 asynchronously.
 356 .It
 357 The request is passed to the driver synchronously in the context of the
 358 thread invoking
 359 .Fn crypto_dispatch .
 360 .It
 361 The request is queued to a queue of pending requests.
 362 A single worker thread dequeues requests and passes them to the driver
 363 asynchronously.
 364 .El
 365 .Pp
 366 To select the first method (taskqueue backed by multiple threads),
 367 requests should set
 368 .Dv CRYPTO_F_ASYNC .
 369 To always use the third method (queue to single worker thread),
 370 requests should set
 371 .Dv CRYPTO_F_BATCH .
 372 If both flags are set,
 373 .Dv CRYPTO_F_ASYNC
 374 takes precedence.
 375 If neither flag is set,
 376 .Fn crypto_dispatch
 377 will first attempt the second method (invoke driver synchronously).
 378 If the driver is blocked,
 379 the request will be queued using the third method.
 380 One caveat is that the first method is only used for requests using software
 381 drivers which use host CPUs to process requests.
 382 Requests whose session is associated with a hardware driver will ignore
 383 .Dv CRYPTO_F_ASYNC
 384 and only use
 385 .Dv CRYPTO_F_BATCH
 386 to determine how requests should be scheduled.
 387 .Pp
 388 In addition to bypassing synchronous dispatch in
 389 .Fn crypto_dispatch ,
 390 .Dv CRYPTO_F_BATCH
 391 requests additional changes aimed at optimizing batches of requests to
 392 the same driver.
 393 When the worker thread processes a request with
 394 .Dv CRYPTO_F_BATCH ,
 395 it will search the pending request queue for any other requests for the same
 396 driver,
 397 including requests from different sessions.
 398 If any other requests are present,
 399 .Dv CRYPTO_HINT_MORE
 400 is passed to the driver's process method.
 401 Drivers may use this to batch completion interrupts.
 402 .Pp
 403 Callback function scheduling is simpler than request scheduling.
 404 Callbacks can either be invoked synchronously from
 405 .Fn crypto_done ,
 406 or they can be queued to a pool of worker threads.
 407 This pool of worker threads is also sized to provide one worker thread
 408 for each CPU by default.
 409 Note that a callback function invoked synchronously from
 410 .Fn crypto_done
 411 must follow the same restrictions placed on threaded interrupt handlers.
 412 .Pp
 413 By default,
 414 callbacks are invoked asynchronously by a worker thread.
 415 If
 416 .Dv CRYPTO_F_CBIMM
 417 is set,
 418 the callback is always invoked synchronously from
 419 .Fn crypto_done .
 420 If
 421 .Dv CRYPTO_F_CBIFSYNC
 422 is set,
 423 the callback is invoked synchronously if the request was processed by a
 424 software driver or asynchronously if the request was processed by a
 425 hardware driver.
 426 .Pp
 427 If a request was scheduled to the taskqueue via
 428 .Dv CRYPTO_F_ASYNC ,
 429 callbacks are always invoked asynchronously ignoring
 430 .Dv CRYPTO_F_CBIMM
 431 and
 432 .Dv CRYPTO_F_CBIFSYNC .
 433 In this case,
 434 .Dv CRYPTO_F_ASYNC_KEEPORDER
 435 may be set to ensure that callbacks for requests on a given session are
 436 invoked in the same order that requests were queued to the session via
 437 .Fn crypto_dispatch .
 438 This flag is used by IPsec to ensure that decrypted network packets are
 439 passed up the network stack in roughly the same order they were received.
 440 .Pp
 441 .Ss Other Request Fields
 442 In addition to the fields and flags enumerated above,
 443 .Vt struct cryptop
 444 includes the following:
 445 .Bl -tag -width crp_payload_length
 446 .It Fa crp_session
 447 A reference to the active session.
 448 This is set when the request is created by
 449 .Fn crypto_getreq
 450 and should not be modified.
 451 Drivers can use this to fetch driver-specific session state or
 452 session parameters.
 453 .It Fa crp_etype
 454 Error status.
 455 Either zero on success, or an error if a request fails.
 456 Set by drivers prior to completing a request via
 457 .Fn crypto_done .
 458 .It Fa crp_flags
 459 A bitmask of flags.
 460 The following flags are available in addition to flags discussed previously:
 461 .Bl -tag -width CRYPTO_F_DONE
 462 .It Dv CRYPTO_F_DONE
 463 Set by
 464 .Fa crypto_done
 465 before calling
 466 .Fa crp_callback .
 467 This flag is not very useful and will likely be removed in the future.
 468 It can only be safely checked from the callback routine at which point
 469 it is always set.
 470 .El
 471 .It Fa crp_cipher_key
 472 Pointer to a request-specific encryption key.
 473 If this value is not set,
 474 the request uses the session encryption key.
 475 .It Fa crp_auth_key
 476 Pointer to a request-specific authentication key.
 477 If this value is not set,
 478 the request uses the session authentication key.
 479 .It Fa crp_opaque
 480 An opaque pointer.
 481 This pointer permits users of the cryptographic framework to store
 482 information about a request to be used in the callback.
 483 .It Fa crp_callback
 484 Callback function.
 485 This must point to a callback function of type
 486 .Vt void (*)(struct cryptop *) .
 487 The callback function should inspect
 488 .Fa crp_etype
 489 to determine the status of the completed operation.
 490 It should also arrange for the request to be freed via
 491 .Fn crypto_freereq .
 492 .It Fa crp_olen
 493 Used with compression and decompression requests to describe the updated
 494 length of the payload region in the data buffer.
 495 .Pp
 496 If a compression request increases the size of the payload,
 497 then the data buffer is unmodified, the request completes successfully,
 498 and
 499 .Fa crp_olen
 500 is set to the size the compressed data would have used.
 501 Callers can compare this to the payload region length to determine if
 502 the compressed data was discarded.
 503 .El
 504 .Sh RETURN VALUES
 505 .Fn crypto_dispatch
 506 returns an error if the request contained invalid fields,
 507 or zero if the request was valid.
 508 .Fn crypto_getreq
 509 returns a pointer to a new request structure on success,
 510 or
 511 .Dv NULL
 512 on failure.
 513 .Dv NULL
 514 can only be returned if
 515 .Dv M_NOWAIT
 516 was 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
 526 Not all drivers properly handle mixing session and per-request keys
 527 within a single session.
 528 Consumers should either use a single key for a session specified in
 529 the session parameters or always use per-request keys.