share/man/man9/crypto_driver.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 April 20, 2020
  34 .Dt CRYPTO_DRIVER 9
  35 .Os
  36 .Sh NAME
  37 .Nm crypto_driver
  38 .Nd interface for symmetric cryptographic drivers
  39 .Sh SYNOPSIS
  40 .In opencrypto/cryptodev.h
  41 .Ft int
  42 .Fo crypto_apply
  43 .Fa "struct cryptop *crp"
  44 .Fa "int off"
  45 .Fa "int len"
  46 .Fa "int (*f)(void *, void *, u_int)"
  47 .Fa "void *arg"
  48 .Fc
  49 .Ft void *
  50 .Fo crypto_contiguous_subsegment
  51 .Fa "struct cryptop *crp"
  52 .Fa "size_t skip"
  53 .Fa "size_t len"
  54 .Fc
  55 .Ft void
  56 .Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src"
  57 .Ft void
  58 .Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst"
  59 .Ft void
  60 .Fn crypto_done "struct cryptop *crp"
  61 .Ft int32_t
  62 .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags"
  63 .Ft void *
  64 .Fn crypto_get_driver_session "crypto_session_t crypto_session"
  65 .Ft void
  66 .Fn crypto_read_iv "struct cryptop *crp" "void *iv"
  67 .Ft int
  68 .Fn crypto_unblock "uint32_t driverid" "int what"
  69 .Ft int
  70 .Fn crypto_unregister_all "uint32_t driverid"
  71 .Ft int
  72 .Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session"
  73 .Ft int
  74 .Fo CRYPTODEV_NEWSESSION
  75 .Fa "device_t dev"
  76 .Fa "crypto_session_t crypto_session"
  77 .Fa "const struct crypto_session_params *csp"
  78 .Fc
  79 .Ft int
  80 .Fo CRYPTODEV_PROBESESSION
  81 .Fa "device_t dev"
  82 .Fa "const struct crypto_session_params *csp"
  83 .Fc
  84 .Ft int
  85 .Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags"
  86 .Ft void
  87 .Fo hmac_init_ipad
  88 .Fa "struct auth_hash *axf"
  89 .Fa "const char *key"
  90 .Fa "int klen"
  91 .Fa "void *auth_ctx"
  92 .Fc
  93 .Ft void
  94 .Fo hmac_init_opad
  95 .Fa "struct auth_hash *axf"
  96 .Fa "const char *key"
  97 .Fa "int klen"
  98 .Fa "void *auth_ctx"
  99 .Fc
 100 .Sh DESCRIPTION
 101 Symmetric cryptographic drivers process cryptographic requests
 102 submitted to sessions associated with the driver.
 103 .Pp
 104 Cryptographic drivers call
 105 .Fn crypto_get_driverid
 106 to register with the cryptographic framework.
 107 .Fa dev
 108 is the device used to service requests.
 109 The
 110 .Fn CRYPTODEV
 111 methods are defined in the method table for the device driver attached to
 112 .Fa dev .
 113 .Fa session_size
 114 specifies the size of a driver-specific per-session structure allocated by
 115 the cryptographic framework.
 116 .Fa flags
 117 is a bitmask of properties about the driver.
 118 Exactly one of
 119 .Dv CRYPTOCAP_F_SOFTWARE
 120 or
 121 .Dv CRYPTOCAP_F_HARDWARE
 122 must be specified.
 123 .Dv CRYPTOCAP_F_SOFTWARE
 124 should be used for drivers which process requests using host CPUs.
 125 .Dv CRYPTOCAP_F_HARDWARE
 126 should be used for drivers which process requests on separate co-processors.
 127 .Dv CRYPTOCAP_F_SYNC
 128 should be set for drivers which process requests synchronously in
 129 .Fn CRYPTODEV_PROCESS .
 130 .Fn crypto_get_driverid
 131 returns an opaque driver id.
 132 .Pp
 133 .Fn crypto_unregister_all
 134 unregisters a driver from the cryptographic framework.
 135 If there are any pending operations or open sessions,
 136 this function will sleep.
 137 .Fa driverid
 138 is the value returned by an earlier call to
 139 .Fn crypto_get_driverid .
 140 .Pp
 141 When a new session is created by
 142 .Fn crypto_newsession ,
 143 .Fn CRYPTODEV_PROBESESSION
 144 is invoked by the cryptographic framework on each active driver to
 145 determine the best driver to use for the session.
 146 This method should inspect the session parameters in
 147 .Fa csp .
 148 If a driver does not support requests described by
 149 .Fa csp ,
 150 this method should return an error value.
 151 If the driver does support requests described by
 152 .Fa csp ,
 153 it should return a negative value.
 154 The framework prefers drivers with the largest negative value,
 155 similar to
 156 .Xr DEVICE_PROBE 9 .
 157 The following values are defined for non-error return values from this
 158 method:
 159 .Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE"
 160 .It Dv CRYPTODEV_PROBE_HARDWARE
 161 The driver processes requests via a co-processor.
 162 .It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE
 163 The driver processes requests on the host CPU using optimized instructions
 164 such as AES-NI.
 165 .It Dv CRYPTODEV_PROBE_SOFTWARE
 166 The driver processes requests on the host CPU.
 167 .El
 168 .Pp
 169 This method should not sleep.
 170 .Pp
 171 Once the framework has chosen a driver for a session,
 172 the framework invokes the
 173 .Fn CRYPTODEV_NEWSESSION
 174 method to initialize driver-specific session state.
 175 Prior to calling this method,
 176 the framework allocates a per-session driver-specific data structure.
 177 This structure is initialized with zeroes,
 178 and its size is set by the
 179 .Fa session_size
 180 passed to
 181 .Fn crypto_get_driverid .
 182 This method can retrieve a pointer to this data structure by passing
 183 .Fa crypto_session
 184 to
 185 .Fn crypto_get_driver_session .
 186 Session parameters are described in
 187 .Fa csp .
 188 .Pp
 189 This method should not sleep.
 190 .Pp
 191 .Fn CRYPTODEV_FREESESSION
 192 is invoked to release any driver-specific state when a session is
 193 destroyed.
 194 The per-session driver-specific data structure is explicitly zeroed
 195 and freed by the framework after this method returns.
 196 If a driver requires no additional tear-down steps, it can leave
 197 this method undefined.
 198 .Pp
 199 This method should not sleep.
 200 .Pp
 201 .Fn CRYPTODEV_PROCESS
 202 is invoked for each request submitted to an active session.
 203 This method can either complete a request synchronously or
 204 schedule it to be completed asynchronously,
 205 but it must not sleep.
 206 .Pp
 207 If this method is not able to complete a request due to insufficient
 208 resources such as a full command queue,
 209 it can defer the request by returning
 210 .Dv ERESTART .
 211 The request will be queued by the framework and retried once the
 212 driver releases pending requests via
 213 .Fn crypto_unblock .
 214 Any requests submitted to sessions belonging to the driver will also
 215 be queued until
 216 .Fn crypto_unblock
 217 is called.
 218 .Pp
 219 If a driver encounters errors while processing a request,
 220 it should report them via the
 221 .Fa crp_etype
 222 field of
 223 .Fa crp
 224 rather than returning an error directly.
 225 .Pp
 226 .Fa flags
 227 may be set to
 228 .Dv CRYPTO_HINT_MORE
 229 if there are additional requests queued for this driver.
 230 The driver can use this as a hint to batch completion interrupts.
 231 Note that these additional requests may be from different sessions.
 232 .Pp
 233 .Fn crypto_get_driver_session
 234 returns a pointer to the driver-specific per-session data structure
 235 for the session
 236 .Fa crypto_session .
 237 This function can be used in the
 238 .Fn CRYPTODEV_NEWSESSION ,
 239 .Fn CRYPTODEV_PROCESS ,
 240 and
 241 .Fn CRYPTODEV_FREESESSION
 242 callbacks.
 243 .Pp
 244 .Fn crypto_copydata
 245 copies
 246 .Fa size
 247 bytes out of the data buffer for
 248 .Fa crp
 249 into a local buffer pointed to by
 250 .Fa dst .
 251 The bytes are read starting at an offset of
 252 .Fa off
 253 bytes in the request's data buffer.
 254 .Pp
 255 .Fn crypto_copyback
 256 copies
 257 .Fa size
 258 bytes from the local buffer pointed to by
 259 .Fa src
 260 into the data buffer for
 261 .Fa crp .
 262 The bytes are written starting at an offset of
 263 .Fa off
 264 bytes in the request's data buffer.
 265 .Pp
 266 .Fn crypto_read_iv
 267 copies the IV or nonce for
 268 .Fa crp
 269 into the the local buffer pointed to by
 270 .Fa iv .
 271 .Pp
 272 A driver calls
 273 .Fn crypto_done
 274 to mark the request
 275 .Fa crp
 276 as completed.
 277 Any errors should be set in
 278 .Fa crp_etype
 279 prior to calling this function.
 280 .Pp
 281 If a driver defers a request by returning
 282 .Dv ERESTART
 283 from
 284 .Dv CRYPTO_PROCESS ,
 285 the framework will queue all requests for the driver until the driver calls
 286 .Fn crypto_unblock
 287 to indicate that the temporary resource shortage has been relieved.
 288 For example,
 289 if a driver returns
 290 .Dv ERESTART
 291 due to a full command ring,
 292 it would invoke
 293 .Fn crypto_unblock
 294 from a command completion interrupt that makes a command ring entry available.
 295 .Fa driverid
 296 is the value returned by
 297 .Fn crypto_get_driverid .
 298 .Fa what
 299 indicates which types of requests the driver is able to handle again:
 300 .Bl -tag -width "CRYPTO_ASYMQ"
 301 .It Dv CRYPTO_SYMQ
 302 indicates that the driver is able to handle symmetric requests passed to
 303 .Fn CRYPTODEV_PROCESS .
 304 .It Dv CRYPTO_ASYMQ
 305 indicates that the driver is able to handle asymmetric requests passed to
 306 .Fn CRYPTODEV_KPROCESS .
 307 .El
 308 .Pp
 309 .Fn crypto_apply
 310 is a helper routine that can be used to invoke a caller-supplied function
 311 to a region of the data buffer for
 312 .Fa crp .
 313 The function
 314 .Fa f
 315 is called one or more times.
 316 For each invocation,
 317 the first argument to
 318 .Fa f
 319 is the value of
 320 .Fa arg passed to
 321 .Fn crypto_apply .
 322 The second and third arguments to
 323 .Fa f
 324 are a pointer and length to a segment of the buffer mapped into the kernel.
 325 The function is called enough times to cover the
 326 .Fa len
 327 bytes of the data buffer which starts at an offset
 328 .Fa off .
 329 If any invocation of
 330 .Fa f
 331 returns a non-zero value,
 332 .Fn crypto_apply
 333 immediately returns that value without invoking
 334 .Fa f
 335 on any remaining segments of the region,
 336 otherwise
 337 .Fn crypto_apply
 338 returns the value from the final call to
 339 .Fa f .
 340 .Pp
 341 .Fn crypto_contiguous_subsegment
 342 attempts to locate a single, virtually-contiguous segment of the data buffer
 343 for
 344 .Fa crp .
 345 The segment must be
 346 .Fa len
 347 bytes long and start at an offset of
 348 .Fa skip
 349 bytes.
 350 If a segment is found,
 351 a pointer to the start of the segment is returned.
 352 Otherwise,
 353 .Dv NULL
 354 is returned.
 355 .Pp
 356 .Fn hmac_init_ipad
 357 prepares an authentication context to generate the inner hash of an HMAC.
 358 .Fa axf
 359 is a software implementation of an authentication algorithm such as the
 360 value returned by
 361 .Fn crypto_auth_hash .
 362 .Fa key
 363 is a pointer to a HMAC key of
 364 .Fa klen
 365 bytes.
 366 .Fa auth_ctx
 367 points to a valid authentication context for the desired algorithm.
 368 The function initializes the context with the supplied key.
 369 .Pp
 370 .Fn hmac_init_opad
 371 is similar to
 372 .Fn hmac_init_ipad
 373 except that it prepares an authentication context to generate the
 374 outer hash of an HMAC.
 375 .Sh RETURN VALUES
 376 .Fn crypto_apply
 377 returns the return value from the caller-supplied callback function.
 378 .Pp
 379 .Fn crypto_contiguous_subsegment
 380 returns a pointer to a contiguous segment or
 381 .Dv NULL .
 382 .Pp
 383 .Fn crypto_get_driverid
 384 returns a driver identifier on success or -1 on error.
 385 .Pp
 386 .Fn crypto_unblock ,
 387 .Fn crypto_unregister_all ,
 388 .Fn CRYPTODEV_FREESESSION ,
 389 .Fn CRYPTODEV_NEWSESSION ,
 390 and
 391 .Fn CRYPTODEV_PROCESS
 392 return zero on success or an error on failure.
 393 .Pp
 394 .Fn CRYPTODEV_PROBESESSION
 395 returns a negative value on success or an error on failure.
 396 .Sh SEE ALSO
 397 .Xr crypto 7 ,
 398 .Xr crypto 9 ,
 399 .Xr crypto_request 9 ,
 400 .Xr crypto_session 9