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