xref: /freebsd/share/man/man9/crypto.9 (revision cfd6422a5217410fbd66f7a7a8a64d9d85e61229)
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 May 11, 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_NULL_HMAC
110.It Dv CRYPTO_POLY1305
111.It Dv CRYPTO_RIPEMD160
112.It Dv CRYPTO_RIPEMD160_HMAC
113.It Dv CRYPTO_SHA1
114.It Dv CRYPTO_SHA1_HMAC
115.It Dv CRYPTO_SHA2_224
116.It Dv CRYPTO_SHA2_224_HMAC
117.It Dv CRYPTO_SHA2_256
118.It Dv CRYPTO_SHA2_256_HMAC
119.It Dv CRYPTO_SHA2_384
120.It Dv CRYPTO_SHA2_384_HMAC
121.It Dv CRYPTO_SHA2_512
122.It Dv CRYPTO_SHA2_512_HMAC
123.El
124.Pp
125The following encryption algorithms are supported:
126.Pp
127.Bl -tag -offset indent -width CRYPTO_CAMELLIA_CBC -compact
128.It Dv CRYPTO_AES_CBC
129.It Dv CRYPTO_AES_ICM
130.It Dv CRYPTO_AES_XTS
131.It Dv CRYPTO_CAMELLIA_CBC
132.It Dv CRYPTO_CHACHA20
133.It Dv CRYPTO_NULL_CBC
134.El
135.Pp
136The following authenticated encryption with additional data (AEAD)
137algorithms are supported:
138.Pp
139.Bl -tag -offset indent -width CRYPTO_AES_NIST_GCM_16 -compact
140.It Dv CRYPTO_AES_CCM_16
141.It Dv CRYPTO_AES_NIST_GCM_16
142.El
143.Pp
144The following compression algorithms are supported:
145.Pp
146.Bl -tag -offset indent -width CRYPTO_DEFLATE_COMP -compact
147.It Dv CRYPTO_DEFLATE_COMP
148.El
149.Sh FILES
150.Bl -tag -width ".Pa sys/opencrypto/crypto.c"
151.It Pa sys/opencrypto/crypto.c
152most of the framework code
153.El
154.Sh SEE ALSO
155.Xr crypto 4 ,
156.Xr ipsec 4 ,
157.Xr crypto 7 ,
158.Xr crypto_asym 9 ,
159.Xr crypto_driver 9 ,
160.Xr crypto_request 9 ,
161.Xr crypto_session 9 ,
162.Xr sleep 9
163.Sh HISTORY
164The cryptographic framework first appeared in
165.Ox 2.7
166and was written by
167.An Angelos D. Keromytis Aq Mt angelos@openbsd.org .
168.Sh BUGS
169The framework needs a mechanism for determining which driver is
170best for a specific set of algorithms associated with a session.
171Some type of benchmarking is in order here.
172