Changeset View
Changeset View
Standalone View
Standalone View
share/man/man7/crypto.7
Show All 21 Lines | |||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||
.\" | .\" | ||||||||
.\" $FreeBSD$ | .\" $FreeBSD$ | ||||||||
.\" | .\" | ||||||||
.Dd June 4, 2020 | .Dd June 4, 2020 | ||||||||
debdrup: Since @bcr hasn't been here yet, I get to remind someone else to remember to bump .Dd ;) | |||||||||
Done Inline Actions
I don't bother bumping until the commit date since it is always stale during review otherwise. jhb: > Since @bcr hasn't been here yet, I get to remind someone else to remember to bump .Dd ;)
I… | |||||||||
.Dt CRYPTO 7 | .Dt CRYPTO 7 | ||||||||
.Os | .Os | ||||||||
.Sh NAME | .Sh NAME | ||||||||
.Nm crypto | .Nm crypto | ||||||||
.Nd OpenCrypto algorithms | .Nd OpenCrypto algorithms | ||||||||
.Sh SYNOPSIS | |||||||||
In the kernel configuration file: | |||||||||
.Cd "device crypto" | |||||||||
.Pp | |||||||||
Or load the crypto.ko module. | |||||||||
.Sh DESCRIPTION | .Sh DESCRIPTION | ||||||||
The following cryptographic algorithms that are part of the OpenCrypto | The in-kernel OpenCrypto framework supports several different encryption | ||||||||
framework have the following requirements. | and authentication algorithms. | ||||||||
.Pp | This document describes the parameters and requirements of these algorithms. | ||||||||
Cipher algorithms: | Unless otherwise noted, all sizes listed below are in bytes. | ||||||||
.Bl -tag -width "CRYPTO_AES_NIST_GCM_16" | .Ss Authenticators | ||||||||
.It Dv CRYPTO_AES_CBC | Authenticators compute a value (also known as a digest, hash, or tag) | ||||||||
.Bl -tag -width "Block size :" -compact -offset indent | over an input of bytes. | ||||||||
.It IV size : | In-kernel requests can either compute the value for a given input, | ||||||||
16 | or verify if a given tag matches the computed tag for a given input. | ||||||||
.It Block size : | The following authentication algorithms are supported: | ||||||||
16 | .Bl -column "CRYPTO_AES_CCM_CBC_MAC" "XXX" "16, 24, 32" "Digest" | ||||||||
.It Key size : | .It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Digest Ta Sy Description | ||||||||
16, 24 or 32 | .It Dv CRYPTO_AES_CCM_CBC_MAC Ta 12 Ta 16, 24, 32 Ta 16 Ta | ||||||||
Authentication-only mode of AES-CCM | |||||||||
.It Dv CRYPTO_AES_NIST_GMAC Ta 12 Ta 16, 24, 32 Ta 16 Ta | |||||||||
Galois message authentication code | |||||||||
.It Dv CRYPTO_BLAKE2B Ta Ta 0, 64 Ta 64 Ta | |||||||||
Blake2b | |||||||||
.It Dv CRYPTO_BLAKE2S Ta Ta 0, 32 Ta 32 Ta | |||||||||
Blake2s | |||||||||
.It Dv CRYPTO_NULL_HMAC Ta Ta Ta 12 Ta | |||||||||
IPsec NULL HMAC | |||||||||
.It Dv CRYPTO_POLY1305 Ta Ta 32 Ta 16 Ta | |||||||||
Poly1305 authenticator | |||||||||
.It Dv CRYPTO_RIPEMD160 Ta Ta Ta 20 Ta | |||||||||
RIPE Message Digest-160 | |||||||||
.It Dv CRYPTO_RIPEMD160_HMAC Ta Ta 64 Ta 20 Ta | |||||||||
RIPE Message Digest-160 HMAC | |||||||||
.It Dv CRYPTO_SHA1 Ta Ta Ta 20 Ta | |||||||||
SHA-1 | |||||||||
.It Dv CRYPTO_SHA1_HMAC Ta Ta 64 Ta 20 Ta | |||||||||
SHA-1 HMAC | |||||||||
.It Dv CRYPTO_SHA2_224 Ta Ta Ta 28 Ta | |||||||||
SHA-2 224 | |||||||||
.It Dv CRYPTO_SHA2_224_HMAC Ta Ta 64 Ta 28 Ta | |||||||||
SHA-2 224 HMAC | |||||||||
.It Dv CRYPTO_SHA2_256 Ta Ta Ta 32 Ta | |||||||||
SHA-2 256 | |||||||||
.It Dv CRYPTO_SHA2_256_HMAC Ta Ta 64 Ta 32 Ta | |||||||||
SHA-2 256 HMAC | |||||||||
.It Dv CRYPTO_SHA2_384 Ta Ta Ta 48 Ta | |||||||||
SHA-2 384 | |||||||||
.It Dv CRYPTO_SHA2_384_HMAC Ta Ta 128 Ta 48 Ta | |||||||||
SHA-2 384 HMAC | |||||||||
.It Dv CRYPTO_SHA2_512 Ta Ta Ta 64 Ta | |||||||||
SHA-2 512 | |||||||||
.It Dv CRYPTO_SHA2_512_HMAC Ta Ta 128 Ta 64 Ta | |||||||||
SHA-2 512 HMAC | |||||||||
.El | .El | ||||||||
.Pp | .Ss Block Ciphers | ||||||||
This algorithm implements Cipher Block Chaining. | Block ciphers in OCF can only operate on messages whose length is an | ||||||||
.It Dv CRYPTO_AES_CCM_16 | exact multiple of the cipher's block size. | ||||||||
.Bl -tag -width "Block size :" -compact -offset indent | OCF supports the following block ciphers: | ||||||||
.It IV size : | .Bl -column "CRYPTO_CAMELLIA_CBC" "IV Size" "Block Size" "16, 24, 32" | ||||||||
12 | .It Sy Name Ta Sy IV Size Ta Sy Block Size Ta Sy Key Sizes Ta Sy Description | ||||||||
.It Block size : | .It Dv CRYPTO_AES_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta | ||||||||
16 | AES-CBC | ||||||||
.It Key size : | .It Dv CRYPTO_AES_XTS Ta 8 Ta 16 Ta 32, 64 Ta | ||||||||
16, 24 or 32 | AES-XTS | ||||||||
.It Digest size : | .It Dv CRYPTO_CAMELLIA_CBC Ta 16 Ta 16 Ta 16, 24, 32 Ta | ||||||||
16 | Camellia CBC | ||||||||
.It Dv CRYPTO_NULL_CBC Ta 0 Ta 4 Ta 0-256 Ta | |||||||||
IPsec NULL cipher | |||||||||
.El | .El | ||||||||
.Pp | .Pp | ||||||||
This algorithm implements Counter with CBC-MAC Mode. | .Dv CRYPTO_AES_XTS | ||||||||
This cipher uses AEAD | implements XEX Tweakable Block Cipher with Ciphertext Stealing | ||||||||
.Pq Authenticated Encryption with Associated Data | as defined in NIST SP 800-38E. | ||||||||
mode. | OCF consumers provide the first 8 bytes of the IV. | ||||||||
The remaining 8 bytes are defined to be a block counter beginning at 0. | |||||||||
.Pp | .Pp | ||||||||
The authentication tag will be read from or written to the offset | NOTE: The ciphertext stealing part is not implemented in all backends | ||||||||
.Va crp_digest_start | which is why this cipher requires input that is a multiple of the block | ||||||||
specified in the request. | size. | ||||||||
.Ss Stream Ciphers | |||||||||
Stream ciphers can operate on messages with arbitrary lengths. | |||||||||
OCF supports the following stream ciphers: | |||||||||
.Bl -column "CRYPTO_CHACHA20" "IV Size" "16, 24, 32" | |||||||||
.It Sy Name Ta Sy IV Size Ta Sy Key Sizes Ta Sy Description | |||||||||
.It Dv CRYPTO_AES_ICM Ta 16 Ta 16, 24, 32 Ta | |||||||||
AES Counter Mode | |||||||||
.It Dv CRYPTO_CHACHA20 Ta 16 Ta 16, 32 Ta | |||||||||
ChaCha20 | |||||||||
.El | |||||||||
.Pp | .Pp | ||||||||
Note: The nonce for each request must be provided in | The IV for each request must be provided in | ||||||||
.Fa crp_iv | .Fa crp_iv | ||||||||
via the | via the | ||||||||
.Dv CRYPTO_F_IV_SEPARATE | .Dv CRYPTO_F_IV_SEPARATE | ||||||||
flag. | flag. | ||||||||
.It Dv CRYPTO_AES_NIST_GCM_16 | |||||||||
.Bl -tag -width "Block size :" -compact -offset indent | |||||||||
.It IV size : | |||||||||
12 | |||||||||
.It Block size : | |||||||||
1 | |||||||||
.It Key size : | |||||||||
16, 24 or 32 | |||||||||
.It Digest size : | |||||||||
16 | |||||||||
.El | |||||||||
.Pp | .Pp | ||||||||
This algorithm implements Galois/Counter Mode. | .Dv CRYPTO_AES_ICM | ||||||||
This cipher uses AEAD | uses the entire IV as a 128-bit big endian block counter. | ||||||||
.Pq Authenticated Encryption with Associated Data | The IV sets the initial counter value for a message. | ||||||||
mode. | If a consumer wishes to use an IV whose value is split into | ||||||||
separate nonce and counter fields (e.g., IPsec), | |||||||||
Done Inline Actions
Missing comma. 0mp: Missing comma. | |||||||||
Done Inline Actions
Is it also better to spell out "for example" explicitly? jhb: > Missing comma.
Is it also better to spell out "for example" explicitly? | |||||||||
the consumer is responsible for splitting requests to handle | |||||||||
counter rollover. | |||||||||
.Pp | .Pp | ||||||||
The authentication tag will be read from or written to the offset | .Dv CRYPTO_CHACHA20 | ||||||||
.Va crp_digest_start | accepts a 16 byte IV. | ||||||||
specified in the request. | The first 8 bytes are used as a nonce. | ||||||||
The last 8 bytes are used as 64-bit big-endian block counter. | |||||||||
.Ss Authenticated Encryption with Associated Data Algorithms | |||||||||
AEAD algorithms in OCF combine a stream cipher with an authentication | |||||||||
algorithm to provide both secrecy and authentication. | |||||||||
AEAD algorithms accept additional authentication data (AAD) | |||||||||
in addition to the ciphertext or plaintext. | |||||||||
AAD is passed to the authentication algorithm as input in a method | |||||||||
defined by the specific AEAD algorithm. | |||||||||
.Pp | .Pp | ||||||||
Note: The nonce for each request must be provided in | AEAD algorithms in OCF accept a nonce that is combined with an | ||||||||
algorithm-defined counter to construct the IV for the underlying | |||||||||
stream cipher. | |||||||||
This nonce must be provided in | |||||||||
.Fa crp_iv | .Fa crp_iv | ||||||||
via the | via the | ||||||||
.Dv CRYPTO_F_IV_SEPARATE | .Dv CRYPTO_F_IV_SEPARATE | ||||||||
flag. | flag. | ||||||||
.It Dv CRYPTO_AES_ICM | |||||||||
.Bl -tag -width "Block size :" -compact -offset indent | |||||||||
.It IV size : | |||||||||
16 | |||||||||
.It Block size : | |||||||||
1 | |||||||||
.It Key size : | |||||||||
16, 24 or 32 | |||||||||
.El | |||||||||
.Pp | .Pp | ||||||||
This algorithm implements Integer Counter Mode. | The following AEAD algorithms are supported: | ||||||||
This is similar to what most people call counter mode, but instead of the | .Bl -column "CRYPTO_AES_NIST_GCM_16" "Nonce" "16, 24, 32" "Tag" | ||||||||
counter being split into a nonce and a counter part, then entire nonce is | .It Sy Name Ta Sy Nonce Ta Sy Key Sizes Ta Sy Tag Ta Sy Description | ||||||||
used as the initial counter. | .It Dv CRYPTO_AES_NIST_GCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta | ||||||||
This does mean that if a counter is required that rolls over at 32 bits, | AES Galois/Counter Mode | ||||||||
the transaction need to be split into two parts where the counter rolls over. | .It Dv CRYPTO_AES_CCM_16 Ta 12 Ta 16, 24, 32 Ta 16 Ta | ||||||||
The counter incremented as a 128-bit big endian number. | AES Counter with CBC-MAC | ||||||||
.Pp | |||||||||
Note: The counter for each request must be provided in | |||||||||
.Fa crp_iv | |||||||||
via the | |||||||||
.Dv CRYPTO_F_IV_SEPARATE | |||||||||
flag. | |||||||||
.It Dv CRYPTO_AES_XTS | |||||||||
.Bl -tag -width "Block size :" -compact -offset indent | |||||||||
.It IV size : | |||||||||
8 | |||||||||
.It Block size : | |||||||||
16 | |||||||||
.It Key size : | |||||||||
32 or 64 | |||||||||
.El | .El | ||||||||
.Pp | |||||||||
This algorithm implements XEX Tweakable Block Cipher with Ciphertext Stealing | |||||||||
as defined in NIST SP 800-38E. | |||||||||
.Pp | |||||||||
NOTE: The ciphertext stealing part is not implemented which is why this cipher | |||||||||
is listed as having a block size of 16 instead of 1. | |||||||||
.It Dv CRYPTO_CAMELLIA_CBC | |||||||||
.Bl -tag -width "Block size :" -compact -offset indent | |||||||||
.It IV size : | |||||||||
16 | |||||||||
.It Block size : | |||||||||
16 | |||||||||
.It Key size : | |||||||||
16, 24 or 32 | |||||||||
.El | |||||||||
.Pp | |||||||||
This algorithm implements Cipher Block Chaining. | |||||||||
.It Dv CRYPTO_CHACHA20 | |||||||||
.Bl -tag -width "Block size :" -compact -offset indent | |||||||||
.It IV size : | |||||||||
16 | |||||||||
.It Block size : | |||||||||
1 | |||||||||
.It Key size : | |||||||||
16 or 32 | |||||||||
.El | |||||||||
.El | |||||||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||||||
.Xr crypto 4 , | .Xr crypto 4 , | ||||||||
.Xr crypto 9 | .Xr crypto 9 | ||||||||
.Sh HISTORY | .Sh HISTORY | ||||||||
The | The | ||||||||
.Nm | .Nm | ||||||||
manpage first appeared in | manual page first appeared in | ||||||||
Done Inline Actionss/manpage/man-page/, according to igor debdrup: s/manpage/man-page/, according to igor | |||||||||
Done Inline ActionsShouldn't it be just /manual page/? 0mp: Shouldn't it be just /manual page/? | |||||||||
Done Inline ActionsI just checked intro(4), devfs(5), and a couple other manual pages, and that is indeed the phrasing, so yes. :) debdrup: I just checked intro(4), devfs(5), and a couple other manual pages, and that is indeed the… | |||||||||
.Fx 10.1 . | .Fx 10.1 . | ||||||||
.Sh BUGS | |||||||||
Not all the implemented algorithms are listed. |
Since @bcr hasn't been here yet, I get to remind someone else to remember to bump .Dd ;)