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