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
364 lines
11 KiB
Groff
364 lines
11 KiB
Groff
.\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $
|
|
.\"
|
|
.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
|
|
.\" Copyright (c) 2014 The FreeBSD Foundation
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Portions of this documentation were written by John-Mark Gurney
|
|
.\" under sponsorship of the FreeBSD Foundation and
|
|
.\" Rubicon Communications, LLC (Netgate).
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Coyote Point Systems, 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.\"
|
|
.\"
|
|
.\" Copyright (c) 2004
|
|
.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone 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 Jonathan Stone OR THE VOICES IN HIS HEAD
|
|
.\" 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.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd April 12, 2021
|
|
.Dt CRYPTO 4
|
|
.Os
|
|
.Sh NAME
|
|
.Nm crypto ,
|
|
.Nm cryptodev
|
|
.Nd user-mode access to hardware-accelerated cryptography
|
|
.Sh SYNOPSIS
|
|
.Cd device crypto
|
|
.Cd device cryptodev
|
|
.Pp
|
|
.In sys/ioctl.h
|
|
.In sys/time.h
|
|
.In crypto/cryptodev.h
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
driver gives user-mode applications access to hardware-accelerated
|
|
cryptographic transforms as implemented by the
|
|
.Xr crypto 9
|
|
in-kernel interface.
|
|
.Pp
|
|
The
|
|
.Pa /dev/crypto
|
|
special device provides an
|
|
.Xr ioctl 2
|
|
based interface.
|
|
User-mode applications open the special device and
|
|
then issue
|
|
.Xr ioctl 2
|
|
calls on the descriptor.
|
|
User-mode access to
|
|
.Pa /dev/crypto
|
|
is controlled by the
|
|
.Ic kern.cryptodevallowsoft
|
|
.Xr sysctl 8
|
|
variable.
|
|
If this variable is zero,
|
|
then user-mode sessions are only permitted to use cryptography coprocessors.
|
|
.Sh THEORY OF OPERATION
|
|
Use of the device requires a basic series of steps:
|
|
.Bl -enum
|
|
.It
|
|
Open the
|
|
.Pa /dev/crypto
|
|
device.
|
|
.It
|
|
Create a session with
|
|
.Dv CIOCGSESSION
|
|
or
|
|
.Dv CIOCGSESSION2 .
|
|
Applications will require at least one symmetric session.
|
|
Since cipher and MAC keys are tied to sessions, many
|
|
applications will require more.
|
|
.It
|
|
Submit requests, synchronously with
|
|
.Dv CIOCCRYPT
|
|
or
|
|
.Dv CIOCCRYPTAEAD .
|
|
.It
|
|
Optionally destroy a session with
|
|
.Dv CIOCFSESSION .
|
|
.It
|
|
Close the
|
|
.Pa /dev/crypto
|
|
device.
|
|
This will automatically close any remaining sessions associated with the
|
|
file desriptor.
|
|
.El
|
|
.Sh SYMMETRIC-KEY OPERATION
|
|
.Nm cryptodev
|
|
provides a context-based API
|
|
to traditional symmetric-key encryption (or privacy) algorithms,
|
|
keyed and unkeyed one-way hash (HMAC and MAC) algorithms,
|
|
encrypt-then-authenticate (ETA) fused operations,
|
|
and authenticated encryption with additional data (AEAD) operations.
|
|
For ETA operations,
|
|
drivers perform both a privacy algorithm and an integrity-check
|
|
algorithm in a single pass over the data: either a fused
|
|
encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
|
|
Similarly, for AEAD operations,
|
|
drivers perform either an encrypt/MAC-generate operation
|
|
or a MAC-verify/decrypt operation.
|
|
.Pp
|
|
The algorithm(s) and key(s) to use are specified when a session is
|
|
created.
|
|
Individual requests are able to specify per-request initialization vectors
|
|
or nonces.
|
|
.Ss Algorithms
|
|
For a list of supported algorithms, see
|
|
.Xr crypto 7 .
|
|
.Ss IOCTL Request Descriptions
|
|
.\"
|
|
.Bl -tag -width CIOCGSESSION
|
|
.\"
|
|
.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
|
|
.Bd -literal
|
|
struct crypt_find_op {
|
|
int crid; /* driver id + flags */
|
|
char name[32]; /* device/driver name */
|
|
};
|
|
|
|
.Ed
|
|
If
|
|
.Fa crid
|
|
is -1, then find the driver named
|
|
.Fa name
|
|
and return the id in
|
|
.Fa crid .
|
|
If
|
|
.Fa crid
|
|
is not -1, return the name of the driver with
|
|
.Fa crid
|
|
in
|
|
.Fa name .
|
|
In either case, if the driver is not found,
|
|
.Dv ENOENT
|
|
is returned.
|
|
.It Dv CIOCGSESSION Fa struct session_op *sessp
|
|
.Bd -literal
|
|
struct session_op {
|
|
uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
|
|
uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
|
|
|
|
uint32_t keylen; /* cipher key */
|
|
const void *key;
|
|
int mackeylen; /* mac key */
|
|
const void *mackey;
|
|
|
|
uint32_t ses; /* returns: ses # */
|
|
};
|
|
|
|
.Ed
|
|
Create a new cryptographic session on a file descriptor for the device;
|
|
that is, a persistent object specific to the chosen
|
|
privacy algorithm, integrity algorithm, and keys specified in
|
|
.Fa sessp .
|
|
The special value 0 for either privacy or integrity
|
|
is reserved to indicate that the indicated operation (privacy or integrity)
|
|
is not desired for this session.
|
|
ETA sessions specify both privacy and integrity algorithms.
|
|
AEAD sessions specify only a privacy algorithm.
|
|
.Pp
|
|
Multiple sessions may be bound to a single file descriptor.
|
|
The session ID returned in
|
|
.Fa sessp-\*[Gt]ses
|
|
is supplied as a required field in the operation structure
|
|
.Fa crypt_op
|
|
for future encryption or hashing requests.
|
|
.\" .Pp
|
|
.\" This implementation will never return a session ID of 0 for a successful
|
|
.\" creation of a session, which is a
|
|
.\" .Nx
|
|
.\" extension.
|
|
.Pp
|
|
For non-zero privacy algorithms, the privacy algorithm
|
|
must be specified in
|
|
.Fa sessp-\*[Gt]cipher ,
|
|
the key length in
|
|
.Fa sessp-\*[Gt]keylen ,
|
|
and the key value in the octets addressed by
|
|
.Fa sessp-\*[Gt]key .
|
|
.Pp
|
|
For keyed one-way hash algorithms, the one-way hash must be specified
|
|
in
|
|
.Fa sessp-\*[Gt]mac ,
|
|
the key length in
|
|
.Fa sessp-\*[Gt]mackey ,
|
|
and the key value in the octets addressed by
|
|
.Fa sessp-\*[Gt]mackeylen .
|
|
.\"
|
|
.Pp
|
|
Support for a specific combination of fused privacy and
|
|
integrity-check algorithms depends on whether the underlying
|
|
hardware supports that combination.
|
|
Not all combinations are supported
|
|
by all hardware, even if the hardware supports each operation as a
|
|
stand-alone non-fused operation.
|
|
.It Dv CIOCGSESSION2 Fa struct session2_op *sessp
|
|
.Bd -literal
|
|
struct session2_op {
|
|
uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
|
|
uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
|
|
|
|
uint32_t keylen; /* cipher key */
|
|
const void *key;
|
|
int mackeylen; /* mac key */
|
|
const void *mackey;
|
|
|
|
uint32_t ses; /* returns: ses # */
|
|
int crid; /* driver id + flags (rw) */
|
|
int pad[4]; /* for future expansion */
|
|
};
|
|
|
|
.Ed
|
|
This request is similar to CIOGSESSION except that
|
|
.Fa sessp-\*[Gt]crid
|
|
requests either a specific crypto device or a class of devices (software vs
|
|
hardware).
|
|
The
|
|
.Fa sessp-\*[Gt]pad
|
|
field must be initialized to zero.
|
|
.It Dv CIOCCRYPT Fa struct crypt_op *cr_op
|
|
.Bd -literal
|
|
struct crypt_op {
|
|
uint32_t ses;
|
|
uint16_t op; /* e.g. COP_ENCRYPT */
|
|
uint16_t flags;
|
|
u_int len;
|
|
const void *src;
|
|
void *dst;
|
|
void *mac; /* must be large enough for result */
|
|
const void *iv;
|
|
};
|
|
|
|
.Ed
|
|
Request an encryption/decryption (or hash) operation.
|
|
To encrypt, set
|
|
.Fa cr_op-\*[Gt]op
|
|
to
|
|
.Dv COP_ENCRYPT .
|
|
To decrypt, set
|
|
.Fa cr_op-\*[Gt]op
|
|
to
|
|
.Dv COP_DECRYPT .
|
|
The field
|
|
.Fa cr_op-\*[Gt]len
|
|
supplies the length of the input buffer; the fields
|
|
.Fa cr_op-\*[Gt]src ,
|
|
.Fa cr_op-\*[Gt]dst ,
|
|
.Fa cr_op-\*[Gt]mac ,
|
|
.Fa cr_op-\*[Gt]iv
|
|
supply the addresses of the input buffer, output buffer,
|
|
one-way hash, and initialization vector, respectively.
|
|
.Pp
|
|
If a session is using either fused encrypt-then-authenticate or
|
|
an AEAD algorithm,
|
|
decryption operations require the associated hash as an input.
|
|
If the hash is incorrect, the
|
|
operation will fail with
|
|
.Dv EBADMSG
|
|
and the output buffer will remain unchanged.
|
|
.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
|
|
.Bd -literal
|
|
struct crypt_aead {
|
|
uint32_t ses;
|
|
uint16_t op; /* e.g. COP_ENCRYPT */
|
|
uint16_t flags;
|
|
u_int len;
|
|
u_int aadlen;
|
|
u_int ivlen;
|
|
const void *src;
|
|
void *dst;
|
|
const void *aad; /* additional authenticated data */
|
|
void *tag; /* must fit for chosen TAG length */
|
|
const void *iv;
|
|
};
|
|
|
|
.Ed
|
|
The
|
|
.Dv CIOCCRYPTAEAD
|
|
is similar to the
|
|
.Dv CIOCCRYPT
|
|
but provides additional data in
|
|
.Fa cr_aead-\*[Gt]aad
|
|
to include in the authentication mode.
|
|
.It Dv CIOCFSESSION Fa u_int32_t ses_id
|
|
Destroys the session identified by
|
|
.Fa ses_id .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr aesni 4 ,
|
|
.Xr hifn 4 ,
|
|
.Xr ipsec 4 ,
|
|
.Xr padlock 4 ,
|
|
.Xr safe 4 ,
|
|
.Xr crypto 7 ,
|
|
.Xr geli 8 ,
|
|
.Xr crypto 9
|
|
.Sh HISTORY
|
|
The
|
|
.Nm
|
|
driver first appeared in
|
|
.Ox 3.0 .
|
|
The
|
|
.Nm
|
|
driver was imported to
|
|
.Fx 5.0 .
|
|
.Sh BUGS
|
|
Error checking and reporting is weak.
|
|
.Pp
|
|
The values specified for symmetric-key key sizes to
|
|
.Dv CIOCGSESSION
|
|
must exactly match the values expected by
|
|
.Xr opencrypto 9 .
|
|
The output buffer and MAC buffers supplied to
|
|
.Dv CIOCCRYPT
|
|
must follow whether privacy or integrity algorithms were specified for
|
|
session: if you request a
|
|
.No non- Ns Dv NULL
|
|
algorithm, you must supply a suitably-sized buffer.
|