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.\" $FreeBSD$ 65.\" 66.Dd October 6, 2021 67.Dt CRYPTO 4 68.Os 69.Sh NAME 70.Nm crypto , 71.Nm cryptodev 72.Nd user-mode access to hardware-accelerated cryptography 73.Sh SYNOPSIS 74.Cd device crypto 75.Cd device cryptodev 76.Pp 77.In sys/ioctl.h 78.In sys/time.h 79.In crypto/cryptodev.h 80.Sh DESCRIPTION 81The 82.Nm 83driver gives user-mode applications access to hardware-accelerated 84cryptographic transforms as implemented by the 85.Xr crypto 9 86in-kernel interface. 87.Pp 88The 89.Pa /dev/crypto 90special device provides an 91.Xr ioctl 2 92based interface. 93User-mode applications open the special device and 94then issue 95.Xr ioctl 2 96calls on the descriptor. 97User-mode access to 98.Pa /dev/crypto 99is controlled by the 100.Ic kern.cryptodevallowsoft 101.Xr sysctl 8 102variable. 103If this variable is zero, 104then user-mode sessions are only permitted to use cryptography coprocessors. 105.Sh THEORY OF OPERATION 106Use of the device requires a basic series of steps: 107.Bl -enum 108.It 109Open the 110.Pa /dev/crypto 111device. 112.It 113Create a session with 114.Dv CIOCGSESSION 115or 116.Dv CIOCGSESSION2 . 117Applications will require at least one symmetric session. 118Since cipher and MAC keys are tied to sessions, many 119applications will require more. 120.It 121Submit requests, synchronously with 122.Dv CIOCCRYPT 123or 124.Dv CIOCCRYPTAEAD . 125.It 126Optionally destroy a session with 127.Dv CIOCFSESSION . 128.It 129Close the 130.Pa /dev/crypto 131device. 132This will automatically close any remaining sessions associated with the 133file desriptor. 134.El 135.Sh SYMMETRIC-KEY OPERATION 136.Nm cryptodev 137provides a context-based API 138to traditional symmetric-key encryption (or privacy) algorithms, 139keyed and unkeyed one-way hash (HMAC and MAC) algorithms, 140encrypt-then-authenticate (ETA) fused operations, 141and authenticated encryption with additional data (AEAD) operations. 142For ETA operations, 143drivers perform both a privacy algorithm and an integrity-check 144algorithm in a single pass over the data: either a fused 145encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 146Similarly, for AEAD operations, 147drivers perform either an encrypt/MAC-generate operation 148or a MAC-verify/decrypt operation. 149.Pp 150The algorithm(s) and key(s) to use are specified when a session is 151created. 152Individual requests are able to specify per-request initialization vectors 153or nonces. 154.Ss Algorithms 155For a list of supported algorithms, see 156.Xr crypto 7 . 157.Ss IOCTL Request Descriptions 158.\" 159.Bl -tag -width CIOCGSESSION 160.\" 161.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop 162.Bd -literal 163struct crypt_find_op { 164 int crid; /* driver id + flags */ 165 char name[32]; /* device/driver name */ 166}; 167 168.Ed 169If 170.Fa crid 171is -1, then find the driver named 172.Fa name 173and return the id in 174.Fa crid . 175If 176.Fa crid 177is not -1, return the name of the driver with 178.Fa crid 179in 180.Fa name . 181In either case, if the driver is not found, 182.Dv ENOENT 183is returned. 184.It Dv CIOCGSESSION Fa struct session_op *sessp 185.Bd -literal 186struct session_op { 187 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 188 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 189 190 uint32_t keylen; /* cipher key */ 191 const void *key; 192 int mackeylen; /* mac key */ 193 const void *mackey; 194 195 uint32_t ses; /* returns: ses # */ 196}; 197 198.Ed 199Create a new cryptographic session on a file descriptor for the device; 200that is, a persistent object specific to the chosen 201privacy algorithm, integrity algorithm, and keys specified in 202.Fa sessp . 203The special value 0 for either privacy or integrity 204is reserved to indicate that the indicated operation (privacy or integrity) 205is not desired for this session. 206ETA sessions specify both privacy and integrity algorithms. 207AEAD sessions specify only a privacy algorithm. 208.Pp 209Multiple sessions may be bound to a single file descriptor. 210The session ID returned in 211.Fa sessp-\*[Gt]ses 212is supplied as a required field in the operation structure 213.Fa crypt_op 214for future encryption or hashing requests. 215.\" .Pp 216.\" This implementation will never return a session ID of 0 for a successful 217.\" creation of a session, which is a 218.\" .Nx 219.\" extension. 220.Pp 221For non-zero privacy algorithms, the privacy algorithm 222must be specified in 223.Fa sessp-\*[Gt]cipher , 224the key length in 225.Fa sessp-\*[Gt]keylen , 226and the key value in the octets addressed by 227.Fa sessp-\*[Gt]key . 228.Pp 229For keyed one-way hash algorithms, the one-way hash must be specified 230in 231.Fa sessp-\*[Gt]mac , 232the key length in 233.Fa sessp-\*[Gt]mackey , 234and the key value in the octets addressed by 235.Fa sessp-\*[Gt]mackeylen . 236.\" 237.Pp 238Support for a specific combination of fused privacy and 239integrity-check algorithms depends on whether the underlying 240hardware supports that combination. 241Not all combinations are supported 242by all hardware, even if the hardware supports each operation as a 243stand-alone non-fused operation. 244.It Dv CIOCGSESSION2 Fa struct session2_op *sessp 245.Bd -literal 246struct session2_op { 247 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 248 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 249 250 uint32_t keylen; /* cipher key */ 251 const void *key; 252 int mackeylen; /* mac key */ 253 const void *mackey; 254 255 uint32_t ses; /* returns: ses # */ 256 int crid; /* driver id + flags (rw) */ 257 int ivlen; /* length of nonce/IV */ 258 int maclen; /* length of MAC/tag */ 259 int pad[2]; /* for future expansion */ 260}; 261 262.Ed 263This request is similar to CIOGSESSION but adds additional fields. 264.Pp 265.Fa sessp-\*[Gt]crid 266requests either a specific crypto device or a class of devices (software vs 267hardware). 268.Pp 269.Fa sessp-\*[Gt]ivlen 270specifies the length of the IV or nonce supplied with each request. 271If this field is set to zero, the default IV or nonce length is used. 272.Pp 273.Fa sessp-\*[Gt]maclen 274specifies the length of the MAC or authentication tag supplied or computed by 275each request. 276If this field is set to zero, the full MAC is used. 277.Pp 278The 279.Fa sessp-\*[Gt]pad 280field must be initialized to zero. 281.It Dv CIOCCRYPT Fa struct crypt_op *cr_op 282.Bd -literal 283struct crypt_op { 284 uint32_t ses; 285 uint16_t op; /* e.g. COP_ENCRYPT */ 286 uint16_t flags; 287 u_int len; 288 const void *src; 289 void *dst; 290 void *mac; /* must be large enough for result */ 291 const void *iv; 292}; 293 294.Ed 295Request an encryption/decryption (or hash) operation. 296To encrypt, set 297.Fa cr_op-\*[Gt]op 298to 299.Dv COP_ENCRYPT . 300To decrypt, set 301.Fa cr_op-\*[Gt]op 302to 303.Dv COP_DECRYPT . 304The field 305.Fa cr_op-\*[Gt]len 306supplies the length of the input buffer; the fields 307.Fa cr_op-\*[Gt]src , 308.Fa cr_op-\*[Gt]dst , 309.Fa cr_op-\*[Gt]mac , 310.Fa cr_op-\*[Gt]iv 311supply the addresses of the input buffer, output buffer, 312one-way hash, and initialization vector, respectively. 313.Pp 314If a session is using either fused encrypt-then-authenticate or 315an AEAD algorithm, 316decryption operations require the associated hash as an input. 317If the hash is incorrect, the 318operation will fail with 319.Dv EBADMSG 320and the output buffer will remain unchanged. 321.It Dv CIOCCRYPTAEAD Fa struct crypt_aead *cr_aead 322.Bd -literal 323struct crypt_aead { 324 uint32_t ses; 325 uint16_t op; /* e.g. COP_ENCRYPT */ 326 uint16_t flags; 327 u_int len; 328 u_int aadlen; 329 u_int ivlen; 330 const void *src; 331 void *dst; 332 const void *aad; /* additional authenticated data */ 333 void *tag; /* must fit for chosen TAG length */ 334 const void *iv; 335}; 336 337.Ed 338The 339.Dv CIOCCRYPTAEAD 340is similar to the 341.Dv CIOCCRYPT 342but provides additional data in 343.Fa cr_aead-\*[Gt]aad 344to include in the authentication mode. 345.It Dv CIOCFSESSION Fa u_int32_t ses_id 346Destroys the session identified by 347.Fa ses_id . 348.El 349.Sh SEE ALSO 350.Xr aesni 4 , 351.Xr hifn 4 , 352.Xr ipsec 4 , 353.Xr padlock 4 , 354.Xr safe 4 , 355.Xr crypto 7 , 356.Xr geli 8 , 357.Xr crypto 9 358.Sh HISTORY 359The 360.Nm 361driver first appeared in 362.Ox 3.0 . 363The 364.Nm 365driver was imported to 366.Fx 5.0 . 367.Sh BUGS 368Error checking and reporting is weak. 369.Pp 370The values specified for symmetric-key key sizes to 371.Dv CIOCGSESSION 372must exactly match the values expected by 373.Xr opencrypto 9 . 374The output buffer and MAC buffers supplied to 375.Dv CIOCCRYPT 376must follow whether privacy or integrity algorithms were specified for 377session: if you request a 378.No non- Ns Dv NULL 379algorithm, you must supply a suitably-sized buffer. 380