76681661be
There haven't been any non-obscure drivers that supported this functionality and it has been impossible to test to ensure that it still works. The only known consumer of this interface was the engine in OpenSSL < 1.1. Modern OpenSSL versions do not include support for this interface as it was not well-documented. Reviewed by: cem Sponsored by: Chelsio Communications Differential Revision: https://reviews.freebsd.org/D29736
341 lines
10 KiB
Groff
341 lines
10 KiB
Groff
.\" Copyright (c) 2020, Chelsio Inc
|
|
.\"
|
|
.\" 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 April 12, 2021
|
|
.Dt CRYPTO_DRIVER 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crypto_driver
|
|
.Nd interface for symmetric cryptographic drivers
|
|
.Sh SYNOPSIS
|
|
.In 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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.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 .
|
|
.Pp
|
|
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:
|
|
.Bl -tag -width "CRYPTODEV_PROBE_ACCEL_SOFTWARE"
|
|
.It Dv CRYPTODEV_PROBE_HARDWARE
|
|
The driver processes requests via a co-processor.
|
|
.It Dv CRYPTODEV_PROBE_ACCEL_SOFTWARE
|
|
The driver processes requests on the host CPU using optimized instructions
|
|
such as AES-NI.
|
|
.It Dv CRYPTODEV_PROBE_SOFTWARE
|
|
The driver processes requests on the host CPU.
|
|
.El
|
|
.Pp
|
|
This method should not sleep.
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
This method should not sleep.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
This method should not sleep.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.Fn crypto_read_iv
|
|
copies the IV or nonce for
|
|
.Fa crp
|
|
into the local buffer pointed to by
|
|
.Fa iv .
|
|
.Pp
|
|
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.
|
|
.Pp
|
|
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:
|
|
.Bl -tag -width "CRYPTO_SYMQ"
|
|
.It Dv CRYPTO_SYMQ
|
|
indicates that the driver is able to handle symmetric requests passed to
|
|
.Fn CRYPTODEV_PROCESS .
|
|
.El
|
|
.Pp
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.Fn crypto_contiguous_subsegment
|
|
returns a pointer to a contiguous segment or
|
|
.Dv NULL .
|
|
.Pp
|
|
.Fn crypto_get_driverid
|
|
returns a driver identifier on success or -1 on error.
|
|
.Pp
|
|
.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.
|
|
.Pp
|
|
.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
|