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