1.\" Copyright (c) 2014-2021 The FreeBSD Foundation 2.\" 3.\" Portions of this documentation were written by John-Mark Gurney 4.\" under the sponsorship of the FreeBSD Foundation and 5.\" Rubicon Communications, LLC (Netgate). 6.\" 7.\" Portions of this documentation were written by Ararat River 8.\" Consulting, LLC under sponsorship of the FreeBSD Foundation. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" $FreeBSD$ 32.\" 33.Dd January 11, 2022 34.Dt CRYPTO 7 35.Os 36.Sh NAME 37.Nm crypto 38.Nd OpenCrypto algorithms 39.Sh DESCRIPTION 40The in-kernel OpenCrypto framework supports several different encryption 41and authentication algorithms. 42This document describes the parameters and requirements of these algorithms. 43Unless otherwise noted, all sizes listed below are in bytes. 44.Ss Authenticators 45Authenticators compute a value (also known as a digest, hash, or tag) 46over an input of bytes. 47In-kernel requests can either compute the value for a given input, 48or verify if a given tag matches the computed tag for a given input. 49The following authentication algorithms are supported: 50.Bl -column "CRYPTO_AES_CCM_CBC_MAC" "XXX" "16, 24, 32" "Digest" 51.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Digest Ta Sy Description 52.It Dv CRYPTO_AES_CCM_CBC_MAC Ta 12 Ta 16, 24, 32 Ta 16 Ta 53Authentication-only mode of AES-CCM 54.It Dv CRYPTO_AES_NIST_GMAC Ta 12 Ta 16, 24, 32 Ta 16 Ta 55Galois message authentication code 56.It Dv CRYPTO_BLAKE2B Ta Ta 0, 64 Ta 64 Ta 57Blake2b 58.It Dv CRYPTO_BLAKE2S Ta Ta 0, 32 Ta 32 Ta 59Blake2s 60.It Dv CRYPTO_NULL_HMAC Ta Ta Ta 12 Ta 61IPsec NULL HMAC 62.It Dv CRYPTO_POLY1305 Ta Ta 32 Ta 16 Ta 63Poly1305 authenticator 64.It Dv CRYPTO_RIPEMD160 Ta Ta Ta 20 Ta 65RIPE Message Digest-160 66.It Dv CRYPTO_RIPEMD160_HMAC Ta Ta 64 Ta 20 Ta 67RIPE Message Digest-160 HMAC 68.It Dv CRYPTO_SHA1 Ta Ta Ta 20 Ta 69SHA-1 70.It Dv CRYPTO_SHA1_HMAC Ta Ta 64 Ta 20 Ta 71SHA-1 HMAC 72.It Dv CRYPTO_SHA2_224 Ta Ta Ta 28 Ta 73SHA-2 224 74.It Dv CRYPTO_SHA2_224_HMAC Ta Ta 64 Ta 28 Ta 75SHA-2 224 HMAC 76.It Dv CRYPTO_SHA2_256 Ta Ta Ta 32 Ta 77SHA-2 256 78.It Dv CRYPTO_SHA2_256_HMAC Ta Ta 64 Ta 32 Ta 79SHA-2 256 HMAC 80.It Dv CRYPTO_SHA2_384 Ta Ta Ta 48 Ta 81SHA-2 384 82.It Dv CRYPTO_SHA2_384_HMAC Ta Ta 128 Ta 48 Ta 83SHA-2 384 HMAC 84.It Dv CRYPTO_SHA2_512 Ta Ta Ta 64 Ta 85SHA-2 512 86.It Dv CRYPTO_SHA2_512_HMAC Ta Ta 128 Ta 64 Ta 87SHA-2 512 HMAC 88.El 89.Ss Block Ciphers 90Block ciphers in OCF can only operate on messages whose length is an 91exact multiple of the cipher's block size. 92OCF supports the following block ciphers: 93.Bl -column "CRYPTO_CAMELLIA_CBC" "IV Size" "Block Size" "16, 24, 32" 94.It Sy Name Ta Sy IV Size Ta Sy Block Size Ta Sy Key Sizes Ta Sy Description 95.It Dv CRYPTO_AES_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta 96AES-CBC 97.It Dv CRYPTO_AES_XTS Ta 8 Ta 16 Ta 32, 64 Ta 98AES-XTS 99.It Dv CRYPTO_CAMELLIA_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta 100Camellia CBC 101.It Dv CRYPTO_NULL_CBC Ta 0 Ta 4 Ta 0-256 Ta 102IPsec NULL cipher 103.El 104.Pp 105.Dv CRYPTO_AES_XTS 106implements XEX Tweakable Block Cipher with Ciphertext Stealing 107as defined in NIST SP 800-38E. 108OCF consumers provide the first 8 bytes of the IV. 109The remaining 8 bytes are defined to be a block counter beginning at 0. 110.Pp 111NOTE: The ciphertext stealing part is not implemented in all backends 112which is why this cipher requires input that is a multiple of the block 113size. 114.Ss Stream Ciphers 115Stream ciphers can operate on messages with arbitrary lengths. 116OCF supports the following stream ciphers: 117.Bl -column "CRYPTO_CHACHA20" "IV Size" "16, 24, 32" 118.It Sy Name Ta Sy IV Size Ta Sy Key Sizes Ta Sy Description 119.It Dv CRYPTO_AES_ICM Ta 16 Ta 16, 24, 32 Ta 120AES Counter Mode 121.It Dv CRYPTO_CHACHA20 Ta 16 Ta 16, 32 Ta 122ChaCha20 123.El 124.Pp 125The IV for each request must be provided in 126.Fa crp_iv 127via the 128.Dv CRYPTO_F_IV_SEPARATE 129flag. 130.Pp 131.Dv CRYPTO_AES_ICM 132uses the entire IV as a 128-bit big endian block counter. 133The IV sets the initial counter value for a message. 134If a consumer wishes to use an IV whose value is split into 135separate nonce and counter fields (e.g., IPsec), 136the consumer is responsible for splitting requests to handle 137counter rollover. 138.Pp 139.Dv CRYPTO_CHACHA20 140accepts a 16 byte IV. 141The first 8 bytes are used as a nonce. 142The last 8 bytes are used as a 64-bit little-endian block counter. 143.Ss Authenticated Encryption with Associated Data Algorithms 144AEAD algorithms in OCF combine a stream cipher with an authentication 145algorithm to provide both secrecy and authentication. 146AEAD algorithms accept additional authentication data (AAD) 147in addition to the ciphertext or plaintext. 148AAD is passed to the authentication algorithm as input in a method 149defined by the specific AEAD algorithm. 150.Pp 151AEAD algorithms in OCF accept a nonce that is combined with an 152algorithm-defined counter to construct the IV for the underlying 153stream cipher. 154This nonce must be provided in 155.Fa crp_iv 156via the 157.Dv CRYPTO_F_IV_SEPARATE 158flag. 159Some AEAD algorithms support multiple nonce sizes. 160The first size listed is the default nonce size. 161.Pp 162The following AEAD algorithms are supported: 163.Bl -column "CRYPTO_AES_NIST_GCM_16" "12, 7-13" "16, 24, 32" "Tag" 164.It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Tag Ta Sy Description 165.It Dv CRYPTO_AES_NIST_GCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta 166AES Galois/Counter Mode 167.It Dv CRYPTO_AES_CCM_16 Ta 12, 7-13 Ta 16, 24, 32 Ta 16 Ta 168AES Counter with CBC-MAC 169.It Dv CRYPTO_CHACHA20_POLY1305 Ta 12, 8 Ta 32 Ta 16 Ta 170ChaCha20-Poly1305 171.It Dv CRYPTO_XCHACHA20_POLY1305 Ta 24 Ta 32 Ta 16 Ta 172XChaCha20-Poly1305 173.El 174.Sh SEE ALSO 175.Xr crypto 4 , 176.Xr crypto 9 177.Sh HISTORY 178The 179.Nm 180manual page first appeared in 181.Fx 10.1 . 182