Date: Thu, 21 Jan 2021 00:40:20 GMT From: John Baldwin <jhb@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org Subject: git: 4a6cd37b755c - main - Restructure the crypto(7) manpage and add authentication algorithms. Message-ID: <202101210040.10L0eKS6095266@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch main has been updated by jhb: URL: https://cgit.FreeBSD.org/src/commit/?id=4a6cd37b755c404122453a82263f15323ecce56b commit 4a6cd37b755c404122453a82263f15323ecce56b Author: John Baldwin <jhb@FreeBSD.org> AuthorDate: 2021-01-21 00:37:55 +0000 Commit: John Baldwin <jhb@FreeBSD.org> CommitDate: 2021-01-21 00:40:03 +0000 Restructure the crypto(7) manpage and add authentication algorithms. Add separate sections for authentication algorithms, block ciphers, stream ciphers, and AEAD algorithms. Describe properties commmon to algorithms in each section to avoid duplication. Use flat tables to list algorithm properties rather than nested tables. List implemented authentication algorithms. Reviewed by: gbe (manpages) Sponsored by: Netflix Differential Revision: https://reviews.freebsd.org/D27833 --- share/man/man7/crypto.7 | 230 +++++++++++++++++++++++------------------------- 1 file changed, 112 insertions(+), 118 deletions(-) diff --git a/share/man/man7/crypto.7 b/share/man/man7/crypto.7 index 609eb574995e..d6cae1e39819 100644 --- a/share/man/man7/crypto.7 +++ b/share/man/man7/crypto.7 @@ -27,144 +27,140 @@ .\" .\" $FreeBSD$ .\" -.Dd June 4, 2020 +.Dd January 20, 2021 .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 "CRYPTO_AES_NIST_GCM_16" -.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 +The in-kernel OpenCrypto framework supports several different encryption +and authentication algorithms. +This document describes the parameters and requirements of these algorithms. +Unless otherwise noted, all sizes listed below are in bytes. +.Ss Authenticators +Authenticators compute a value (also known as a digest, hash, or tag) +over an input of bytes. +In-kernel requests can either compute the value for a given input, +or verify if a given tag matches the computed tag for a given input. +The following authentication algorithms are supported: +.Bl -column "CRYPTO_AES_CCM_CBC_MAC" "XXX" "16, 24, 32" "Digest" +.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Digest Ta Sy Description +.It Dv CRYPTO_AES_CCM_CBC_MAC Ta 12 Ta 16, 24, 32 Ta 16 Ta +Authentication-only mode of AES-CCM +.It Dv CRYPTO_AES_NIST_GMAC Ta 12 Ta 16, 24, 32 Ta 16 Ta +Galois message authentication code +.It Dv CRYPTO_BLAKE2B Ta Ta 0, 64 Ta 64 Ta +Blake2b +.It Dv CRYPTO_BLAKE2S Ta Ta 0, 32 Ta 32 Ta +Blake2s +.It Dv CRYPTO_NULL_HMAC Ta Ta Ta 12 Ta +IPsec NULL HMAC +.It Dv CRYPTO_POLY1305 Ta Ta 32 Ta 16 Ta +Poly1305 authenticator +.It Dv CRYPTO_RIPEMD160 Ta Ta Ta 20 Ta +RIPE Message Digest-160 +.It Dv CRYPTO_RIPEMD160_HMAC Ta Ta 64 Ta 20 Ta +RIPE Message Digest-160 HMAC +.It Dv CRYPTO_SHA1 Ta Ta Ta 20 Ta +SHA-1 +.It Dv CRYPTO_SHA1_HMAC Ta Ta 64 Ta 20 Ta +SHA-1 HMAC +.It Dv CRYPTO_SHA2_224 Ta Ta Ta 28 Ta +SHA-2 224 +.It Dv CRYPTO_SHA2_224_HMAC Ta Ta 64 Ta 28 Ta +SHA-2 224 HMAC +.It Dv CRYPTO_SHA2_256 Ta Ta Ta 32 Ta +SHA-2 256 +.It Dv CRYPTO_SHA2_256_HMAC Ta Ta 64 Ta 32 Ta +SHA-2 256 HMAC +.It Dv CRYPTO_SHA2_384 Ta Ta Ta 48 Ta +SHA-2 384 +.It Dv CRYPTO_SHA2_384_HMAC Ta Ta 128 Ta 48 Ta +SHA-2 384 HMAC +.It Dv CRYPTO_SHA2_512 Ta Ta Ta 64 Ta +SHA-2 512 +.It Dv CRYPTO_SHA2_512_HMAC Ta Ta 128 Ta 64 Ta +SHA-2 512 HMAC .El -.Pp -This algorithm implements Cipher Block Chaining. -.It Dv CRYPTO_AES_CCM_16 -.Bl -tag -width "Block size :" -compact -offset indent -.It IV size : -12 -.It Block size : -16 -.It Key size : -16, 24 or 32 -.It Digest size : -16 +.Ss Block Ciphers +Block ciphers in OCF can only operate on messages whose length is an +exact multiple of the cipher's block size. +OCF supports the following block ciphers: +.Bl -column "CRYPTO_CAMELLIA_CBC" "IV Size" "Block Size" "16, 24, 32" +.It Sy Name Ta Sy IV Size Ta Sy Block Size Ta Sy Key Sizes Ta Sy Description +.It Dv CRYPTO_AES_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta +AES-CBC +.It Dv CRYPTO_AES_XTS Ta 8 Ta 16 Ta 32, 64 Ta +AES-XTS +.It Dv CRYPTO_CAMELLIA_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta +Camellia CBC +.It Dv CRYPTO_NULL_CBC Ta 0 Ta 4 Ta 0-256 Ta +IPsec NULL cipher .El .Pp -This algorithm implements Counter with CBC-MAC Mode. -This cipher uses AEAD -.Pq Authenticated Encryption with Associated Data -mode. -.Pp -The authentication tag will be read from or written to the offset -.Va crp_digest_start -specified in the request. +.Dv CRYPTO_AES_XTS +implements XEX Tweakable Block Cipher with Ciphertext Stealing +as defined in NIST SP 800-38E. +OCF consumers provide the first 8 bytes of the IV. +The remaining 8 bytes are defined to be a block counter beginning at 0. .Pp -Note: The nonce for each request must be provided in -.Fa crp_iv -via the -.Dv CRYPTO_F_IV_SEPARATE -flag. -.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 +NOTE: The ciphertext stealing part is not implemented in all backends +which is why this cipher requires input that is a multiple of the block +size. +.Ss Stream Ciphers +Stream ciphers can operate on messages with arbitrary lengths. +OCF supports the following stream ciphers: +.Bl -column "CRYPTO_CHACHA20" "IV Size" "16, 24, 32" +.It Sy Name Ta Sy IV Size Ta Sy Key Sizes Ta Sy Description +.It Dv CRYPTO_AES_ICM Ta 16 Ta 16, 24, 32 Ta +AES Counter Mode +.It Dv CRYPTO_CHACHA20 Ta 16 Ta 16, 32 Ta +ChaCha20 .El .Pp -This algorithm implements Galois/Counter Mode. -This cipher uses AEAD -.Pq Authenticated Encryption with Associated Data -mode. -.Pp -The authentication tag will be read from or written to the offset -.Va crp_digest_start -specified in the request. -.Pp -Note: The nonce for each request must be provided in +The IV for each request must be provided in .Fa crp_iv via the .Dv CRYPTO_F_IV_SEPARATE flag. -.It Dv CRYPTO_AES_ICM -.Bl -tag -width "Block size :" -compact -offset indent -.It IV size : -16 -.It Block size : -1 -.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. +.Dv CRYPTO_AES_ICM +uses the entire IV as a 128-bit big endian block counter. +The IV sets the initial counter value for a message. +If a consumer wishes to use an IV whose value is split into +separate nonce and counter fields (e.g., IPsec), +the consumer is responsible for splitting requests to handle +counter rollover. +.Pp +.Dv CRYPTO_CHACHA20 +accepts a 16 byte IV. +The first 8 bytes are used as a nonce. +The last 8 bytes are used as 64-bit big-endian block counter. +.Ss Authenticated Encryption with Associated Data Algorithms +AEAD algorithms in OCF combine a stream cipher with an authentication +algorithm to provide both secrecy and authentication. +AEAD algorithms accept additional authentication data (AAD) +in addition to the ciphertext or plaintext. +AAD is passed to the authentication algorithm as input in a method +defined by the specific AEAD algorithm. .Pp -Note: The counter for each request must be provided in +AEAD algorithms in OCF accept a nonce that is combined with an +algorithm-defined counter to construct the IV for the underlying +stream cipher. +This nonce must be provided in .Fa crp_iv via the .Dv CRYPTO_F_IV_SEPARATE flag. -.It Dv CRYPTO_AES_XTS -.Bl -tag -width "Block size :" -compact -offset indent -.It IV size : -8 -.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. -.It Dv CRYPTO_CAMELLIA_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_CHACHA20 -.Bl -tag -width "Block size :" -compact -offset indent -.It IV size : -16 -.It Block size : -1 -.It Key size : -16 or 32 -.El +The following AEAD algorithms are supported: +.Bl -column "CRYPTO_AES_NIST_GCM_16" "Nonce" "16, 24, 32" "Tag" +.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Tag Ta Sy Description +.It Dv CRYPTO_AES_NIST_GCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta +AES Galois/Counter Mode +.It Dv CRYPTO_AES_CCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta +AES Counter with CBC-MAC .El .Sh SEE ALSO .Xr crypto 4 , @@ -172,7 +168,5 @@ This algorithm implements Cipher Block Chaining. .Sh HISTORY The .Nm -manpage first appeared in +manual page first appeared in .Fx 10.1 . -.Sh BUGS -Not all the implemented algorithms are listed.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202101210040.10L0eKS6095266>