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