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