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.
63 .Dd September 21, 2017
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 should open the special device,
93 calls on the descriptor.
96 is controlled by three
99 .Ic kern.userasymcrypto
101 .Ic kern.cryptodevallowsoft .
105 device provides two distinct modes of operation: one mode for
106 symmetric-keyed cryptographic requests, and a second mode for
107 both asymmetric-key (public-key/private-key) requests, and for
108 modular arithmetic (for Diffie-Hellman key exchange and other
109 cryptographic protocols).
110 The two modes are described separately below.
111 .Sh THEORY OF OPERATION
112 Regardless of whether symmetric-key or asymmetric-key operations are
113 to be performed, use of the device requires a basic series of steps:
116 Open a file descriptor for the device.
120 If any symmetric operation will be performed,
121 create one session, with
123 Most applications will require at least one symmetric session.
124 Since cipher and MAC keys are tied to sessions, many
125 applications will require more.
126 Asymmetric operations do not use sessions.
128 Submit requests, synchronously with
137 Destroy one session with
140 Close the device with
143 .Sh SYMMETRIC-KEY OPERATION
144 The symmetric-key operation mode provides a context-based API
145 to traditional symmetric-key encryption (or privacy) algorithms,
146 or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms.
147 The symmetric-key mode also permits fused operation,
148 where the hardware performs both a privacy algorithm and an integrity-check
149 algorithm in a single pass over the data: either a fused
150 encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
152 To use symmetric mode, you must first create a session specifying
153 the algorithm(s) and key(s) to use; then issue encrypt or decrypt
154 requests against the session.
156 For a list of supported algorithms, see
160 .Ss IOCTL Request Descriptions
162 .Bl -tag -width CIOCGSESSION
164 .It Dv CRIOGET Fa int *fd
165 Clone the fd argument to
167 yielding a new file descriptor for the creation of sessions.
169 .It Dv CIOCFINDDEV Fa struct crypt_find_op *fop
171 struct crypt_find_op {
172 int crid; /* driver id + flags */
173 char name[32]; /* device/driver name */
179 is -1, then find the driver named
185 is not -1, return the name of the driver with
189 In either case, if the driver is not found,
192 .It Dv CIOCGSESSION Fa struct session_op *sessp
195 u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */
196 u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */
198 u_int32_t keylen; /* cipher key */
200 int mackeylen; /* mac key */
203 u_int32_t ses; /* returns: ses # */
207 Create a new cryptographic session on a file descriptor for the device;
208 that is, a persistent object specific to the chosen
209 privacy algorithm, integrity algorithm, and keys specified in
211 The special value 0 for either privacy or integrity
212 is reserved to indicate that the indicated operation (privacy or integrity)
213 is not desired for this session.
215 Multiple sessions may be bound to a single file descriptor.
216 The session ID returned in
218 is supplied as a required field in the symmetric-operation structure
220 for future encryption or hashing requests.
222 .\" This implementation will never return a session ID of 0 for a successful
223 .\" creation of a session, which is a
227 For non-zero symmetric-key privacy algorithms, the privacy algorithm
229 .Fa sessp-\*[Gt]cipher ,
231 .Fa sessp-\*[Gt]keylen ,
232 and the key value in the octets addressed by
233 .Fa sessp-\*[Gt]key .
235 For keyed one-way hash algorithms, the one-way hash must be specified
237 .Fa sessp-\*[Gt]mac ,
239 .Fa sessp-\*[Gt]mackey ,
240 and the key value in the octets addressed by
241 .Fa sessp-\*[Gt]mackeylen .
244 Support for a specific combination of fused privacy and
245 integrity-check algorithms depends on whether the underlying
246 hardware supports that combination.
247 Not all combinations are supported
248 by all hardware, even if the hardware supports each operation as a
249 stand-alone non-fused operation.
250 .It Dv CIOCCRYPT Fa struct crypt_op *cr_op
254 u_int16_t op; /* e.g. COP_ENCRYPT */
258 caddr_t mac; /* must be large enough for result */
263 Request a symmetric-key (or hash) operation.
264 The file descriptor argument to
266 must have been bound to a valid session.
277 supplies the length of the input buffer; the fields
278 .Fa cr_op-\*[Gt]src ,
279 .Fa cr_op-\*[Gt]dst ,
280 .Fa cr_op-\*[Gt]mac ,
282 supply the addresses of the input buffer, output buffer,
283 one-way hash, and initialization vector, respectively.
284 If a session is using both a privacy algorithm and a hash algorithm,
285 the request will generate a hash of the input buffer before
286 generating the output buffer by default.
288 .Dv COP_F_CIPHER_FIRST
289 flag is included in the
290 .Fa cr_op-\*[Gt]flags
292 then the request will generate a hash of the output buffer after
293 executing the privacy algorithm.
294 .It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead
298 u_int16_t op; /* e.g. COP_ENCRYPT */
305 caddr_t tag; /* must be large enough for result */
314 but provides additional data in
315 .Fa cr_aead-\*[Gt]aad
316 to include in the authentication mode.
317 .It Dv CIOCFSESSION Fa u_int32_t ses_id
318 Destroys the /dev/crypto session associated with the file-descriptor
320 .It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ;
330 sessions specified by the
332 array of session identifiers.
335 .Sh ASYMMETRIC-KEY OPERATION
336 .Ss Asymmetric-key algorithms
337 Contingent upon hardware support, the following asymmetric
338 (public-key/private-key; or key-exchange subroutine) operations may
341 .Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact
342 .It Em "Algorithm" Ta "Input parameter" Ta "Output parameter"
343 .It Em " " Ta "Count" Ta "Count"
344 .It Dv CRK_MOD_EXP Ta 3 Ta 1
345 .It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1
346 .It Dv CRK_DSA_SIGN Ta 5 Ta 2
347 .It Dv CRK_DSA_VERIFY Ta 7 Ta 0
348 .It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1
351 See below for discussion of the input and output parameter counts.
352 .Ss Asymmetric-key commands
353 .Bl -tag -width CIOCKEY
354 .It Dv CIOCASYMFEAT Fa int *feature_mask
355 Returns a bitmask of supported asymmetric-key operations.
356 Each of the above-listed asymmetric operations is present
357 if and only if the bit position numbered by the code for that operation
361 is available if and only if the bit
362 .Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP
364 .It Dv CIOCKEY Fa struct crypt_kop *kop
367 u_int crk_op; /* e.g. CRK_MOD_EXP */
368 u_int crk_status; /* return status */
369 u_short crk_iparams; /* # of input params */
370 u_short crk_oparams; /* # of output params */
372 struct crparam crk_param[CRK_MAXPARAM];
375 /* Bignum parameter, in packed bytes. */
382 Performs an asymmetric-key operation from the list above.
383 The specific operation is supplied in
384 .Fa kop-\*[Gt]crk_op ;
385 final status for the operation is returned in
386 .Fa kop-\*[Gt]crk_status .
387 The number of input arguments and the number of output arguments
389 .Fa kop-\*[Gt]crk_iparams
391 .Fa kop-\*[Gt]crk_iparams ,
395 must be filled in with exactly
396 .Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams
397 arguments, each encoded as a
399 (address, bitlength) pair.
401 The semantics of these arguments are currently undocumented.
416 driver first appeared in
420 driver was imported to
423 Error checking and reporting is weak.
425 The values specified for symmetric-key key sizes to
427 must exactly match the values expected by
429 The output buffer and MAC buffers supplied to
431 must follow whether privacy or integrity algorithms were specified for
432 session: if you request a
434 algorithm, you must supply a suitably-sized buffer.
436 The scheme for passing arguments for asymmetric requests is baroque.
438 The naming inconsistency between
442 names is an unfortunate historical artifact.