diff options
Diffstat (limited to 'static/freebsd/man4/crypto.4')
| -rw-r--r-- | static/freebsd/man4/crypto.4 | 376 |
1 files changed, 376 insertions, 0 deletions
diff --git a/static/freebsd/man4/crypto.4 b/static/freebsd/man4/crypto.4 new file mode 100644 index 00000000..4242a663 --- /dev/null +++ b/static/freebsd/man4/crypto.4 @@ -0,0 +1,376 @@ +.\" $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. +.\" +.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 descriptor. +.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 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. |