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