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 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 .\" This code is derived from software contributed to The NetBSD Foundation
12 .\" by Coyote Point Systems, Inc.
14 .\" Redistribution and use in source and binary forms, with or without
15 .\" modification, are permitted provided that the following conditions
17 .\" 1. Redistributions of source code must retain the above copyright
18 .\" notice, this list of conditions and the following disclaimer.
19 .\" 2. Redistributions in binary form must reproduce the above copyright
20 .\" notice, this list of conditions and the following disclaimer in the
21 .\" documentation and/or other materials provided with the distribution.
23 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
24 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
25 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
26 .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
27 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
28 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
29 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
30 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
31 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
32 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
33 .\" POSSIBILITY OF SUCH DAMAGE.
37 .\" Copyright (c) 2004
38 .\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved.
40 .\" Redistribution and use in source and binary forms, with or without
41 .\" modification, are permitted provided that the following conditions
43 .\" 1. Redistributions of source code must retain the above copyright
44 .\" notice, this list of conditions and the following disclaimer.
45 .\" 2. Redistributions in binary form must reproduce the above copyright
46 .\" notice, this list of conditions and the following disclaimer in the
47 .\" documentation and/or other materials provided with the distribution.
49 .\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND
50 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
51 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
52 .\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD
53 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
54 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
55 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
56 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
57 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
58 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
59 .\" THE POSSIBILITY OF SUCH DAMAGE.
69 .Nd user-mode access to hardware-accelerated cryptography
76 .In crypto/cryptodev.h
80 driver gives user-mode applications access to hardware-accelerated
81 cryptographic transforms as implemented by the
87 special device provides an
90 User-mode applications open the special device and
93 calls on the descriptor.
97 .Ic kern.cryptodevallowsoft
100 If this variable is zero,
101 then user-mode sessions are only permitted to use cryptography coprocessors.
102 .Sh THEORY OF OPERATION
103 Use of the device requires a basic series of steps:
110 Create a session with
114 Applications will require at least one symmetric session.
115 Since cipher and MAC keys are tied to sessions, many
116 applications will require more.
118 Submit requests, synchronously with
123 Optionally destroy a session with
129 This will automatically close any remaining sessions associated with the
132 .Sh SYMMETRIC-KEY OPERATION
134 provides a context-based API
135 to traditional symmetric-key encryption (or privacy) algorithms,
136 keyed and unkeyed one-way hash (HMAC and MAC) algorithms,
137 encrypt-then-authenticate (ETA) fused operations,
138 and authenticated encryption with additional data (AEAD) operations.
140 drivers perform both a privacy algorithm and an integrity-check
141 algorithm in a single pass over the data: either a fused
142 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
143 Similarly, for AEAD operations,
144 drivers perform either an encrypt/MAC-generate operation
145 or a MAC-verify/decrypt operation.
147 The algorithm(s) and key(s) to use are specified when a session is
149 Individual requests are able to specify per-request initialization vectors
152 For a list of supported algorithms, see
154 .Ss IOCTL Request Descriptions
156 .Bl -tag -width CIOCGSESSION
158 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
160 struct crypt_find_op {
161 int crid; /* driver id + flags */
162 char name[32]; /* device/driver name */
168 is -1, then find the driver named
174 is not -1, return the name of the driver with
178 In either case, if the driver is not found,
181 .It Dv CIOCGSESSION Fa struct session_op *sessp
184 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
185 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
187 uint32_t keylen; /* cipher key */
189 int mackeylen; /* mac key */
192 uint32_t ses; /* returns: ses # */
196 Create a new cryptographic session on a file descriptor for the device;
197 that is, a persistent object specific to the chosen
198 privacy algorithm, integrity algorithm, and keys specified in
200 The special value 0 for either privacy or integrity
201 is reserved to indicate that the indicated operation (privacy or integrity)
202 is not desired for this session.
203 ETA sessions specify both privacy and integrity algorithms.
204 AEAD sessions specify only a privacy algorithm.
206 Multiple sessions may be bound to a single file descriptor.
207 The session ID returned in
209 is supplied as a required field in the operation structure
211 for future encryption or hashing requests.
213 .\" This implementation will never return a session ID of 0 for a successful
214 .\" creation of a session, which is a
218 For non-zero privacy algorithms, the privacy algorithm
220 .Fa sessp-\*[Gt]cipher ,
222 .Fa sessp-\*[Gt]keylen ,
223 and the key value in the octets addressed by
224 .Fa sessp-\*[Gt]key .
226 For keyed one-way hash algorithms, the one-way hash must be specified
228 .Fa sessp-\*[Gt]mac ,
230 .Fa sessp-\*[Gt]mackey ,
231 and the key value in the octets addressed by
232 .Fa sessp-\*[Gt]mackeylen .
235 Support for a specific combination of fused privacy and
236 integrity-check algorithms depends on whether the underlying
237 hardware supports that combination.
238 Not all combinations are supported
239 by all hardware, even if the hardware supports each operation as a
240 stand-alone non-fused operation.
241 .It Dv CIOCGSESSION2 Fa struct session2_op *sessp
244 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
245 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
247 uint32_t keylen; /* cipher key */
249 int mackeylen; /* mac key */
252 uint32_t ses; /* returns: ses # */
253 int crid; /* driver id + flags (rw) */
254 int pad[4]; /* for future expansion */
258 This request is similar to CIOGSESSION except that
260 requests either a specific crypto device or a class of devices (software vs
264 field must be initialized to zero.
265 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
269 uint16_t op; /* e.g. COP_ENCRYPT */
274 void *mac; /* must be large enough for result */
279 Request an encryption/decryption (or hash) operation.
290 supplies the length of the input buffer; the fields
291 .Fa cr_op-\*[Gt]src ,
292 .Fa cr_op-\*[Gt]dst ,
293 .Fa cr_op-\*[Gt]mac ,
295 supply the addresses of the input buffer, output buffer,
296 one-way hash, and initialization vector, respectively.
298 If a session is using either fused encrypt-then-authenticate or
300 decryption operations require the associated hash as an input.
301 If the hash is incorrect, the
302 operation will fail with
304 and the output buffer will remain unchanged.
305 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
309 uint16_t op; /* e.g. COP_ENCRYPT */
316 const void *aad; /* additional authenticated data */
317 void *tag; /* must fit for chosen TAG length */
326 but provides additional data in
327 .Fa cr_aead-\*[Gt]aad
328 to include in the authentication mode.
329 .It Dv CIOCFSESSION Fa u_int32_t ses_id
330 Destroys the session identified by
345 driver first appeared in
349 driver was imported to
352 Error checking and reporting is weak.
354 The values specified for symmetric-key key sizes to
356 must exactly match the values expected by
358 The output buffer and MAC buffers supplied to
360 must follow whether privacy or integrity algorithms were specified for
361 session: if you request a
363 algorithm, you must supply a suitably-sized buffer.