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-2021 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.\" Portions of this documentation were written by Ararat River 12.\" Consulting, LLC under sponsorship of the FreeBSD Foundation. 13.\" 14.\" This code is derived from software contributed to The NetBSD Foundation 15.\" by Coyote Point Systems, Inc. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.\" 39.\" 40.\" Copyright (c) 2004 41.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved. 42.\" 43.\" Redistribution and use in source and binary forms, with or without 44.\" modification, are permitted provided that the following conditions 45.\" are met: 46.\" 1. Redistributions of source code must retain the above copyright 47.\" notice, this list of conditions and the following disclaimer. 48.\" 2. Redistributions in binary form must reproduce the above copyright 49.\" notice, this list of conditions and the following disclaimer in the 50.\" documentation and/or other materials provided with the distribution. 51.\" 52.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND 53.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 54.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 55.\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD 56.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 57.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 58.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 59.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 60.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 61.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 62.\" THE POSSIBILITY OF SUCH DAMAGE. 63.\" 64.Dd October 6, 2021 65.Dt CRYPTO 4 66.Os 67.Sh NAME 68.Nm crypto , 69.Nm cryptodev 70.Nd user-mode access to hardware-accelerated cryptography 71.Sh SYNOPSIS 72.Cd device crypto 73.Cd device cryptodev 74.Pp 75.In sys/ioctl.h 76.In sys/time.h 77.In crypto/cryptodev.h 78.Sh DESCRIPTION 79The 80.Nm 81driver gives user-mode applications access to hardware-accelerated 82cryptographic transforms as implemented by the 83.Xr crypto 9 84in-kernel interface. 85.Pp 86The 87.Pa /dev/crypto 88special device provides an 89.Xr ioctl 2 90based interface. 91User-mode applications open the special device and 92then issue 93.Xr ioctl 2 94calls on the descriptor. 95User-mode access to 96.Pa /dev/crypto 97is controlled by two 98.Xr sysctl 8 99variables: 100.Ic kern.userasymcrypto 101and 102.Ic kern.cryptodevallowsoft . 103.Pp 104The 105.Nm 106device provides two distinct modes of operation: one mode for 107symmetric-keyed cryptographic requests and digests, and a second mode for 108both asymmetric-key (public-key/private-key) requests and 109modular arithmetic (for Diffie-Hellman key exchange and other 110cryptographic protocols). 111The two modes are described separately below. 112.Sh DEPRECATION NOTICE 113The asymmetric-key operations supported by this interface will not be 114present in 115.Fx 14.0 116and later. 117.Sh THEORY OF OPERATION 118Regardless of whether symmetric-key or asymmetric-key operations are 119to be performed, use of the device requires a basic series of steps: 120.Bl -enum 121.It 122Open the 123.Pa /dev/crypto 124device. 125.It 126If any symmetric-keyed cryptographic or digest operations will be performed, 127create a session with 128.Dv CIOCGSESSION 129or 130.Dv CIOCGSESSION2 . 131Most applications will require at least one symmetric session. 132Since cipher and MAC keys are tied to sessions, many 133applications will require more. 134Asymmetric operations do not use sessions. 135.It 136Submit requests, synchronously with 137.Dv CIOCCRYPT 138(symmetric), 139.Dv CIOCCRYPTAEAD 140(symmetric), 141or 142.Dv CIOCKEY 143(asymmetric). 144.It 145Optionally destroy a session with 146.Dv CIOCFSESSION . 147.It 148Close the 149.Pa /dev/crypto 150device. 151This will automatically close any remaining sessions associated with the 152file desriptor. 153.El 154.Sh SYMMETRIC-KEY OPERATION 155The symmetric-key operation mode provides a context-based API 156to traditional symmetric-key encryption (or privacy) algorithms, 157or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. 158The symmetric-key mode also permits encrypt-then-authenticate fused operation, 159where the hardware performs both a privacy algorithm and an integrity-check 160algorithm in a single pass over the data: either a fused 161encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 162.Pp 163To use symmetric mode, you must first create a session specifying 164the algorithm(s) and key(s) to use; then issue encrypt or decrypt 165requests against the session. 166.Ss Algorithms 167For a list of supported algorithms, see 168.Xr crypto 7 169and 170.Xr crypto 9 . 171.Ss IOCTL Request Descriptions 172.\" 173.Bl -tag -width CIOCGSESSION 174.\" 175.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop 176.Bd -literal 177struct crypt_find_op { 178 int crid; /* driver id + flags */ 179 char name[32]; /* device/driver name */ 180}; 181 182.Ed 183If 184.Fa crid 185is -1, then find the driver named 186.Fa name 187and return the id in 188.Fa crid . 189If 190.Fa crid 191is not -1, return the name of the driver with 192.Fa crid 193in 194.Fa name . 195In either case, if the driver is not found, 196.Dv ENOENT 197is returned. 198.It Dv CIOCGSESSION Fa struct session_op *sessp 199.Bd -literal 200struct session_op { 201 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 202 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 203 204 uint32_t keylen; /* cipher key */ 205 const void *key; 206 int mackeylen; /* mac key */ 207 const void *mackey; 208 209 uint32_t ses; /* returns: ses # */ 210}; 211 212.Ed 213Create a new cryptographic session on a file descriptor for the device; 214that is, a persistent object specific to the chosen 215privacy algorithm, integrity algorithm, and keys specified in 216.Fa sessp . 217The special value 0 for either privacy or integrity 218is reserved to indicate that the indicated operation (privacy or integrity) 219is not desired for this session. 220.Pp 221Multiple sessions may be bound to a single file descriptor. 222The session ID returned in 223.Fa sessp-\*[Gt]ses 224is supplied as a required field in the symmetric-operation structure 225.Fa crypt_op 226for future encryption or hashing requests. 227.\" .Pp 228.\" This implementation will never return a session ID of 0 for a successful 229.\" creation of a session, which is a 230.\" .Nx 231.\" extension. 232.Pp 233For non-zero symmetric-key privacy algorithms, the privacy algorithm 234must be specified in 235.Fa sessp-\*[Gt]cipher , 236the key length in 237.Fa sessp-\*[Gt]keylen , 238and the key value in the octets addressed by 239.Fa sessp-\*[Gt]key . 240.Pp 241For keyed one-way hash algorithms, the one-way hash must be specified 242in 243.Fa sessp-\*[Gt]mac , 244the key length in 245.Fa sessp-\*[Gt]mackey , 246and the key value in the octets addressed by 247.Fa sessp-\*[Gt]mackeylen . 248.\" 249.Pp 250Support for a specific combination of fused privacy and 251integrity-check algorithms depends on whether the underlying 252hardware supports that combination. 253Not all combinations are supported 254by all hardware, even if the hardware supports each operation as a 255stand-alone non-fused operation. 256.It Dv CIOCGSESSION2 Fa struct session2_op *sessp 257.Bd -literal 258struct session2_op { 259 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 260 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 261 262 uint32_t keylen; /* cipher key */ 263 const void *key; 264 int mackeylen; /* mac key */ 265 const void *mackey; 266 267 uint32_t ses; /* returns: ses # */ 268 int crid; /* driver id + flags (rw) */ 269 int ivlen; /* length of nonce/IV */ 270 int maclen; /* length of MAC/tag */ 271 int pad[2]; /* for future expansion */ 272}; 273 274.Ed 275This request is similar to CIOGSESSION but adds additional fields. 276.Pp 277.Fa sessp-\*[Gt]crid 278requests either a specific crypto device or a class of devices (software vs 279hardware). 280.Pp 281.Fa sessp-\*[Gt]ivlen 282specifies the length of the IV or nonce supplied with each request. 283If this field is set to zero, the default IV or nonce length is used. 284.Pp 285.Fa sessp-\*[Gt]maclen 286specifies the length of the MAC or authentication tag supplied or computed by 287each request. 288If this field is set to zero, the full MAC is used. 289.Pp 290The 291.Fa sessp-\*[Gt]pad 292field must be initialized to zero. 293.It Dv CIOCCRYPT Fa struct crypt_op *cr_op 294.Bd -literal 295struct crypt_op { 296 uint32_t ses; 297 uint16_t op; /* e.g. COP_ENCRYPT */ 298 uint16_t flags; 299 u_int len; 300 const void *src; 301 void *dst; 302 void *mac; /* must be large enough for result */ 303 const void *iv; 304}; 305 306.Ed 307Request a symmetric-key (or hash) operation. 308To encrypt, set 309.Fa cr_op-\*[Gt]op 310to 311.Dv COP_ENCRYPT . 312To decrypt, set 313.Fa cr_op-\*[Gt]op 314to 315.Dv COP_DECRYPT . 316The field 317.Fa cr_op-\*[Gt]len 318supplies the length of the input buffer; the fields 319.Fa cr_op-\*[Gt]src , 320.Fa cr_op-\*[Gt]dst , 321.Fa cr_op-\*[Gt]mac , 322.Fa cr_op-\*[Gt]iv 323supply the addresses of the input buffer, output buffer, 324one-way hash, and initialization vector, respectively. 325.Pp 326If a session is using either fused encrypt-then-authenticate or 327an AEAD algorithm, 328decryption operations require the associated hash as an input. 329If the hash is incorrect, the 330operation will fail with 331.Dv EBADMSG 332and the output buffer will remain unchanged. 333.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead 334.Bd -literal 335struct crypt_aead { 336 uint32_t ses; 337 uint16_t op; /* e.g. COP_ENCRYPT */ 338 uint16_t flags; 339 u_int len; 340 u_int aadlen; 341 u_int ivlen; 342 const void *src; 343 void *dst; 344 const void *aad; /* additional authenticated data */ 345 void *tag; /* must fit for chosen TAG length */ 346 const void *iv; 347}; 348 349.Ed 350The 351.Dv CIOCCRYPTAEAD 352is similar to the 353.Dv CIOCCRYPT 354but provides additional data in 355.Fa cr_aead-\*[Gt]aad 356to include in the authentication mode. 357.It Dv CIOCFSESSION Fa u_int32_t ses_id 358Destroys the session identified by 359.Fa ses_id . 360.El 361.\" 362.Sh ASYMMETRIC-KEY OPERATION 363.Ss Asymmetric-key algorithms 364Contingent upon hardware support, the following asymmetric 365(public-key/private-key; or key-exchange subroutine) operations may 366also be available: 367.Pp 368.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact 369.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" 370.It Em " " Ta "Count" Ta "Count" 371.It Dv CRK_MOD_EXP Ta 3 Ta 1 372.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 373.It Dv CRK_DSA_SIGN Ta 5 Ta 2 374.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 375.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 376.El 377.Pp 378See below for discussion of the input and output parameter counts. 379.Ss Asymmetric-key commands 380.Bl -tag -width CIOCKEY 381.It Dv CIOCASYMFEAT Fa int *feature_mask 382Returns a bitmask of supported asymmetric-key operations. 383Each of the above-listed asymmetric operations is present 384if and only if the bit position numbered by the code for that operation 385is set. 386For example, 387.Dv CRK_MOD_EXP 388is available if and only if the bit 389.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EXP 390is set. 391.It Dv CIOCKEY Fa struct crypt_kop *kop 392.Bd -literal 393struct crypt_kop { 394 u_int crk_op; /* e.g. CRK_MOD_EXP */ 395 u_int crk_status; /* return status */ 396 u_short crk_iparams; /* # of input params */ 397 u_short crk_oparams; /* # of output params */ 398 u_int crk_pad1; 399 struct crparam crk_param[CRK_MAXPARAM]; 400}; 401 402/* Bignum parameter, in packed bytes. */ 403struct crparam { 404 void * crp_p; 405 u_int crp_nbits; 406}; 407 408.Ed 409Performs an asymmetric-key operation from the list above. 410The specific operation is supplied in 411.Fa kop-\*[Gt]crk_op ; 412final status for the operation is returned in 413.Fa kop-\*[Gt]crk_status . 414The number of input arguments and the number of output arguments 415is specified in 416.Fa kop-\*[Gt]crk_iparams 417and 418.Fa kop-\*[Gt]crk_iparams , 419respectively. 420The field 421.Fa crk_param[] 422must be filled in with exactly 423.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams 424arguments, each encoded as a 425.Fa struct crparam 426(address, bitlength) pair. 427.Pp 428The semantics of these arguments are currently undocumented. 429.El 430.Sh SEE ALSO 431.Xr aesni 4 , 432.Xr hifn 4 , 433.Xr ipsec 4 , 434.Xr padlock 4 , 435.Xr safe 4 , 436.Xr crypto 7 , 437.Xr geli 8 , 438.Xr crypto 9 439.Sh HISTORY 440The 441.Nm 442driver first appeared in 443.Ox 3.0 . 444The 445.Nm 446driver was imported to 447.Fx 5.0 . 448.Sh BUGS 449Error checking and reporting is weak. 450.Pp 451The values specified for symmetric-key key sizes to 452.Dv CIOCGSESSION 453must exactly match the values expected by 454.Xr opencrypto 9 . 455The output buffer and MAC buffers supplied to 456.Dv CIOCCRYPT 457must follow whether privacy or integrity algorithms were specified for 458session: if you request a 459.No non- Ns Dv NULL 460algorithm, you must supply a suitably-sized buffer. 461.Pp 462The scheme for passing arguments for asymmetric requests is baroque. 463