feat: Added FreeBSD man pages

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.