diff options
Diffstat (limited to 'share')
| -rw-r--r-- | share/man/man4/crypto.4 | 449 | ||||
| -rw-r--r-- | share/man/man4/inet.4 | 26 | ||||
| -rw-r--r-- | share/man/man7/Makefile | 1 | ||||
| -rw-r--r-- | share/man/man7/crypto.7 | 141 | ||||
| -rw-r--r-- | share/man/man9/crypto.9 | 26 |
5 files changed, 541 insertions, 102 deletions
diff --git a/share/man/man4/crypto.4 b/share/man/man4/crypto.4 index bb62825..c3d328c 100644 --- a/share/man/man4/crypto.4 +++ b/share/man/man4/crypto.4 @@ -1,8 +1,16 @@ -.\" $OpenBSD: crypto.4,v 1.4 2002/09/12 07:15:03 deraadt Exp $ +.\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ .\" -.\" Copyright (c) 2001 Theo de Raadt +.\" 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: @@ -11,99 +19,378 @@ .\" 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. The name of the author may not be used to endorse or promote products -.\" derived from this software without specific prior written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``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 AUTHOR 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 +.\" +.\" 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 September 7, 2010 +.Dd December 12, 2014 .Dt CRYPTO 4 .Os .Sh NAME .Nm crypto , .Nm cryptodev -.Nd hardware crypto access driver +.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 provides a device-independent framework to support -cryptographic operations in the kernel. +driver gives user-mode applications access to hardware-accelerated +cryptographic transforms, as implemented by the +.Xr opencrypto 9 +in-kernel interface. +.Pp The -.Nm cryptodev -driver provides userland applications access to this support -through the .Pa /dev/crypto -device. -This node primarily operates in an +special device provides an +.Xr ioctl 2 +based interface. +User-mode applications should open the special device, +then issue .Xr ioctl 2 -based model, permitting a variety of applications to query device capabilities, -submit transactions, and get results. +calls on the descriptor. +User-mode access to +.Pa /dev/crypto +is controlled by three +.Xr sysctl 8 +variables, +.Ic kern.userasymcrypto +and +.Ic kern.cryptodevallowsoft . +See +.Xr sysctl 7 +for additional details. .Pp -If -.Ar count -given in the specification, and is greater than 0, a maximum of one +The .Nm -device is created. +device provides two distinct modes of operation: one mode for +symmetric-keyed cryptographic requests, and a second mode for +both asymmetric-key (public-key/private-key) requests, and for +modular arithmetic (for Diffie-Hellman key exchange and other +cryptographic protocols). +The two modes are described separately below. +.Sh THEORY OF OPERATION +Regardless of whether symmetric-key or asymmetric-key operations are +to be performed, use of the device requires a basic series of steps: +.Pp +.Bl -enum +.It +Open a file descriptor for the device. +See +.Xr open 2 . +.It +If any symmetric operation will be performed, +create one session, with +.Dv CIOCGSESSION . +Most applications will require at least one symmetric session. +Since cipher and MAC keys are tied to sessions, many +applications will require more. +Asymmetric operations do not use sessions. +.It +Submit requests, synchronously with +.Dv CIOCCRYPT +(symmetric) +or +.Dv CIOCKEY +(asymmetric). +.It +Destroy one session with +.Dv CIOCFSESSION . +.It +Close the device with +.Xr close 2 . +.El +.Sh SYMMETRIC-KEY OPERATION +The symmetric-key operation mode provides a context-based API +to traditional symmetric-key encryption (or privacy) algorithms, +or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. +The symmetric-key mode also permits fused operation, +where the hardware performs 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. +.Pp +To use symmetric mode, you must first create a session specifying +the algorithm(s) and key(s) to use; then issue encrypt or decrypt +requests against the session. +.Ss Algorithms +For a list of supported algorithms, see +.Xr crypto 7 +and +.Xr crypto 9 . +.Ss IOCTL Request Descriptions +.\" +.Bl -tag -width CIOCGSESSION +.\" +.It Dv CRIOGET Fa int *fd +Clone the fd argument to +.Xr ioctl 2 , +yielding a new file descriptor for the creation of sessions. +.\" +.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 { + u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ + u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ + + u_int32_t keylen; /* cipher key */ + void * key; + int mackeylen; /* mac key */ + void * mackey; + + u_int32_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. +.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 symmetric-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 symmetric-key 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 -The following +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 CIOCCRYPT Fa struct crypt_op *cr_op +.Bd -literal +struct crypt_op { + u_int32_t ses; + u_int16_t op; /* e.g. COP_ENCRYPT */ + u_int16_t flags; + u_int len; + caddr_t src, dst; + caddr_t mac; /* must be large enough for result */ + caddr_t iv; +}; + +.Ed +Request a symmetric-key (or hash) operation. +The file descriptor argument to .Xr ioctl 2 -calls apply only to the -.Nm -devices: -.Bl -tag -width ".Dv CIOCGSESSION" -.It Dv CIOCGSESSION -Setup a new crypto session for a new type of operation. -.It Dv CIOCFSESSION -Free a previously established session. -.It Dv CIOCCRYPT -Perform a crypto operation against a previously setup session. +must have been bound to a valid session. +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. +.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead +.Bd -literal +struct crypt_aead { + u_int32_t ses; + u_int16_t op; /* e.g. COP_ENCRYPT */ + u_int16_t flags; + u_int len; + u_int aadlen; + u_int ivlen; + caddr_t src, dst; + caddr_t aad; + caddr_t tag; /* must be large enough for result */ + caddr_t 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 /dev/crypto session associated with the file-descriptor +argument. +.It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ; +.Bd -literal +struct crypt_sfop { + size_t count; + u_int32_t *sesid; +}; + +.Ed +Destroys the +.Fa sfop-\*[Gt]count +sessions specified by the +.Fa sfop +array of session identifiers. .El -.Sh FEATURES -Depending on hardware being present, the following symmetric and -asymmetric cryptographic features are potentially available from -.Pa /dev/crypto : +.\" +.Sh ASYMMETRIC-KEY OPERATION +.Ss Asymmetric-key algorithms +Contingent upon hardware support, the following asymmetric +(public-key/private-key; or key-exchange subroutine) operations may +also be available: .Pp -.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -offset indent -compact -.It Dv CRYPTO_DES_CBC -.It Dv CRYPTO_3DES_CBC -.It Dv CRYPTO_BLF_CBC -.It Dv CRYPTO_CAMELLIA_CBC -.It Dv CRYPTO_CAST_CBC -.It Dv CRYPTO_SKIPJACK_CBC -.It Dv CRYPTO_MD5_HMAC -.It Dv CRYPTO_SHA1_HMAC -.It Dv CRYPTO_RIPEMD160_HMAC -.It Dv CRYPTO_MD5_KPDK -.It Dv CRYPTO_SHA1_KPDK -.It Dv CRYPTO_AES_CBC -.It Dv CRYPTO_ARC4 -.It Dv CRYPTO_MD5 -.It Dv CRYPTO_SHA1 -.It Dv CRK_MOD_EXP -.It Dv CRK_MOD_EXP_CRT -.It Dv CRK_DSA_SIGN -.It Dv CRK_DSA_VERIFY -.It Dv CRK_DH_COMPUTE_KEY +.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact +.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" +.It Em " " Ta "Count" Ta "Count" +.It Dv CRK_MOD_EXP Ta 3 Ta 1 +.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 +.It Dv CRK_DSA_SIGN Ta 5 Ta 2 +.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 +.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 .El -.Sh FILES -.Bl -tag -width ".Pa /dev/crypto" -compact -.It Pa /dev/crypto -crypto access device +.Pp +See below for discussion of the input and output parameter counts. +.Ss Asymmetric-key commands +.Bl -tag -width CIOCKEY +.It Dv CIOCASYMFEAT Fa int *feature_mask +Returns a bitmask of supported asymmetric-key operations. +Each of the above-listed asymmetric operations is present +if and only if the bit position numbered by the code for that operation +is set. +For example, +.Dv CRK_MOD_EXP +is available if and only if the bit +.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP +is set. +.It Dv CIOCKEY Fa struct crypt_kop *kop +.Bd -literal +struct crypt_kop { + u_int crk_op; /* e.g. CRK_MOD_EXP */ + u_int crk_status; /* return status */ + u_short crk_iparams; /* # of input params */ + u_short crk_oparams; /* # of output params */ + u_int crk_pad1; + struct crparam crk_param[CRK_MAXPARAM]; +}; + +/* Bignum parameter, in packed bytes. */ +struct crparam { + void * crp_p; + u_int crp_nbits; +}; + +.Ed +Performs an asymmetric-key operation from the list above. +The specific operation is supplied in +.Fa kop-\*[Gt]crk_op ; +final status for the operation is returned in +.Fa kop-\*[Gt]crk_status . +The number of input arguments and the number of output arguments +is specified in +.Fa kop-\*[Gt]crk_iparams +and +.Fa kop-\*[Gt]crk_iparams , +respectively. +The field +.Fa crk_param[] +must be filled in with exactly +.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams +arguments, each encoded as a +.Fa struct crparam +(address, bitlength) pair. +.Pp +The semantics of these arguments are currently undocumented. .El .Sh SEE ALSO .Xr aesni 4 , @@ -113,6 +400,7 @@ crypto access device .Xr padlock 4 , .Xr safe 4 , .Xr ubsec 4 , +.Xr crypto 7 , .Xr geli 8 , .Xr crypto 9 .Sh HISTORY @@ -124,3 +412,24 @@ 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. +.Pp +The scheme for passing arguments for asymmetric requests is baroque. +.Pp +The naming inconsistency between +.Dv CRIOGET +and the various +.Dv CIOC Ns \&* +names is an unfortunate historical artifact. diff --git a/share/man/man4/inet.4 b/share/man/man4/inet.4 index 09cb0bc..6fe4e61 100644 --- a/share/man/man4/inet.4 +++ b/share/man/man4/inet.4 @@ -32,7 +32,7 @@ .\" From: @(#)inet.4 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd January 26, 2012 +.Dd Feb 4, 2016 .Dt INET 4 .Os .Sh NAME @@ -169,33 +169,11 @@ MIB. In addition to the variables supported by the transport protocols (for which the respective manual pages may be consulted), the following general variables are defined: -.Bl -tag -width IPCTL_FASTFORWARDING +.Bl -tag -width IPCTL_ACCEPTSOURCEROUTE .It Dv IPCTL_FORWARDING .Pq ip.forwarding Boolean: enable/disable forwarding of IP packets. Defaults to off. -.It Dv IPCTL_FASTFORWARDING -.Pq ip.fastforwarding -Boolean: enable/disable the use of -.Tn fast IP forwarding -code. -Defaults to off. -When -.Tn fast IP forwarding -is enabled, IP packets are forwarded directly to the appropriate network -interface with direct processing to completion, which greatly improves -the throughput. -All packets for local IP addresses, non-unicast, or with IP options are -handled by the normal IP input processing path. -All features of the normal (slow) IP forwarding path are supported -including firewall (through -.Xr pfil 9 -hooks) checking, except -.Xr ipsec 4 -tunnel brokering. -The -.Tn IP fastforwarding -path does not generate ICMP redirect or source quench messages. .It Dv IPCTL_SENDREDIRECTS .Pq ip.redirect Boolean: enable/disable sending of ICMP redirects in response to diff --git a/share/man/man7/Makefile b/share/man/man7/Makefile index 37afd65..93c14c6 100644 --- a/share/man/man7/Makefile +++ b/share/man/man7/Makefile @@ -9,6 +9,7 @@ MAN= adding_user.7 \ bsd.snmpmod.mk.7 \ build.7 \ clocks.7 \ + crypto.7 \ c99.7 \ development.7 \ environ.7 \ diff --git a/share/man/man7/crypto.7 b/share/man/man7/crypto.7 new file mode 100644 index 0000000..a268996 --- /dev/null +++ b/share/man/man7/crypto.7 @@ -0,0 +1,141 @@ +.\" Copyright (c) 2014 The FreeBSD Foundation +.\" All rights reserved. +.\" +.\" This documentation was written by John-Mark Gurney under +.\" the sponsorship of the FreeBSD Foundation and +.\" Rubicon Communications, LLC (Netgate). +.\" 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 AUTHOR 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 AUTHOR 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. +.\" +.\" $FreeBSD$ +.\" +.Dd December 12, 2014 +.Dt CRYPTO 7 +.Os +.Sh NAME +.Nm crypto +.Nd OpenCrypto algorithms +.Sh SYNOPSIS +In the kernel configuration file: +.Cd "device crypto" +.Pp +Or load the crypto.ko module. +.Sh DESCRIPTION +The following cryptographic algorithms that are part of the OpenCrypto +framework have the following requirements. +.Pp +Cipher algorithms: +.Bl -tag -width ".Dv CRYPTO_AES_CBC" +.It Dv CRYPTO_AES_CBC +.Bl -tag -width "Block size :" -compact -offset indent +.It IV size : +16 +.It Block size : +16 +.It Key size : +16, 24 or 32 +.El +.Pp +This algorithm implements Cipher-block chaining. +.It Dv CRYPTO_AES_NIST_GCM_16 +.Bl -tag -width "Block size :" -compact -offset indent +.It IV size : +12 +.It Block size : +1 +.It Key size : +16, 24 or 32 +.It Digest size : +16 +.El +.Pp +This algorithm implements Galois/Counter Mode. +This is the cipher part of an AEAD +.Pq Authenticated Encryption with Associated Data +mode. +This requires use of the use of a proper authentication mode, one of +.Dv CRYPTO_AES_128_NIST_GMAC , +.Dv CRYPTO_AES_192_NIST_GMAC +or +.Dv CRYPTO_AES_256_NIST_GMAC , +that corresponds with the number of bits in the key that you are using. +.Pp +The associated data (if any) must be provided by the authentication mode op. +The authentication tag will be read/written from/to the offset crd_inject +specified in the descriptor for the authentication mode. +.Pp +Note: You must provide an IV on every call. +.It Dv CRYPTO_AES_ICM +.Bl -tag -width "Block size :" -compact -offset indent +.It IV size : +16 +.It Block size : +1 (aesni), 16 (software) +.It Key size : +16, 24 or 32 +.El +.Pp +This algorithm implements Integer Counter Mode. +This is similar to what most people call counter mode, but instead of the +counter being split into a nonce and a counter part, then entire nonce is +used as the initial counter. +This does mean that if a counter is required that rolls over at 32 bits, +the transaction need to be split into two parts where the counter rolls over. +The counter incremented as a 128-bit big endian number. +.Pp +Note: You must provide an IV on every call. +.It Dv CRYPTO_AES_XTS +.Bl -tag -width "Block size :" -compact -offset indent +.It IV size : +16 +.It Block size : +16 +.It Key size : +32 or 64 +.El +.Pp +This algorithm implements XEX Tweakable Block Cipher with Ciphertext Stealing +as defined in NIST SP 800-38E. +.Pp +NOTE: The ciphertext stealing part is not implemented which is why this cipher +is listed as having a block size of 16 instead of 1. +.El +.Pp +Authentication algorithms: +.Bl -tag -width ".Dv CRYPTO_AES_256_NIST_GMAC" +.It CRYPTO_AES_128_NIST_GMAC +See +.Dv CRYPTO_AES_NIST_GCM_16 +in the cipher mode section. +.It CRYPTO_AES_192_NIST_GMAC +See +.Dv CRYPTO_AES_NIST_GCM_16 +in the cipher mode section. +.It CRYPTO_AES_256_NIST_GMAC +See +.Dv CRYPTO_AES_NIST_GCM_16 +in the cipher mode section. +.El +.Sh SEE ALSO +.Xr crypto 4 , +.Xr crypto 9 +.Sh BUGS +Not all the implemented algorithms are listed. diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9 index c2682af..2aaf130 100644 --- a/share/man/man9/crypto.9 +++ b/share/man/man9/crypto.9 @@ -175,17 +175,26 @@ Contains an algorithm identifier. Currently supported algorithms are: .Pp .Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact +.It Dv CRYPTO_AES_128_NIST_GMAC +.It Dv CRYPTO_AES_192_NIST_GMAC +.It Dv CRYPTO_AES_256_NIST_GMAC .It Dv CRYPTO_AES_CBC +.It Dv CRYPTO_AES_ICM +.It Dv CRYPTO_AES_NIST_GCM_16 +.It Dv CRYPTO_AES_NIST_GMAC +.It Dv CRYPTO_AES_XTS .It Dv CRYPTO_ARC4 .It Dv CRYPTO_BLF_CBC .It Dv CRYPTO_CAMELLIA_CBC .It Dv CRYPTO_CAST_CBC +.It Dv CRYPTO_DEFLATE_COMP .It Dv CRYPTO_DES_CBC .It Dv CRYPTO_3DES_CBC -.It Dv CRYPTO_SKIPJACK_CBC .It Dv CRYPTO_MD5 .It Dv CRYPTO_MD5_HMAC .It Dv CRYPTO_MD5_KPDK +.It Dv CRYPTO_NULL_HMAC +.It Dv CRYPTO_NULL_CBC .It Dv CRYPTO_RIPEMD160_HMAC .It Dv CRYPTO_SHA1 .It Dv CRYPTO_SHA1_HMAC @@ -193,8 +202,7 @@ Currently supported algorithms are: .It Dv CRYPTO_SHA2_256_HMAC .It Dv CRYPTO_SHA2_384_HMAC .It Dv CRYPTO_SHA2_512_HMAC -.It Dv CRYPTO_NULL_HMAC -.It Dv CRYPTO_NULL_CBC +.It Dv CRYPTO_SKIPJACK_CBC .El .It Va cri_klen Specifies the length of the key in bits, for variable-size key @@ -207,7 +215,8 @@ Contains the key to be used with the algorithm. .It Va cri_iv Contains an explicit initialization vector (IV), if it does not prefix the data. -This field is ignored during initialization. +This field is ignored during initialization +.Pq Nm crypto_newsession . If no IV is explicitly passed (see below on details), a random IV is used by the device driver processing the request. .It Va cri_next @@ -296,8 +305,6 @@ The buffer pointed to by is an .Vt uio structure. -.It Dv CRYPTO_F_REL -Must return data in the same place. .It Dv CRYPTO_F_BATCH Batch operation if possible. .It Dv CRYPTO_F_CBIMM @@ -363,7 +370,7 @@ The following flags are defined: For encryption algorithms, this bit is set when encryption is required (when not set, decryption is performed). .It Dv CRD_F_IV_PRESENT -For encryption algorithms, this bit is set when the IV already +For encryption, this bit is set when the IV already precedes the data, so the .Va crd_inject value will be ignored and no IV will be written in the buffer. @@ -372,7 +379,7 @@ at the location pointed to by .Va crd_inject . The IV length is assumed to be equal to the blocksize of the encryption algorithm. -Some applications that do special +Applications that do special .Dq "IV cooking" , such as the half-IV mode in .Xr ipsec 4 , @@ -403,6 +410,8 @@ field for the given operation. Otherwise, the key is taken at newsession time from the .Va cri_key field. +As calculating the key schedule may take a while, it is recommended that often +used keys are given their own session. .It Dv CRD_F_COMP For compression algorithms, this bit is set when compression is required (when not set, decompression is performed). @@ -641,6 +650,7 @@ most of the framework code .El .Sh SEE ALSO .Xr ipsec 4 , +.Xr crypto 7 , .Xr malloc 9 , .Xr sleep 9 .Sh HISTORY |
