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