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