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