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