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