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