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