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