16676123fc
Add 'ivlen' and 'maclen' fields to the structure used for CIOGSESSION2 to specify the explicit IV/nonce and MAC/tag lengths for crypto sessions. If these fields are zero, the default lengths are used. This permits selecting an alternate nonce length for AEAD ciphers such as AES-CCM which support multiple nonce leengths. It also supports truncated MACs as input to AEAD or ETA requests. Reviewed by: markj Sponsored by: The FreeBSD Foundation Differential Revision: https://reviews.freebsd.org/D32107
380 lines
11 KiB
Groff
380 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-2021 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).
|
|
.\"
|
|
.\" Portions of this documentation were written by Ararat River
|
|
.\" Consulting, LLC under sponsorship of the FreeBSD Foundation.
|
|
.\"
|
|
.\" 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 October 6, 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 ivlen; /* length of nonce/IV */
|
|
int maclen; /* length of MAC/tag */
|
|
int pad[2]; /* for future expansion */
|
|
};
|
|
|
|
.Ed
|
|
This request is similar to CIOGSESSION but adds additional fields.
|
|
.Pp
|
|
.Fa sessp-\*[Gt]crid
|
|
requests either a specific crypto device or a class of devices (software vs
|
|
hardware).
|
|
.Pp
|
|
.Fa sessp-\*[Gt]ivlen
|
|
specifies the length of the IV or nonce supplied with each request.
|
|
If this field is set to zero, the default IV or nonce length is used.
|
|
.Pp
|
|
.Fa sessp-\*[Gt]maclen
|
|
specifies the length of the MAC or authentication tag supplied or computed by
|
|
each request.
|
|
If this field is set to zero, the full MAC is used.
|
|
.Pp
|
|
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.
|