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 the 98.Ic kern.cryptodevallowsoft 99.Xr sysctl 8 100variable. 101If this variable is zero, 102then user-mode sessions are only permitted to use cryptography coprocessors. 103.Sh THEORY OF OPERATION 104Use of the device requires a basic series of steps: 105.Bl -enum 106.It 107Open the 108.Pa /dev/crypto 109device. 110.It 111Create a session with 112.Dv CIOCGSESSION 113or 114.Dv CIOCGSESSION2 . 115Applications will require at least one symmetric session. 116Since cipher and MAC keys are tied to sessions, many 117applications will require more. 118.It 119Submit requests, synchronously with 120.Dv CIOCCRYPT 121or 122.Dv CIOCCRYPTAEAD . 123.It 124Optionally destroy a session with 125.Dv CIOCFSESSION . 126.It 127Close the 128.Pa /dev/crypto 129device. 130This will automatically close any remaining sessions associated with the 131file descriptor. 132.El 133.Sh SYMMETRIC-KEY OPERATION 134.Nm cryptodev 135provides a context-based API 136to traditional symmetric-key encryption (or privacy) algorithms, 137keyed and unkeyed one-way hash (HMAC and MAC) algorithms, 138encrypt-then-authenticate (ETA) fused operations, 139and authenticated encryption with additional data (AEAD) operations. 140For ETA operations, 141drivers perform both a privacy algorithm and an integrity-check 142algorithm in a single pass over the data: either a fused 143encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 144Similarly, for AEAD operations, 145drivers perform either an encrypt/MAC-generate operation 146or a MAC-verify/decrypt operation. 147.Pp 148The algorithm(s) and key(s) to use are specified when a session is 149created. 150Individual requests are able to specify per-request initialization vectors 151or nonces. 152.Ss Algorithms 153For a list of supported algorithms, see 154.Xr crypto 7 . 155.Ss IOCTL Request Descriptions 156.\" 157.Bl -tag -width CIOCGSESSION 158.\" 159.It Dv CIOCFINDDEV Fa struct crypt_find_op *fop 160.Bd -literal 161struct crypt_find_op { 162 int crid; /* driver id + flags */ 163 char name[32]; /* device/driver name */ 164}; 165 166.Ed 167If 168.Fa crid 169is -1, then find the driver named 170.Fa name 171and return the id in 172.Fa crid . 173If 174.Fa crid 175is not -1, return the name of the driver with 176.Fa crid 177in 178.Fa name . 179In either case, if the driver is not found, 180.Dv ENOENT 181is returned. 182.It Dv CIOCGSESSION Fa struct session_op *sessp 183.Bd -literal 184struct session_op { 185 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 186 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 187 188 uint32_t keylen; /* cipher key */ 189 const void *key; 190 int mackeylen; /* mac key */ 191 const void *mackey; 192 193 uint32_t ses; /* returns: ses # */ 194}; 195 196.Ed 197Create a new cryptographic session on a file descriptor for the device; 198that is, a persistent object specific to the chosen 199privacy algorithm, integrity algorithm, and keys specified in 200.Fa sessp . 201The special value 0 for either privacy or integrity 202is reserved to indicate that the indicated operation (privacy or integrity) 203is not desired for this session. 204ETA sessions specify both privacy and integrity algorithms. 205AEAD sessions specify only a privacy algorithm. 206.Pp 207Multiple sessions may be bound to a single file descriptor. 208The session ID returned in 209.Fa sessp-\*[Gt]ses 210is supplied as a required field in the operation structure 211.Fa crypt_op 212for future encryption or hashing requests. 213.\" .Pp 214.\" This implementation will never return a session ID of 0 for a successful 215.\" creation of a session, which is a 216.\" .Nx 217.\" extension. 218.Pp 219For non-zero privacy algorithms, the privacy algorithm 220must be specified in 221.Fa sessp-\*[Gt]cipher , 222the key length in 223.Fa sessp-\*[Gt]keylen , 224and the key value in the octets addressed by 225.Fa sessp-\*[Gt]key . 226.Pp 227For keyed one-way hash algorithms, the one-way hash must be specified 228in 229.Fa sessp-\*[Gt]mac , 230the key length in 231.Fa sessp-\*[Gt]mackey , 232and the key value in the octets addressed by 233.Fa sessp-\*[Gt]mackeylen . 234.\" 235.Pp 236Support for a specific combination of fused privacy and 237integrity-check algorithms depends on whether the underlying 238hardware supports that combination. 239Not all combinations are supported 240by all hardware, even if the hardware supports each operation as a 241stand-alone non-fused operation. 242.It Dv CIOCGSESSION2 Fa struct session2_op *sessp 243.Bd -literal 244struct session2_op { 245 uint32_t cipher; /* e.g. CRYPTO_AES_CBC */ 246 uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */ 247 248 uint32_t keylen; /* cipher key */ 249 const void *key; 250 int mackeylen; /* mac key */ 251 const void *mackey; 252 253 uint32_t ses; /* returns: ses # */ 254 int crid; /* driver id + flags (rw) */ 255 int ivlen; /* length of nonce/IV */ 256 int maclen; /* length of MAC/tag */ 257 int pad[2]; /* for future expansion */ 258}; 259 260.Ed 261This request is similar to CIOGSESSION but adds additional fields. 262.Pp 263.Fa sessp-\*[Gt]crid 264requests either a specific crypto device or a class of devices (software vs 265hardware). 266.Pp 267.Fa sessp-\*[Gt]ivlen 268specifies the length of the IV or nonce supplied with each request. 269If this field is set to zero, the default IV or nonce length is used. 270.Pp 271.Fa sessp-\*[Gt]maclen 272specifies the length of the MAC or authentication tag supplied or computed by 273each request. 274If this field is set to zero, the full MAC is used. 275.Pp 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 an encryption/decryption (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.Sh SEE ALSO 348.Xr aesni 4 , 349.Xr hifn 4 , 350.Xr ipsec 4 , 351.Xr padlock 4 , 352.Xr safe 4 , 353.Xr crypto 7 , 354.Xr geli 8 , 355.Xr crypto 9 356.Sh HISTORY 357The 358.Nm 359driver first appeared in 360.Ox 3.0 . 361The 362.Nm 363driver was imported to 364.Fx 5.0 . 365.Sh BUGS 366Error checking and reporting is weak. 367.Pp 368The values specified for symmetric-key key sizes to 369.Dv CIOCGSESSION 370must exactly match the values expected by 371.Xr opencrypto 9 . 372The output buffer and MAC buffers supplied to 373.Dv CIOCCRYPT 374must follow whether privacy or integrity algorithms were specified for 375session: if you request a 376.No non- Ns Dv NULL 377algorithm, you must supply a suitably-sized buffer. 378