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