share/man/man7/crypto.7

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