share/man/man7/crypto.7

   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
  40 The in-kernel OpenCrypto framework supports several different encryption
  41 and authentication algorithms.
  42 This document describes the parameters and requirements of these algorithms.
  43 Unless otherwise noted, all sizes listed below are in bytes.
  44 .Ss Authenticators
  45 Authenticators compute a value (also known as a digest, hash, or tag)
  46 over an input of bytes.
  47 In-kernel requests can either compute the value for a given input,
  48 or verify if a given tag matches the computed tag for a given input.
  49 The 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
  53 Authentication-only mode of AES-CCM
  54 .It Dv CRYPTO_AES_NIST_GMAC Ta 12 Ta 16, 24, 32 Ta 16 Ta
  55 Galois message authentication code
  56 .It Dv CRYPTO_BLAKE2B Ta Ta 0, 64 Ta 64 Ta
  57 Blake2b
  58 .It Dv CRYPTO_BLAKE2S Ta Ta 0, 32 Ta 32 Ta
  59 Blake2s
  60 .It Dv CRYPTO_NULL_HMAC Ta Ta Ta 12 Ta
  61 IPsec NULL HMAC
  62 .It Dv CRYPTO_POLY1305 Ta Ta 32 Ta 16 Ta
  63 Poly1305 authenticator
  64 .It Dv CRYPTO_RIPEMD160 Ta Ta Ta 20 Ta
  65 RIPE Message Digest-160
  66 .It Dv CRYPTO_RIPEMD160_HMAC Ta Ta 64 Ta 20 Ta
  67 RIPE Message Digest-160 HMAC
  68 .It Dv CRYPTO_SHA1 Ta Ta Ta 20 Ta
  69 SHA-1
  70 .It Dv CRYPTO_SHA1_HMAC Ta Ta 64 Ta 20 Ta
  71 SHA-1 HMAC
  72 .It Dv CRYPTO_SHA2_224 Ta Ta Ta 28 Ta
  73 SHA-2 224
  74 .It Dv CRYPTO_SHA2_224_HMAC Ta Ta 64 Ta 28 Ta
  75 SHA-2 224 HMAC
  76 .It Dv CRYPTO_SHA2_256 Ta Ta Ta 32 Ta
  77 SHA-2 256
  78 .It Dv CRYPTO_SHA2_256_HMAC Ta Ta 64 Ta 32 Ta
  79 SHA-2 256 HMAC
  80 .It Dv CRYPTO_SHA2_384 Ta Ta Ta 48 Ta
  81 SHA-2 384
  82 .It Dv CRYPTO_SHA2_384_HMAC Ta Ta 128 Ta 48 Ta
  83 SHA-2 384 HMAC
  84 .It Dv CRYPTO_SHA2_512 Ta Ta Ta 64 Ta
  85 SHA-2 512
  86 .It Dv CRYPTO_SHA2_512_HMAC Ta Ta 128 Ta 64 Ta
  87 SHA-2 512 HMAC
  88 .El
  89 .Ss Block Ciphers
  90 Block ciphers in OCF can only operate on messages whose length is an
  91 exact multiple of the cipher's block size.
  92 OCF 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
  96 AES-CBC
  97 .It Dv CRYPTO_AES_XTS Ta 8 Ta 16 Ta 32, 64 Ta
  98 AES-XTS
  99 .It Dv CRYPTO_CAMELLIA_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta
 100 Camellia CBC
 101 .It Dv CRYPTO_NULL_CBC Ta 0 Ta 4 Ta 0-256 Ta
 102 IPsec NULL cipher
 103 .El
 104 .Pp
 105 .Dv CRYPTO_AES_XTS
 106 implements XEX Tweakable Block Cipher with Ciphertext Stealing
 107 as defined in NIST SP 800-38E.
 108 OCF consumers provide the first 8 bytes of the IV.
 109 The remaining 8 bytes are defined to be a block counter beginning at 0.
 110 .Pp
 111 NOTE: The ciphertext stealing part is not implemented in all backends
 112 which is why this cipher requires input that is a multiple of the block
 113 size.
 114 .Ss Stream Ciphers
 115 Stream ciphers can operate on messages with arbitrary lengths.
 116 OCF 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
 120 AES Counter Mode
 121 .It Dv CRYPTO_CHACHA20 Ta 16 Ta 16, 32 Ta
 122 ChaCha20
 123 .El
 124 .Pp
 125 The IV for each request must be provided in
 126 .Fa crp_iv
 127 via the
 128 .Dv CRYPTO_F_IV_SEPARATE
 129 flag.
 130 .Pp
 131 .Dv CRYPTO_AES_ICM
 132 uses the entire IV as a 128-bit big endian block counter.
 133 The IV sets the initial counter value for a message.
 134 If a consumer wishes to use an IV whose value is split into
 135 separate nonce and counter fields (e.g., IPsec),
 136 the consumer is responsible for splitting requests to handle
 137 counter rollover.
 138 .Pp
 139 .Dv CRYPTO_CHACHA20
 140 accepts a 16 byte IV.
 141 The first 8 bytes are used as a nonce.
 142 The last 8 bytes are used as a 64-bit little-endian block counter.
 143 .Ss Authenticated Encryption with Associated Data Algorithms
 144 AEAD algorithms in OCF combine a stream cipher with an authentication
 145 algorithm to provide both secrecy and authentication.
 146 AEAD algorithms accept additional authentication data (AAD)
 147 in addition to the ciphertext or plaintext.
 148 AAD is passed to the authentication algorithm as input in a method
 149 defined by the specific AEAD algorithm.
 150 .Pp
 151 AEAD algorithms in OCF accept a nonce that is combined with an
 152 algorithm-defined counter to construct the IV for the underlying
 153 stream cipher.
 154 This nonce must be provided in
 155 .Fa crp_iv
 156 via the
 157 .Dv CRYPTO_F_IV_SEPARATE
 158 flag.
 159 Some AEAD algorithms support multiple nonce sizes.
 160 The first size listed is the default nonce size.
 161 .Pp
 162 The 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
 166 AES Galois/Counter Mode
 167 .It Dv CRYPTO_AES_CCM_16 Ta 12, 7-13 Ta 16, 24, 32 Ta 16 Ta
 168 AES Counter with CBC-MAC
 169 .It Dv CRYPTO_CHACHA20_POLY1305 Ta 12, 8 Ta 32 Ta 16 Ta
 170 ChaCha20-Poly1305
 171 .It Dv CRYPTO_XCHACHA20_POLY1305 Ta 24 Ta 32 Ta 16 Ta
 172 XChaCha20-Poly1305
 173 .El
 174 .Sh SEE ALSO
 175 .Xr crypto 4 ,
 176 .Xr crypto 9
 177 .Sh HISTORY
 178 The
 179 .Nm
 180 manual page first appeared in
 181 .Fx 10.1 .