Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
1. Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
3. Neither the name of the Chelsio Inc nor the names of its
contributors may be used to endorse or promote products derived from
this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
* Other names and brands may be claimed as the property of others.
$FreeBSD$
.Dd June 9, 2020 .Dt CRYPTO_DRIVER 9 .Os .Sh NAME .Nm crypto_driver .Nd interface for symmetric cryptographic drivers .Sh SYNOPSIS n opencrypto/cryptodev.h .Ft void .Fn crypto_copyback "struct cryptop *crp" "int off" "int size" "const void *src" .Ft void .Fn crypto_copydata "struct cryptop *crp" "int off" "int size" "void *dst" .Ft void .Fn crypto_done "struct cryptop *crp" .Ft int32_t .Fn crypto_get_driverid "device_t dev" "size_t session_size" "int flags" .Ft void * .Fn crypto_get_driver_session "crypto_session_t crypto_session" .Ft void .Fn crypto_read_iv "struct cryptop *crp" "void *iv" .Ft int .Fn crypto_unblock "uint32_t driverid" "int what" .Ft int .Fn crypto_unregister_all "uint32_t driverid" .Ft int .Fn CRYPTODEV_FREESESSION "device_t dev" "crypto_session_t crypto_session" .Ft int .Fo CRYPTODEV_NEWSESSION .Fa "device_t dev" .Fa "crypto_session_t crypto_session" .Fa "const struct crypto_session_params *csp" .Fc .Ft int .Fo CRYPTODEV_PROBESESSION .Fa "device_t dev" .Fa "const struct crypto_session_params *csp" .Fc .Ft int .Fn CRYPTODEV_PROCESS "device_t dev" "struct cryptop *crp" "int flags" .Ft void .Fo hmac_init_ipad .Fa "struct auth_hash *axf" .Fa "const char *key" .Fa "int klen" .Fa "void *auth_ctx" .Fc .Ft void .Fo hmac_init_opad .Fa "struct auth_hash *axf" .Fa "const char *key" .Fa "int klen" .Fa "void *auth_ctx" .Fc .Sh DESCRIPTION Symmetric cryptographic drivers process cryptographic requests submitted to sessions associated with the driver.
p Cryptographic drivers call .Fn crypto_get_driverid to register with the cryptographic framework. .Fa dev is the device used to service requests. The .Fn CRYPTODEV methods are defined in the method table for the device driver attached to .Fa dev . .Fa session_size specifies the size of a driver-specific per-session structure allocated by the cryptographic framework. .Fa flags is a bitmask of properties about the driver. Exactly one of .Dv CRYPTOCAP_F_SOFTWARE or .Dv CRYPTOCAP_F_HARDWARE must be specified. .Dv CRYPTOCAP_F_SOFTWARE should be used for drivers which process requests using host CPUs. .Dv CRYPTOCAP_F_HARDWARE should be used for drivers which process requests on separate co-processors. .Dv CRYPTOCAP_F_SYNC should be set for drivers which process requests synchronously in .Fn CRYPTODEV_PROCESS . .Dv CRYPTOCAP_F_ACCEL_SOFTWARE should be set for software drivers which use accelerated CPU instructions. .Fn crypto_get_driverid returns an opaque driver id.
p .Fn crypto_unregister_all unregisters a driver from the cryptographic framework. If there are any pending operations or open sessions, this function will sleep. .Fa driverid is the value returned by an earlier call to .Fn crypto_get_driverid .
p When a new session is created by .Fn crypto_newsession , .Fn CRYPTODEV_PROBESESSION is invoked by the cryptographic framework on each active driver to determine the best driver to use for the session. This method should inspect the session parameters in .Fa csp . If a driver does not support requests described by .Fa csp , this method should return an error value. If the driver does support requests described by .Fa csp , it should return a negative value. The framework prefers drivers with the largest negative value, similar to .Xr DEVICE_PROBE 9 . The following values are defined for non-error return values from this method: l -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE" t Dv CRYPTODEV_PROBE_HARDWARE The driver processes requests via a co-processor. t Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE The driver processes requests on the host CPU using optimized instructions such as AES-NI. t Dv CRYPTODEV_PROBE_SOFTWARE The driver processes requests on the host CPU. .El
p This method should not sleep.
p Once the framework has chosen a driver for a session, the framework invokes the .Fn CRYPTODEV_NEWSESSION method to initialize driver-specific session state. Prior to calling this method, the framework allocates a per-session driver-specific data structure. This structure is initialized with zeroes, and its size is set by the .Fa session_size passed to .Fn crypto_get_driverid . This method can retrieve a pointer to this data structure by passing .Fa crypto_session to .Fn crypto_get_driver_session . Session parameters are described in .Fa csp .
p This method should not sleep.
p .Fn CRYPTODEV_FREESESSION is invoked to release any driver-specific state when a session is destroyed. The per-session driver-specific data structure is explicitly zeroed and freed by the framework after this method returns. If a driver requires no additional tear-down steps, it can leave this method undefined.
p This method should not sleep.
p .Fn CRYPTODEV_PROCESS is invoked for each request submitted to an active session. This method can either complete a request synchronously or schedule it to be completed asynchronously, but it must not sleep.
p If this method is not able to complete a request due to insufficient resources such as a full command queue, it can defer the request by returning .Dv ERESTART . The request will be queued by the framework and retried once the driver releases pending requests via .Fn crypto_unblock . Any requests submitted to sessions belonging to the driver will also be queued until .Fn crypto_unblock is called.
p If a driver encounters errors while processing a request, it should report them via the .Fa crp_etype field of .Fa crp rather than returning an error directly.
p .Fa flags may be set to .Dv CRYPTO_HINT_MORE if there are additional requests queued for this driver. The driver can use this as a hint to batch completion interrupts. Note that these additional requests may be from different sessions.
p .Fn crypto_get_driver_session returns a pointer to the driver-specific per-session data structure for the session .Fa crypto_session . This function can be used in the .Fn CRYPTODEV_NEWSESSION , .Fn CRYPTODEV_PROCESS , and .Fn CRYPTODEV_FREESESSION callbacks.
p .Fn crypto_copydata copies .Fa size bytes out of the input buffer for .Fa crp into a local buffer pointed to by .Fa dst . The bytes are read starting at an offset of .Fa off bytes in the request's input buffer.
p .Fn crypto_copyback copies .Fa size bytes from the local buffer pointed to by .Fa src into the output buffer for .Fa crp . The bytes are written starting at an offset of .Fa off bytes in the request's output buffer.
p .Fn crypto_read_iv copies the IV or nonce for .Fa crp into the local buffer pointed to by .Fa iv .
p A driver calls .Fn crypto_done to mark the request .Fa crp as completed. Any errors should be set in .Fa crp_etype prior to calling this function.
p If a driver defers a request by returning .Dv ERESTART from .Dv CRYPTO_PROCESS , the framework will queue all requests for the driver until the driver calls .Fn crypto_unblock to indicate that the temporary resource shortage has been relieved. For example, if a driver returns .Dv ERESTART due to a full command ring, it would invoke .Fn crypto_unblock from a command completion interrupt that makes a command ring entry available. .Fa driverid is the value returned by .Fn crypto_get_driverid . .Fa what indicates which types of requests the driver is able to handle again: l -tag -width "CRYPTO_ASYMQ" t Dv CRYPTO_SYMQ indicates that the driver is able to handle symmetric requests passed to .Fn CRYPTODEV_PROCESS . t Dv CRYPTO_ASYMQ indicates that the driver is able to handle asymmetric requests passed to .Fn CRYPTODEV_KPROCESS . .El
p
p .Fn hmac_init_ipad prepares an authentication context to generate the inner hash of an HMAC. .Fa axf is a software implementation of an authentication algorithm such as the value returned by .Fn crypto_auth_hash . .Fa key is a pointer to a HMAC key of .Fa klen bytes. .Fa auth_ctx points to a valid authentication context for the desired algorithm. The function initializes the context with the supplied key.
p .Fn hmac_init_opad is similar to .Fn hmac_init_ipad except that it prepares an authentication context to generate the outer hash of an HMAC. .Sh RETURN VALUES .Fn crypto_apply returns the return value from the caller-supplied callback function.
p .Fn crypto_contiguous_subsegment returns a pointer to a contiguous segment or .Dv NULL .
p .Fn crypto_get_driverid returns a driver identifier on success or -1 on error.
p .Fn crypto_unblock , .Fn crypto_unregister_all , .Fn CRYPTODEV_FREESESSION , .Fn CRYPTODEV_NEWSESSION , and .Fn CRYPTODEV_PROCESS return zero on success or an error on failure.
p .Fn CRYPTODEV_PROBESESSION returns a negative value on success or an error on failure. .Sh SEE ALSO .Xr crypto 7 , .Xr crypto 9 , .Xr crypto_buffer 9 , .Xr crypto_request 9 , .Xr crypto_session 9