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 April 12, 2021 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 encryption and decryption operations 39using block and stream ciphers as well as computation and verification 40of message authentication codes (MACs). 41Consumers allocate sessions to describe a transform as discussed in 42.Xr crypto_session 9 . 43Consumers then allocate request objects to describe each transformation 44such as encrypting a network packet or decrypting a disk sector. 45Requests are described in 46.Xr crypto_request 9 . 47.Pp 48Device drivers are responsible for processing requests submitted by 49consumers. 50.Xr crypto_driver 9 51describes the interfaces drivers use to register with the framework, 52helper routines the framework provides to facilitate request processing, 53and the interfaces drivers are required to provide. 54.Ss Callbacks 55Since the consumers may not be associated with a process, drivers may 56not 57.Xr sleep 9 . 58The same holds for the framework. 59Thus, a callback mechanism is used 60to notify a consumer that a request has been completed (the 61callback is specified by the consumer on a per-request basis). 62The callback is invoked by the framework whether the request was 63successfully completed or not. 64Errors are reported to the callback function. 65.Pp 66Session initialization does not use callbacks and returns errors 67synchronously. 68.Ss Session Migration 69Operations may fail with a specific error code, 70.Er EAGAIN , 71to indicate that a session handle has changed and that the 72request may be re-submitted immediately with the new session. 73The consumer should update its saved copy of the session handle 74to the value of 75.Fa crp_session 76so that future requests use the new session. 77.Ss Supported Algorithms 78More details on some algorithms may be found in 79.Xr crypto 7 . 80.Pp 81The following authentication algorithms are supported: 82.Pp 83.Bl -tag -offset indent -width CRYPTO_AES_CCM_CBC_MAC -compact 84.It Dv CRYPTO_AES_CCM_CBC_MAC 85.It Dv CRYPTO_AES_NIST_GMAC 86.It Dv CRYPTO_BLAKE2B 87.It Dv CRYPTO_BLAKE2S 88.It Dv CRYPTO_NULL_HMAC 89.It Dv CRYPTO_POLY1305 90.It Dv CRYPTO_RIPEMD160 91.It Dv CRYPTO_RIPEMD160_HMAC 92.It Dv CRYPTO_SHA1 93.It Dv CRYPTO_SHA1_HMAC 94.It Dv CRYPTO_SHA2_224 95.It Dv CRYPTO_SHA2_224_HMAC 96.It Dv CRYPTO_SHA2_256 97.It Dv CRYPTO_SHA2_256_HMAC 98.It Dv CRYPTO_SHA2_384 99.It Dv CRYPTO_SHA2_384_HMAC 100.It Dv CRYPTO_SHA2_512 101.It Dv CRYPTO_SHA2_512_HMAC 102.El 103.Pp 104The following encryption algorithms are supported: 105.Pp 106.Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact 107.It Dv CRYPTO_AES_CBC 108.It Dv CRYPTO_AES_ICM 109.It Dv CRYPTO_AES_XTS 110.It Dv CRYPTO_CAMELLIA_CBC 111.It Dv CRYPTO_CHACHA20 112.It Dv CRYPTO_NULL_CBC 113.El 114.Pp 115The following authenticated encryption with additional data (AEAD) 116algorithms are supported: 117.Pp 118.Bl -tag -offset indent -width CRYPTO_CHACHA20_POLY1305 -compact 119.It Dv CRYPTO_AES_CCM_16 120.It Dv CRYPTO_AES_NIST_GCM_16 121.It Dv CRYPTO_CHACHA20_POLY1305 122.El 123.Pp 124The following compression algorithms are supported: 125.Pp 126.Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact 127.It Dv CRYPTO_DEFLATE_COMP 128.El 129.Sh FILES 130.Bl -tag -width ".Pa sys/opencrypto/crypto.c" 131.It Pa sys/opencrypto/crypto.c 132most of the framework code 133.El 134.Sh SEE ALSO 135.Xr crypto 4 , 136.Xr ipsec 4 , 137.Xr crypto 7 , 138.Xr crypto_driver 9 , 139.Xr crypto_request 9 , 140.Xr crypto_session 9 , 141.Xr sleep 9 142.Sh HISTORY 143The cryptographic framework first appeared in 144.Ox 2.7 145and was written by 146.An Angelos D. Keromytis Aq Mt angelos@openbsd.org . 147.Sh BUGS 148The framework needs a mechanism for determining which driver is 149best for a specific set of algorithms associated with a session. 150Some type of benchmarking is in order here. 151