1.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ 2.\" 3.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) 4.\" 5.\" Copyright (c) 2000, 2001 Angelos D. Keromytis 6.\" 7.\" Permission to use, copy, and modify this software with or without fee 8.\" is hereby granted, provided that this entire notice is included in 9.\" all source code copies of any software which is or includes a copy or 10.\" modification of this software. 11.\" 12.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 13.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY 14.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 15.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 16.\" PURPOSE. 17.\" 18.\" $FreeBSD$ 19.\" 20.Dd March 27, 2020 21.Dt CRYPTO 9 22.Os 23.Sh NAME 24.Nm crypto 25.Nd API for cryptographic services in the kernel 26.Sh SYNOPSIS 27.In opencrypto/cryptodev.h 28.Sh DESCRIPTION 29.Nm 30is a framework for in-kernel cryptography. 31It permits in-kernel consumers to encrypt and decrypt data 32and also enables userland applications to use cryptographic hardware 33through the 34.Pa /dev/crypto 35device. 36.Pp 37.Nm 38supports two modes of operation: 39one mode for symmetric-keyed cryptographic requests and digest, 40and a second mode for asymmetric-key requests and modular arithmetic. 41.Ss Symmetric-Key Mode 42Symmetric-key operations include encryption and decryption operations 43using block and stream ciphers as well as computation and verification 44of message authentication codes (MACs). 45In this mode, 46consumers allocate sessions to describe a transform as discussed in 47.Xr crypto_session 9 . 48Consumers then allocate request objects to describe each transformation 49such as encrypting a network packet or decrypting a disk sector. 50Requests are described in 51.Xr crypto_request 9 . 52.Pp 53Device drivers are responsible for processing requests submitted by 54consumers. 55.Xr crypto_driver 9 56describes the interfaces drivers use to register with the framework, 57helper routines the framework provides to faciliate request processing, 58and the interfaces drivers are required to provide. 59.Ss Asymmetric-Key Mode 60Assymteric-key operations do not use sessions. 61Instead, 62these operations perform individual mathematical operations using a set 63of input and output parameters. 64These operations are described in 65.Xr crypto_asym 9 . 66Drivers that support asymmetric operations use additional interfaces 67described in 68.Xr crypto_asym 9 69in addition to the base interfaces described in 70.Xr crypto_driver 9 . 71.Ss Callbacks 72Since the consumers may not be associated with a process, drivers may 73not 74.Xr sleep 9 . 75The same holds for the framework. 76Thus, a callback mechanism is used 77to notify a consumer that a request has been completed (the 78callback is specified by the consumer on a per-request basis). 79The callback is invoked by the framework whether the request was 80successfully completed or not. 81Errors are reported to the callback function. 82.Pp 83Session initialization does not use callbacks and returns errors 84synchronously. 85.Ss Session Migration 86For symmetric-key operations, 87a specific error code, 88.Er EAGAIN , 89is used to indicate that a session handle has changed and that the 90request may be re-submitted immediately with the new session. 91The consumer should update its saved copy of the session handle 92to the value of 93.Fa crp_session 94so that future requests use the new session. 95.Ss Supported Algorithms 96More details on some algorithms may be found in 97.Xr crypto 7 . 98These algorithms are used for symmetric-mode operations. 99Asymmetric-mode operations support operations described in 100.Xr crypto_asym 9 . 101.Pp 102The following authentication algorithms are supported: 103.Pp 104.Bl -tag -offset indent -width CRYPTO_AES_CCM_CBC_MAC -compact 105.It Dv CRYPTO_AES_CCM_CBC_MAC 106.It Dv CRYPTO_AES_NIST_GMAC 107.It Dv CRYPTO_BLAKE2B 108.It Dv CRYPTO_BLAKE2S 109.It Dv CRYPTO_MD5 110.It Dv CRYPTO_MD5_HMAC 111.It Dv CRYPTO_MD5_KPDK 112.It Dv CRYPTO_NULL_HMAC 113.It Dv CRYPTO_POLY1305 114.It Dv CRYPTO_RIPEMD160 115.It Dv CRYPTO_RIPEMD160_HMAC 116.It Dv CRYPTO_SHA1 117.It Dv CRYPTO_SHA1_HMAC 118.It Dv CRYPTO_SHA1_KPDK 119.It Dv CRYPTO_SHA2_224 120.It Dv CRYPTO_SHA2_224_HMAC 121.It Dv CRYPTO_SHA2_256 122.It Dv CRYPTO_SHA2_256_HMAC 123.It Dv CRYPTO_SHA2_384 124.It Dv CRYPTO_SHA2_384_HMAC 125.It Dv CRYPTO_SHA2_512 126.It Dv CRYPTO_SHA2_512_HMAC 127.El 128.Pp 129The following encryption algorithms are supported: 130.Pp 131.Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact 132.It Dv CRYPTO_AES_CBC 133.It Dv CRYPTO_AES_ICM 134.It Dv CRYPTO_AES_XTS 135.It Dv CRYPTO_ARC4 136.It Dv CRYPTO_BLF_CBC 137.It Dv CRYPTO_CAMELLIA_CBC 138.It Dv CRYPTO_CAST_CBC 139.It Dv CRYPTO_CHACHA20 140.It Dv CRYPTO_DES_CBC 141.It Dv CRYPTO_3DES_CBC 142.It Dv CRYPTO_NULL_CBC 143.It Dv CRYPTO_SKIPJACK_CBC 144.El 145.Pp 146The following authenticated encryption with additional data (AEAD) 147algorithms are supported: 148.Pp 149.Bl -tag -offset indent -width CRYPTO_AES_NIST_GCM_16 -compact 150.It Dv CRYPTO_AES_CCM_16 151.It Dv CRYPTO_AES_NIST_GCM_16 152.El 153.Pp 154The following compression algorithms are supported: 155.Pp 156.Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact 157.It Dv CRYPTO_DEFLATE_COMP 158.El 159.Sh FILES 160.Bl -tag -width ".Pa sys/opencrypto/crypto.c" 161.It Pa sys/opencrypto/crypto.c 162most of the framework code 163.El 164.Sh SEE ALSO 165.Xr crypto 4 , 166.Xr ipsec 4 , 167.Xr crypto 7 , 168.Xr crypto_asym 9 , 169.Xr crypto_driver 9 , 170.Xr crypto_request 9 , 171.Xr crypto_session 9 , 172.Xr sleep 9 173.Sh HISTORY 174The cryptographic framework first appeared in 175.Ox 2.7 176and was written by 177.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . 178.Sh BUGS 179The framework needs a mechanism for determining which driver is 180best for a specific set of algorithms associated with a session. 181Some type of benchmarking is in order here. 182