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