a3d565a118
Use this in GELI to print out a different message when accelerated software such as AESNI is used vs plain software crypto. While here, simplify the logic in GELI a bit for determing which type of crypto driver was chosen the first time by examining the capabilities of the matched driver after a single call to crypto_newsession rather than making separate calls with different flags. Reviewed by: delphij Sponsored by: Chelsio Communications Differential Revision: https://reviews.freebsd.org/D25126
344 lines
10 KiB
Groff
344 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 June 9, 2020
|
|
.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_ASYMQ"
|
|
.It Dv CRYPTO_SYMQ
|
|
indicates that the driver is able to handle symmetric requests passed to
|
|
.Fn CRYPTODEV_PROCESS .
|
|
.It Dv CRYPTO_ASYMQ
|
|
indicates that the driver is able to handle asymmetric requests passed to
|
|
.Fn CRYPTODEV_KPROCESS .
|
|
.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
|