1.\" $NetBSD: crypto.4,v 1.10 2006/09/23 20:38:51 elad Exp $ 2.\" 3.\" Copyright (c) 2004 4.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD 19.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 20.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 21.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 22.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 23.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 24.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 25.\" THE POSSIBILITY OF SUCH DAMAGE. 26.\" 27.Dd September 23, 2006 28.Dt CRYPTO 4 29.Os 30.Sh NAME 31.Nm crypto , 32.Nm swcrypto 33.Nd user-mode access to hardware-accelerated cryptography 34.Sh SYNOPSIS 35.Cd "hifn* at pci? dev ? function ?" 36.Cd "ubsec* at pci? dev ? function ?" 37.Pp 38.Cd pseudo-device crypto 39.Cd pseudo-device swcrypto 40.Pp 41.In sys/ioctl.h 42.In sys/time.h 43.In crypto/cryptodev.h 44.Sh DESCRIPTION 45The 46.Nm 47driver gives user-mode applications access to hardware-accelerated 48cryptographic transforms, as implemented by the 49.Xr opencrypto 9 50in-kernel interface. 51The 52.Cm swcrypto 53driver is a software-only implementation of the 54.Xr opencrypto 9 55interface, and must be included to use the interface without hardware 56acceleration. 57The 58.Pa /dev/crypto 59special device provides an 60.Xr ioctl 2 61based interface. 62User-mode applications should open the special device, 63then issue 64.Xr ioctl 2 65calls on the descriptor. 66The 67.Nm 68device provides two distinct modes of operation: one mode for 69symmetric-keyed cryptographic requests, and a second mode for 70both asymmetric-key (public-key/private-key) requests, and for 71modular exponentiation (for Diffie-Hellman key exchange). 72The two modes are described separately below. 73.Sh SYMMETRIC-KEY OPERATION 74The symmetric-key operation mode provides a context-based API 75to traditional symmetric-key encryption (or privacy) algorithms, 76or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. 77The symmetric-key mode also permits fused operation, 78where the hardware performs both a privacy algorithm and an integrity-check 79algorithm in a single pass over the data: either a fused 80encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 81.Pp 82To use symmetric mode, you must first create a session specifying 83the algorithm(s) and key(s) to use; then issue encrypt or decrypt 84requests against the session. 85.Ss Symmetric-key privacy algorithms 86Contingent upon device drivers for installed cryptographic hardware 87registering with 88.Xr opencrypto 9 , 89as providers of a given algorithm, some or all of the following 90symmetric-key privacy algorithms may be available: 91.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 92.It CRYPTO_DES_CBC 93.It CRYPTO_3DES_CBC 94.It CRYPTO_BLF_CBC 95.It CRYPTO_CAST_CBC 96.It CRYPTO_SKIPJACK_CBC 97.It CRYPTO_AES_CBC 98.It CRYPTO_ARC4 99.El 100.Ss Integrity-check operations 101Contingent upon hardware support, some or all of the following 102keyed one-way hash algorithms may be available: 103.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 104.It CRYPTO_RIPEMD160_HMAC 105.It CRYPTO_MD5_KPDK 106.It CRYPTO_SHA1_KPDK 107.It CRYPTO_MD5_HMAC 108.It CRYPTO_SHA1_HMAC 109.It CRYPTO_SHA2_HMAC 110.It CRYPTO_MD5 111.It CRYPTO_SHA1 112.El 113The 114.Em CRYPTO_MD5 115and 116.Em CRYPTO_SHA1 117algorithms are actually unkeyed, but should be requested 118as symmetric-key hash algorithms with a zero-length key. 119.Ss IOCTL Request Descriptions 120.\" 121.Bl -tag -width CIOCFKEY 122.\" 123.It Dv CRIOGET Fa int *fd 124Clone the fd argument to 125.Xr ioctl 4 , 126yielding a new file descriptor which can be used to create 127crypto sessions and request crypto operations. 128.\" 129.It Dv CIOCGSESSION Fa struct session_op *sessp 130Persistently bind a file descriptor returned by a previous 131.Dv CRIOGET 132to a session: that is, to the chosen privacy algorithm, integrity 133algorithm, and keys specified in 134.Fa sessp . 135The special value 0 for either privacy or integrity 136is reserved to indicate that the indicated operation (privacy or integrity) 137is not desired for this session. 138.Pp 139For non-zero symmetric-key privacy algorithms, the privacy algorithm 140must be specified in 141.Fa sess-\*[Gt]cipher , 142the key length in 143.Fa sessp-\*[Gt]keylen , 144and the key value in the octets addressed by 145.Fa sessp-\*[Gt]key . 146.Pp 147For keyed one-way hash algorithms, the one-way hash must be specified 148in 149.Fa sessp-\*[Gt]mac , 150the key length in 151.Fa sessp-\*[Gt]mackey , 152and the key value in the octets addressed by 153.Fa sessp-\*[Gt]mackeylen . 154.\" 155.Pp 156Support for a specific combination of fused privacy and 157integrity-check algorithms depends on whether the underlying 158hardware supports that combination. 159Not all combinations are supported 160by all hardware, even if the hardware supports each operation as a 161stand-alone non-fused operation. 162.It Dv CIOCCRYPT Fa struct crypt_op *cr_op 163Request a symmetric-key (or unkeyed hash) operation. 164The file descriptor argument to 165.Xr ioctl 4 166must have been bound to a valid session. 167To encrypt, set 168.Fa cr_op-\*[Gt]op 169to 170.Dv COP_ENCRYPT . 171To decrypt, set 172.Fa cr_op-\*[Gt]op 173to 174.Dv COP_DECRYPT . 175The field 176.Fa cr_op-\*[Gt]len 177supplies the length of the input buffer; the fields 178.Fa cr_op-\*[Gt]src , 179.Fa cr_op-\*[Gt]dst , 180.Fa cr_op-\*[Gt]mac , 181.Fa cr_op-\*[Gt]iv 182supply the addresses of the input buffer, output buffer, 183one-way hash, and initialization vector, respectively. 184.It Dv CIOCFSESSION Fa void 185Destroys the /dev/crypto session associated with the file-descriptor 186argument. 187.El 188.\" 189.Sh ASYMMETRIC-KEY OPERATION 190.Ss Asymmetric-key algorithms 191Contingent upon hardware support, the following asymmetric 192(public-key/private-key; or key-exchange subroutine) operations may 193also be available: 194.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact 195.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" 196.It Em " " Ta "Count" Ta "Count" 197.It Dv CRK_MOD_EXP Ta 3 Ta 1 198.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 199.It Dv CRK_DSA_SIGN Ta 5 Ta 2 200.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 201.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 202.El 203.Pp 204See below for discussion of the input and output parameter counts. 205.Ss Asymmetric-key commands 206.Bl -tag -width CIOCFKEY 207.It Dv CIOCASSYMFEAT Fa int *feature_mask 208Returns a bitmask of supported asymmetric-key operations. 209Each of the above-listed asymmetric operations is present 210if and only if the bit position numbered by the code for that operation 211is set. 212For example, 213.Dv CRK_MOD_EXP 214is available if and only if the bit 215.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EX 216is set. 217.It Dv CIOCFKEY Fa struct crypt_kop *kop 218Performs an asymmetric-key operation from the list above. 219The specific operation is supplied in 220.Fa kop-\*[Gt]crk_op ; 221final status for the operation is returned in 222.Fa kop-\*[Gt]crk_status . 223The number of input arguments and the number of output arguments 224is specified in 225.Fa kop-\*[Gt]crk_iparams 226and 227.Fa kop-\*[Gt]crk_iparams , 228respectively. 229The field 230.Fa crk_param[] 231must be filled in with exactly 232.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams 233arguments, each encoded as a 234.Fa struct crparam 235(address, bitlength) pair. 236.El 237.Pp 238The semantics of these arguments are currently undocumented. 239.Sh SEE ALSO 240.Xr hifn 4 , 241.Xr ubsec 4 , 242.Xr opencrypto 9 243.Sh HISTORY 244The 245.Nm 246driver is derived from a version which appeared in 247.Fx 4.8 , 248which in turn is based on code which appeared in 249.Ox 3.2 . 250.Sh BUGS 251Error checking and reporting is weak. 252The values specified for symmetric-key key sizes to 253.Dv CIOCGSESSION 254must exactly match the values expected by 255.Xr opencrypto 9 . 256The output buffer and MAC buffers supplied to 257.Dv CIOCCRYPT 258must follow whether privacy or integrity algorithms were specified for 259session: if you request a 260.No non- Ns Dv NULL 261algorithm, you must supply a suitably-sized buffer. 262.Pp 263The scheme for passing arguments for asymmetric requests is Baroque. 264.Pp 265The naming inconsistency between 266.Dv CRIOGET 267and the various 268.Dv CIOC Ns \&* 269names is an unfortunate historical artifact. 270