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