1.\" $NetBSD: crypto.4,v 1.24 2014/01/27 21:23:59 pgoyette Exp $ 2.\" 3.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 4.\" Copyright (c) 2014 The FreeBSD Foundation 5.\" All rights reserved. 6.\" 7.\" Portions of this documentation were written by John-Mark Gurney 8.\" under sponsorship of the FreeBSD Foundation and 9.\" Rubicon Communications, LLC (Netgate). 10.\" 11.\" This code is derived from software contributed to The NetBSD Foundation 12.\" by Coyote Point Systems, Inc. 13.\" 14.\" Redistribution and use in source and binary forms, with or without 15.\" modification, are permitted provided that the following conditions 16.\" are met: 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. 22.\" 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. 34.\" 35.\" 36.\" 37.\" Copyright (c) 2004 38.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved. 39.\" 40.\" Redistribution and use in source and binary forms, with or without 41.\" modification, are permitted provided that the following conditions 42.\" are met: 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. 48.\" 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. 60.\" 61.\" $FreeBSD$ 62.\" 63.Dd December 12, 2014 64.Dt CRYPTO 4 65.Os 66.Sh NAME 67.Nm crypto , 68.Nm cryptodev 69.Nd user-mode access to hardware-accelerated cryptography 70.Sh SYNOPSIS 71.Cd device crypto 72.Cd device cryptodev 73.Pp 74.In sys/ioctl.h 75.In sys/time.h 76.In crypto/cryptodev.h 77.Sh DESCRIPTION 78The 79.Nm 80driver gives user-mode applications access to hardware-accelerated 81cryptographic transforms, as implemented by the 82.Xr opencrypto 9 83in-kernel interface. 84.Pp 85The 86.Pa /dev/crypto 87special device provides an 88.Xr ioctl 2 89based interface. 90User-mode applications should open the special device, 91then issue 92.Xr ioctl 2 93calls on the descriptor. 94User-mode access to 95.Pa /dev/crypto 96is controlled by three 97.Xr sysctl 8 98variables, 99.Ic kern.userasymcrypto 100and 101.Ic kern.cryptodevallowsoft . 102See 103.Xr sysctl 7 104for additional details. 105.Pp 106The 107.Nm 108device provides two distinct modes of operation: one mode for 109symmetric-keyed cryptographic requests, and a second mode for 110both asymmetric-key (public-key/private-key) requests, and for 111modular arithmetic (for Diffie-Hellman key exchange and other 112cryptographic protocols). 113The two modes are described separately below. 114.Sh THEORY OF OPERATION 115Regardless of whether symmetric-key or asymmetric-key operations are 116to be performed, use of the device requires a basic series of steps: 117.Bl -enum 118.It 119Open a file descriptor for the device. 120See 121.Xr open 2 . 122.It 123If any symmetric operation will be performed, 124create one session, with 125.Dv CIOCGSESSION . 126Most applications will require at least one symmetric session. 127Since cipher and MAC keys are tied to sessions, many 128applications will require more. 129Asymmetric operations do not use sessions. 130.It 131Submit requests, synchronously with 132.Dv CIOCCRYPT 133(symmetric) 134or 135.Dv CIOCKEY 136(asymmetric). 137.It 138Destroy one session with 139.Dv CIOCFSESSION . 140.It 141Close the device with 142.Xr close 2 . 143.El 144.Sh SYMMETRIC-KEY OPERATION 145The symmetric-key operation mode provides a context-based API 146to traditional symmetric-key encryption (or privacy) algorithms, 147or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. 148The symmetric-key mode also permits fused operation, 149where the hardware performs both a privacy algorithm and an integrity-check 150algorithm in a single pass over the data: either a fused 151encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 152.Pp 153To use symmetric mode, you must first create a session specifying 154the algorithm(s) and key(s) to use; then issue encrypt or decrypt 155requests against the session. 156.Ss Algorithms 157For a list of supported algorithms, see 158.Xr crypto 7 159and 160.Xr crypto 9 . 161.Ss IOCTL Request Descriptions 162.\" 163.Bl -tag -width CIOCGSESSION 164.\" 165.It Dv CRIOGET Fa int *fd 166Clone the fd argument to 167.Xr ioctl 2 , 168yielding a new file descriptor for the creation of sessions. 169.\" 170.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop 171.Bd -literal 172struct crypt_find_op { 173 int crid; /* driver id + flags */ 174 char name[32]; /* device/driver name */ 175}; 176 177.Ed 178If 179.Fa crid 180is -1, then find the driver named 181.Fa name 182and return the id in 183.Fa crid . 184If 185.Fa crid 186is not -1, return the name of the driver with 187.Fa crid 188in 189.Fa name . 190In either case, if the driver is not found, 191.Dv ENOENT 192is returned. 193.It Dv CIOCGSESSION Fa struct session_op *sessp 194.Bd -literal 195struct session_op { 196 u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ 197 u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ 198 199 u_int32_t keylen; /* cipher key */ 200 void * key; 201 int mackeylen; /* mac key */ 202 void * mackey; 203 204 u_int32_t ses; /* returns: ses # */ 205}; 206 207.Ed 208Create a new cryptographic session on a file descriptor for the device; 209that is, a persistent object specific to the chosen 210privacy algorithm, integrity algorithm, and keys specified in 211.Fa sessp . 212The special value 0 for either privacy or integrity 213is reserved to indicate that the indicated operation (privacy or integrity) 214is not desired for this session. 215.Pp 216Multiple sessions may be bound to a single file descriptor. 217The session ID returned in 218.Fa sessp-\*[Gt]ses 219is supplied as a required field in the symmetric-operation structure 220.Fa crypt_op 221for future encryption or hashing requests. 222.\" .Pp 223.\" This implementation will never return a session ID of 0 for a successful 224.\" creation of a session, which is a 225.\" .Nx 226.\" extension. 227.Pp 228For non-zero symmetric-key privacy algorithms, the privacy algorithm 229must be specified in 230.Fa sessp-\*[Gt]cipher , 231the key length in 232.Fa sessp-\*[Gt]keylen , 233and the key value in the octets addressed by 234.Fa sessp-\*[Gt]key . 235.Pp 236For keyed one-way hash algorithms, the one-way hash must be specified 237in 238.Fa sessp-\*[Gt]mac , 239the key length in 240.Fa sessp-\*[Gt]mackey , 241and the key value in the octets addressed by 242.Fa sessp-\*[Gt]mackeylen . 243.\" 244.Pp 245Support for a specific combination of fused privacy and 246integrity-check algorithms depends on whether the underlying 247hardware supports that combination. 248Not all combinations are supported 249by all hardware, even if the hardware supports each operation as a 250stand-alone non-fused operation. 251.It Dv CIOCCRYPT Fa struct crypt_op *cr_op 252.Bd -literal 253struct crypt_op { 254 u_int32_t ses; 255 u_int16_t op; /* e.g. COP_ENCRYPT */ 256 u_int16_t flags; 257 u_int len; 258 caddr_t src, dst; 259 caddr_t mac; /* must be large enough for result */ 260 caddr_t iv; 261}; 262 263.Ed 264Request a symmetric-key (or hash) operation. 265The file descriptor argument to 266.Xr ioctl 2 267must have been bound to a valid session. 268To encrypt, set 269.Fa cr_op-\*[Gt]op 270to 271.Dv COP_ENCRYPT . 272To decrypt, set 273.Fa cr_op-\*[Gt]op 274to 275.Dv COP_DECRYPT . 276The field 277.Fa cr_op-\*[Gt]len 278supplies the length of the input buffer; the fields 279.Fa cr_op-\*[Gt]src , 280.Fa cr_op-\*[Gt]dst , 281.Fa cr_op-\*[Gt]mac , 282.Fa cr_op-\*[Gt]iv 283supply the addresses of the input buffer, output buffer, 284one-way hash, and initialization vector, respectively. 285.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead 286.Bd -literal 287struct crypt_aead { 288 u_int32_t ses; 289 u_int16_t op; /* e.g. COP_ENCRYPT */ 290 u_int16_t flags; 291 u_int len; 292 u_int aadlen; 293 u_int ivlen; 294 caddr_t src, dst; 295 caddr_t aad; 296 caddr_t tag; /* must be large enough for result */ 297 caddr_t iv; 298}; 299 300.Ed 301The 302.Dv CIOCCRYPTAEAD 303is similar to the 304.Dv CIOCCRYPT 305but provides additional data in 306.Fa cr_aead-\*[Gt]aad 307to include in the authentication mode. 308.It Dv CIOCFSESSION Fa u_int32_t ses_id 309Destroys the /dev/crypto session associated with the file-descriptor 310argument. 311.It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ; 312.Bd -literal 313struct crypt_sfop { 314 size_t count; 315 u_int32_t *sesid; 316}; 317 318.Ed 319Destroys the 320.Fa sfop-\*[Gt]count 321sessions specified by the 322.Fa sfop 323array of session identifiers. 324.El 325.\" 326.Sh ASYMMETRIC-KEY OPERATION 327.Ss Asymmetric-key algorithms 328Contingent upon hardware support, the following asymmetric 329(public-key/private-key; or key-exchange subroutine) operations may 330also be available: 331.Pp 332.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact 333.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" 334.It Em " " Ta "Count" Ta "Count" 335.It Dv CRK_MOD_EXP Ta 3 Ta 1 336.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 337.It Dv CRK_DSA_SIGN Ta 5 Ta 2 338.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 339.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 340.El 341.Pp 342See below for discussion of the input and output parameter counts. 343.Ss Asymmetric-key commands 344.Bl -tag -width CIOCKEY 345.It Dv CIOCASYMFEAT Fa int *feature_mask 346Returns a bitmask of supported asymmetric-key operations. 347Each of the above-listed asymmetric operations is present 348if and only if the bit position numbered by the code for that operation 349is set. 350For example, 351.Dv CRK_MOD_EXP 352is available if and only if the bit 353.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP 354is set. 355.It Dv CIOCKEY Fa struct crypt_kop *kop 356.Bd -literal 357struct crypt_kop { 358 u_int crk_op; /* e.g. CRK_MOD_EXP */ 359 u_int crk_status; /* return status */ 360 u_short crk_iparams; /* # of input params */ 361 u_short crk_oparams; /* # of output params */ 362 u_int crk_pad1; 363 struct crparam crk_param[CRK_MAXPARAM]; 364}; 365 366/* Bignum parameter, in packed bytes. */ 367struct crparam { 368 void * crp_p; 369 u_int crp_nbits; 370}; 371 372.Ed 373Performs an asymmetric-key operation from the list above. 374The specific operation is supplied in 375.Fa kop-\*[Gt]crk_op ; 376final status for the operation is returned in 377.Fa kop-\*[Gt]crk_status . 378The number of input arguments and the number of output arguments 379is specified in 380.Fa kop-\*[Gt]crk_iparams 381and 382.Fa kop-\*[Gt]crk_iparams , 383respectively. 384The field 385.Fa crk_param[] 386must be filled in with exactly 387.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams 388arguments, each encoded as a 389.Fa struct crparam 390(address, bitlength) pair. 391.Pp 392The semantics of these arguments are currently undocumented. 393.El 394.Sh SEE ALSO 395.Xr aesni 4 , 396.Xr hifn 4 , 397.Xr ipsec 4 , 398.Xr padlock 4 , 399.Xr safe 4 , 400.Xr ubsec 4 , 401.Xr crypto 7 , 402.Xr geli 8 , 403.Xr crypto 9 404.Sh HISTORY 405The 406.Nm 407driver first appeared in 408.Ox 3.0 . 409The 410.Nm 411driver was imported to 412.Fx 5.0 . 413.Sh BUGS 414Error checking and reporting is weak. 415.Pp 416The values specified for symmetric-key key sizes to 417.Dv CIOCGSESSION 418must exactly match the values expected by 419.Xr opencrypto 9 . 420The output buffer and MAC buffers supplied to 421.Dv CIOCCRYPT 422must follow whether privacy or integrity algorithms were specified for 423session: if you request a 424.No non- Ns Dv NULL 425algorithm, you must supply a suitably-sized buffer. 426.Pp 427The scheme for passing arguments for asymmetric requests is baroque. 428.Pp 429The naming inconsistency between 430.Dv CRIOGET 431and the various 432.Dv CIOC Ns \&* 433names is an unfortunate historical artifact. 434