1.\" $NetBSD: crypto.4,v 1.5 2004/04/29 19:42:29 jonathan 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 April 27, 2004 28.Dt CRYPTO 4 29.Os 30.Sh NAME 31.Nm crypto 32.Nd user-mode access to hardware-accelerated cryptography 33.Sh SYNOPSIS 34.Cd "hifn* at pci? dev ? function ?" 35.Cd "ubsec* at pci? dev ? function ?" 36.Pp 37.Cd pseudo-device crypto 38.Pp 39.In sys/ioctl.h 40.In sys/time.h 41.In crypto/cryptodev.h 42.Sh DESCRIPTION 43The 44.Nm 45driver gives user-mode applications access to hardware-accelerated 46cryptographic transforms, as implemented by the 47.Xr opencrypto 9 48in-kernel interface. 49The 50.Pa /dev/crypto 51special device provides an 52.Xr ioctl 2 53based interface. 54User-mode applications should open the special device, 55then issue 56.Xr ioctl 2 57calls on the descriptor. 58The 59.Nm 60device provides two distinct modes of operation: one mode for 61symmetric-keyed cryptographic requests, and a second mode for 62both asymmetric-key (public-key/private-key) requests, and for 63modular exponentiation (for Diffie-Hellman key exchange). 64The two modes are described separately below. 65.Sh SYMMETRIC-KEY OPERATION 66The symmetric-key operation mode provides a context-based API 67to traditional symmetric-key encryption (or privacy) algorithms, 68or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. 69The symmetric-key mode also permits fused operation, 70where the hardware performs both a privacy algorithm and an integrity-check 71algorithm in a single pass over the data: either a fused 72encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 73.Pp 74To use symmetric mode, you must first create a session specifying 75the algorithm(s) and key(s) to use; then issue encrypt or decrypt 76requests against the session. 77.Ss Symmetric-key privacy algorithms 78Contingent upon device drivers for installed cryptographic hardware 79registering with 80.Xr opencrypto 9 , 81as providers of a given algorithm, some or all of the following 82symmetric-key privacy algorithms may be available: 83.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 84.It CRYPTO_DES_CBC 85.It CRYPTO_3DES_CBC 86.It CRYPTO_BLF_CBC 87.It CRYPTO_CAST_CBC 88.It CRYPTO_SKIPJACK_CBC 89.It CRYPTO_AES_CBC 90.It CRYPTO_ARC4 91.El 92.Ss Integrity-check operations 93Contingent upon hardware support, some or all of the following 94keyed one-way hash algorithms may be available: 95.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 96.It CRYPTO_RIPEMD160_HMAC 97.It CRYPTO_MD5_KPDK 98.It CRYPTO_SHA1_KPDK 99.It CRYPTO_MD5_HMAC 100.It CRYPTO_SHA1_HMAC 101.It CRYPTO_SHA2_HMAC 102.It CRYPTO_MD5 103.It CRYPTO_SHA1 104.El 105The 106.Em CRYPTO_MD5 107and 108.Em CRYPTO_SHA1 109algorithms are actually unkeyed, but should be requested 110as symmetric-key hash algorithms with a zero-length key. 111.Ss IOCTL Request Descriptions 112.\" 113.Bl -tag -width CIOCFKEY 114.\" 115.It Dv CRIOCGET Fa int *fd 116Clone the fd argument to 117.Xr ioctl 4 , 118yielding a new file descriptor which can be used to create 119crypto sessions and request crypto operations. 120.\" 121.It Dv CRIOCGSESSION Fa struct session_op *sessp 122Persistently bind a file descriptor returned by a previous 123.Dv CRIOCGET 124to a session: that is, to the chosen privacy algorithm, integrity 125algorithm, and keys specified in 126.Fa sessp . 127The special value 0 for either privacy or integrity 128is reserved to indicate that the indicated operation (privacy or integrity) 129is not desired for this session. 130.Pp 131For non-zero symmetric-key privacy algorithms, the privacy algorithm 132must be specified in 133.Fa sess-\*[Gt]cipher , 134the key length in 135.Fa sessp-\*[Gt]keylen , 136and the key value in the octets addressed by 137.Fa sessp-\*[Gt]key . 138.Pp 139For keyed one-way hash algorithms, the one-way hash must be specified 140in 141.Fa sessp-\*[Gt]mac , 142the key length in 143.Fa sessp-\*[Gt]mackey , 144and the key value in the octets addressed by 145.Fa sessp-\*[Gt]mackeylen . 146.\" 147.Pp 148Support for a specific combination of fused privacy and 149integrity-check algorithms depends on whether the underlying 150hardware supports that combination. 151Not all combinations are supported 152by all hardware, even if the hardware supports each operation as a 153stand-alone non-fused operation. 154.It Dv CIOCCRYPT Fa struct crpyto_op *cr_op 155Request a symmetric-key (or unkeyed hash) operation. 156The file descriptor argument to 157.Xr ioctl 4 158must have been bound to a valid session. 159To encrypt, set 160.Fa cr_op-\*[Gt]op 161to 162.Dv COP_ENCRYPT . 163To decrypt, set 164.Fa cr_op-\*[Gt]op 165to 166.Dv COP_DECRYPT . 167The field 168.Fa cr_op-\*[Gt]len 169supplies the length of the input buffer; the fields 170.Fa cr_op-\*[Gt]src , 171.Fa cr_op-\*[Gt]dst , 172.Fa cr_op-\*[Gt]mac , 173.Fa cr_op-\*[Gt]iv 174supply the addresses of the input buffer, output buffer, 175one-way hash, and initialization vector, respectively. 176.It Dv CIOCFSESSION Fa void 177Destroys the /dev/crypto session associated with the file-descriptor 178argument. 179.El 180.\" 181.Sh ASYMMETRIC-KEY OPERATION 182.Ss Asymmetric-key algorithms 183Contingent upon hardware support, the following asymmetric 184(public-key/private-key; or key-exchange subroutine) operations may 185also be available: 186.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact 187.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" 188.It Em " " Ta "Count" Ta "Count" 189.It Dv CRK_MOD_EXP Ta 3 Ta 1 190.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 191.It Dv CRK_DSA_SIGN Ta 5 Ta 2 192.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 193.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 194.El 195.Pp 196See below for discussion of the input and output parameter counts. 197.Ss Asymmetric-key commands 198.Bl -tag -width CIOCFKEY 199.It Dv CIOCASSYMFEAT Fa int *feature_mask 200Returns a bitmask of supported asymmetric-key operations. 201Each of the above-listed asymmetric operations is present 202if and only if the bit position numbered by the code for that operation 203is set. 204For example, 205.Dv CRK_MOD_EXP 206is available if and only if the bit 207.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EX 208is set. 209.It Dv CIOCFKEY Fa struct crypt_kop *kop 210Performs an asymmetric-key operation from the list above. 211The specific operation is supplied in 212.Fa kop-\*[Gt]crk_op ; 213final status for the operation is returned in 214.Fa kop-\*[Gt]crk_status . 215The number of input arguments and the number of output arguments 216is specified in 217.Fa kop-\*[Gt]crk_iparams 218and 219.Fa kop-\*[Gt]crk_iparams , 220respectively. 221The field 222.Fa crk_param[] 223must be filled in with exactly 224.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams 225arguments, each encoded as a 226.Fa struct crparam 227(address, bitlength) pair. 228.El 229.Pp 230The semantics of these arguments are currently undocumented. 231.Sh SEE ALSO 232.Xr hifn 4 , 233.Xr ubsec 4 , 234.Xr opencrypto 9 235.Sh HISTORY 236The 237.Nm 238driver is derived from a version which appeared in 239.Fx 4.8 , 240which in turn is based on code which appeared in 241.Ox 3.2 . 242.Sh BUGS 243Error checking and reporting is weak. 244The values specified for symmetric-key key sizes to 245.Dv CRIOCGSESSION 246must exactly match the values expected by 247.XR opencrypto 9 . 248The output buffer and MAC buffers supplied to 249.Dv CRIOCRYPT 250must follow whether privacy or integrity algorithms were specified for 251session: if you request a 252.No non- Ns Dv NULL 253algorithm, you must supply a suitably-sized buffer. 254.Pp 255The scheme for passing arguments for asymmetric requests is Baroque. 256