1 .\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $
3 .\" Copyright (c) 2008 The NetBSD Foundation, Inc.
4 .\" Copyright (c) 2014-2021 The FreeBSD Foundation
5 .\" All rights reserved.
7 .\" Portions of this documentation were written by John-Mark Gurney
8 .\" under sponsorship of the FreeBSD Foundation and
9 .\" Rubicon Communications, LLC (Netgate).
11 .\" Portions of this documentation were written by Ararat River
12 .\" Consulting, LLC under sponsorship of the FreeBSD Foundation.
14 .\" This code is derived from software contributed to The NetBSD Foundation
15 .\" by Coyote Point Systems, Inc.
17 .\" Redistribution and use in source and binary forms, with or without
18 .\" modification, are permitted provided that the following conditions
20 .\" 1. Redistributions of source code must retain the above copyright
21 .\" notice, this list of conditions and the following disclaimer.
22 .\" 2. Redistributions in binary form must reproduce the above copyright
23 .\" notice, this list of conditions and the following disclaimer in the
24 .\" documentation and/or other materials provided with the distribution.
26 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
27 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
28 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
29 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
30 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
31 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
32 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
33 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
34 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
35 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
36 .\" POSSIBILITY OF SUCH DAMAGE.
40 .\" Copyright (c) 2004
41 .\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved.
43 .\" Redistribution and use in source and binary forms, with or without
44 .\" modification, are permitted provided that the following conditions
46 .\" 1. Redistributions of source code must retain the above copyright
47 .\" notice, this list of conditions and the following disclaimer.
48 .\" 2. Redistributions in binary form must reproduce the above copyright
49 .\" notice, this list of conditions and the following disclaimer in the
50 .\" documentation and/or other materials provided with the distribution.
52 .\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND
53 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
54 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
55 .\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD
56 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
57 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
58 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
59 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
60 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
61 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
62 .\" THE POSSIBILITY OF SUCH DAMAGE.
72 .Nd user-mode access to hardware-accelerated cryptography
79 .In crypto/cryptodev.h
83 driver gives user-mode applications access to hardware-accelerated
84 cryptographic transforms as implemented by the
90 special device provides an
93 User-mode applications open the special device and
96 calls on the descriptor.
100 .Ic kern.cryptodevallowsoft
103 If this variable is zero,
104 then user-mode sessions are only permitted to use cryptography coprocessors.
105 .Sh THEORY OF OPERATION
106 Use of the device requires a basic series of steps:
113 Create a session with
117 Applications will require at least one symmetric session.
118 Since cipher and MAC keys are tied to sessions, many
119 applications will require more.
121 Submit requests, synchronously with
126 Optionally destroy a session with
132 This will automatically close any remaining sessions associated with the
135 .Sh SYMMETRIC-KEY OPERATION
137 provides a context-based API
138 to traditional symmetric-key encryption (or privacy) algorithms,
139 keyed and unkeyed one-way hash (HMAC and MAC) algorithms,
140 encrypt-then-authenticate (ETA) fused operations,
141 and authenticated encryption with additional data (AEAD) operations.
143 drivers perform both a privacy algorithm and an integrity-check
144 algorithm in a single pass over the data: either a fused
145 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
146 Similarly, for AEAD operations,
147 drivers perform either an encrypt/MAC-generate operation
148 or a MAC-verify/decrypt operation.
150 The algorithm(s) and key(s) to use are specified when a session is
152 Individual requests are able to specify per-request initialization vectors
155 For a list of supported algorithms, see
157 .Ss IOCTL Request Descriptions
159 .Bl -tag -width CIOCGSESSION
161 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
163 struct crypt_find_op {
164 int crid; /* driver id + flags */
165 char name[32]; /* device/driver name */
171 is -1, then find the driver named
177 is not -1, return the name of the driver with
181 In either case, if the driver is not found,
184 .It Dv CIOCGSESSION Fa struct session_op *sessp
187 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
188 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
190 uint32_t keylen; /* cipher key */
192 int mackeylen; /* mac key */
195 uint32_t ses; /* returns: ses # */
199 Create a new cryptographic session on a file descriptor for the device;
200 that is, a persistent object specific to the chosen
201 privacy algorithm, integrity algorithm, and keys specified in
203 The special value 0 for either privacy or integrity
204 is reserved to indicate that the indicated operation (privacy or integrity)
205 is not desired for this session.
206 ETA sessions specify both privacy and integrity algorithms.
207 AEAD sessions specify only a privacy algorithm.
209 Multiple sessions may be bound to a single file descriptor.
210 The session ID returned in
212 is supplied as a required field in the operation structure
214 for future encryption or hashing requests.
216 .\" This implementation will never return a session ID of 0 for a successful
217 .\" creation of a session, which is a
221 For non-zero privacy algorithms, the privacy algorithm
223 .Fa sessp-\*[Gt]cipher ,
225 .Fa sessp-\*[Gt]keylen ,
226 and the key value in the octets addressed by
227 .Fa sessp-\*[Gt]key .
229 For keyed one-way hash algorithms, the one-way hash must be specified
231 .Fa sessp-\*[Gt]mac ,
233 .Fa sessp-\*[Gt]mackey ,
234 and the key value in the octets addressed by
235 .Fa sessp-\*[Gt]mackeylen .
238 Support for a specific combination of fused privacy and
239 integrity-check algorithms depends on whether the underlying
240 hardware supports that combination.
241 Not all combinations are supported
242 by all hardware, even if the hardware supports each operation as a
243 stand-alone non-fused operation.
244 .It Dv CIOCGSESSION2 Fa struct session2_op *sessp
247 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
248 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
250 uint32_t keylen; /* cipher key */
252 int mackeylen; /* mac key */
255 uint32_t ses; /* returns: ses # */
256 int crid; /* driver id + flags (rw) */
257 int ivlen; /* length of nonce/IV */
258 int maclen; /* length of MAC/tag */
259 int pad[2]; /* for future expansion */
263 This request is similar to CIOGSESSION but adds additional fields.
266 requests either a specific crypto device or a class of devices (software vs
269 .Fa sessp-\*[Gt]ivlen
270 specifies the length of the IV or nonce supplied with each request.
271 If this field is set to zero, the default IV or nonce length is used.
273 .Fa sessp-\*[Gt]maclen
274 specifies the length of the MAC or authentication tag supplied or computed by
276 If this field is set to zero, the full MAC is used.
280 field must be initialized to zero.
281 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
285 uint16_t op; /* e.g. COP_ENCRYPT */
290 void *mac; /* must be large enough for result */
295 Request an encryption/decryption (or hash) operation.
306 supplies the length of the input buffer; the fields
307 .Fa cr_op-\*[Gt]src ,
308 .Fa cr_op-\*[Gt]dst ,
309 .Fa cr_op-\*[Gt]mac ,
311 supply the addresses of the input buffer, output buffer,
312 one-way hash, and initialization vector, respectively.
314 If a session is using either fused encrypt-then-authenticate or
316 decryption operations require the associated hash as an input.
317 If the hash is incorrect, the
318 operation will fail with
320 and the output buffer will remain unchanged.
321 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
325 uint16_t op; /* e.g. COP_ENCRYPT */
332 const void *aad; /* additional authenticated data */
333 void *tag; /* must fit for chosen TAG length */
342 but provides additional data in
343 .Fa cr_aead-\*[Gt]aad
344 to include in the authentication mode.
345 .It Dv CIOCFSESSION Fa u_int32_t ses_id
346 Destroys the session identified by
361 driver first appeared in
365 driver was imported to
368 Error checking and reporting is weak.
370 The values specified for symmetric-key key sizes to
372 must exactly match the values expected by
374 The output buffer and MAC buffers supplied to
376 must follow whether privacy or integrity algorithms were specified for
377 session: if you request a
379 algorithm, you must supply a suitably-sized buffer.