1.\" $NetBSD: crypto.4,v 1.13 2008/04/10 22:48:42 tls Exp $ 2.\" 3.\" Copyright (c) 2008 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Coyote Point Systems, Inc. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" 38.\" 39.\" Copyright (c) 2004 40.\" Jonathan Stone <jonathan@dsg.stanford.edu>. All rights reserved. 41.\" 42.\" Redistribution and use in source and binary forms, with or without 43.\" modification, are permitted provided that the following conditions 44.\" are met: 45.\" 1. Redistributions of source code must retain the above copyright 46.\" notice, this list of conditions and the following disclaimer. 47.\" 2. Redistributions in binary form must reproduce the above copyright 48.\" notice, this list of conditions and the following disclaimer in the 49.\" documentation and/or other materials provided with the distribution. 50.\" 51.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND 52.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 53.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 54.\" ARE DISCLAIMED. IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD 55.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 56.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 57.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 58.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 59.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 60.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF 61.\" THE POSSIBILITY OF SUCH DAMAGE. 62.\" 63.Dd March 29, 2008 64.Dt CRYPTO 4 65.Os 66.Sh NAME 67.Nm crypto , 68.Nm swcrypto 69.Nd user-mode access to hardware-accelerated cryptography 70.Sh SYNOPSIS 71.Cd "hifn* at pci? dev ? function ?" 72.Cd "ubsec* at pci? dev ? function ?" 73.Pp 74.Cd pseudo-device crypto 75.Cd pseudo-device swcrypto 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 opencrypto 9 86in-kernel interface. 87The 88.Cm swcrypto 89driver is a software-only implementation of the 90.Xr opencrypto 9 91interface, and must be included to use the interface without hardware 92acceleration. 93The 94.Pa /dev/crypto 95special device provides an 96.Xr ioctl 2 97based interface. 98User-mode applications should open the special device, 99then issue 100.Xr ioctl 2 101calls on the descriptor. 102The 103.Nm 104device provides two distinct modes of operation: one mode for 105symmetric-keyed cryptographic requests, and a second mode for 106both asymmetric-key (public-key/private-key) requests, and for 107modular arithmetic (for Diffie-Hellman key exchange and other 108cryptographic protocols). 109The two modes are described separately below. 110.Sh THEORY OF OPERATION 111Regardless of whether symmetric-key or asymmetric-key operations are 112to be performed, use of the device requires a basic series of steps: 113.Pp 114.Bl -enum 115.It 116Open a file descriptor for the device. See 117.Xr open 2 . 118.It 119If any symmetric operation will be performed, 120create one session, with 121.Dv CIOCGSESSION , 122or multiple sessions, with 123.Dv CIOCNGSESSION . 124Most applications will require at least one symmetric session. 125Since cipher and MAC keys are tied to sessions, many 126applications will require more. Asymmetric operations do not use sessions. 127.It 128Submit requests, synchronously with 129.Dv CIOCCRYPT 130(symmetric) 131or 132.Dv CIOCFKEY 133(asymmetric) 134or asynchronously with 135.Dv CIOCNCRYPTM 136(symmetric) 137or 138.Dv CIOCNFKEYM 139(asymmetric). 140The asynchronous interface allows multiple requests to be submitted in one 141call if the user so desires. 142.It 143If the asynchronous interface is used, wait for results with 144.Xr select 2 145or 146.Xr poll 2 , 147then collect them with 148.Dv CIOCNCRYPTRET 149(a particular request) 150or 151.Dv CIOCNCRYPTRETM 152(multiple requests). 153.It 154Destroy one session with 155.Dv CIOCFSESSION 156or many at once with 157.Dv CIOCNFSESSION . 158.It 159Close the device with 160.Xr close 2 . 161.El 162.Sh SYMMETRIC-KEY OPERATION 163The symmetric-key operation mode provides a context-based API 164to traditional symmetric-key encryption (or privacy) algorithms, 165or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms. 166The symmetric-key mode also permits fused operation, 167where the hardware performs both a privacy algorithm and an integrity-check 168algorithm in a single pass over the data: either a fused 169encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation. 170.Pp 171To use symmetric mode, you must first create a session specifying 172the algorithm(s) and key(s) to use; then issue encrypt or decrypt 173requests against the session. 174.Ss Symmetric-key privacy algorithms 175Contingent upon device drivers for installed cryptographic hardware 176registering with 177.Xr opencrypto 9 , 178as providers of a given algorithm, some or all of the following 179symmetric-key privacy algorithms may be available: 180.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 181.It CRYPTO_DES_CBC 182.It CRYPTO_3DES_CBC 183.It CRYPTO_BLF_CBC 184.It CRYPTO_CAST_CBC 185.It CRYPTO_SKIPJACK_CBC 186.It CRYPTO_AES_CBC 187.It CRYPTO_ARC4 188.El 189.Ss Integrity-check operations 190Contingent upon hardware support, some or all of the following 191keyed one-way hash algorithms may be available: 192.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent 193.It CRYPTO_RIPEMD160_HMAC 194.It CRYPTO_MD5_KPDK 195.It CRYPTO_SHA1_KPDK 196.It CRYPTO_MD5_HMAC 197.It CRYPTO_SHA1_HMAC 198.It CRYPTO_SHA2_HMAC 199.It CRYPTO_MD5 200.It CRYPTO_SHA1 201.El 202The 203.Em CRYPTO_MD5 204and 205.Em CRYPTO_SHA1 206algorithms are actually unkeyed, but should be requested 207as symmetric-key hash algorithms with a zero-length key. 208.Ss IOCTL Request Descriptions 209.\" 210.Bl -tag -width CIOCFKEY 211.\" 212.It Dv CRIOGET Fa int *fd 213This operation is deprecated and will be removed after 214.Nx 5.0. 215It clones the fd argument to 216.Xr ioctl 4 , 217yielding a new file descriptor for the creation of sessions. Because the 218device now clones on open, this operation is unnecessary. 219.\" 220.It Dv CIOCGSESSION Fa struct session_op *sessp 221.Bd -literal 222struct session_op { 223 u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ 224 u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ 225 226 u_int32_t keylen; /* cipher key */ 227 void * key; 228 int mackeylen; /* mac key */ 229 void * mackey; 230 231 u_int32_t ses; /* returns: ses # */ 232}; 233 234.Ed 235Create a new cryptographic session on a file descriptor for the device; 236that is, a persistent object specific to the chosen 237privacy algorithm, integrity algorithm, and keys specified in 238.Fa sessp . 239The special value 0 for either privacy or integrity 240is reserved to indicate that the indicated operation (privacy or integrity) 241is not desired for this session. 242.Pp 243Multiple sessions may be bound to a single file descriptor. The session 244ID returned in 245.Fa sessp-\*[Gt]ses 246is supplied as a required field in the symmetric-operation structure 247.Fa crypt_op 248for future encryption or hashing requests. 249.Pp 250This implementation will never return a session ID of 0 for a successful 251creation of a session, which is a 252.Nx 253extension. 254.Pp 255For non-zero symmetric-key privacy algorithms, the privacy algorithm 256must be specified in 257.Fa sessp-\*[Gt]cipher , 258the key length in 259.Fa sessp-\*[Gt]keylen , 260and the key value in the octets addressed by 261.Fa sessp-\*[Gt]key . 262.Pp 263For keyed one-way hash algorithms, the one-way hash must be specified 264in 265.Fa sessp-\*[Gt]mac , 266the key length in 267.Fa sessp-\*[Gt]mackey , 268and the key value in the octets addressed by 269.Fa sessp-\*[Gt]mackeylen . 270.\" 271.Pp 272Support for a specific combination of fused privacy and 273integrity-check algorithms depends on whether the underlying 274hardware supports that combination. 275Not all combinations are supported 276by all hardware, even if the hardware supports each operation as a 277stand-alone non-fused operation. 278.It Dv CIOCNGSESSION Fa struct crypt_sgop *sgop 279.Bd -literal 280struct crypt_sgop { 281 size_t count; /* how many */ 282 struct session_n_op * sessions; /* where to get them */ 283}; 284 285struct session_n_op { 286 u_int32_t cipher; /* e.g. CRYPTO_DES_CBC */ 287 u_int32_t mac; /* e.g. CRYPTO_MD5_HMAC */ 288 289 u_int32_t keylen; /* cipher key */ 290 void * key; 291 u_int32_t mackeylen; /* mac key */ 292 void * mackey; 293 294 u_int32_t ses; /* returns: session # */ 295 int status; 296}; 297 298.Ed 299Create one or more sessions. Takes a counted array of 300.Fa session_n_op 301structures 302in 303.Fa sgop . 304For each requested session (array element n), the session number is returned in 305.Fa sgop-\*[Gt]sessions[n].ses 306and the status for that session creation in 307.Fa sgop-\*[Gt]sessions[n].status . 308.\" 309.It Dv CIOCCRYPT Fa struct crypt_op *cr_op 310.Bd -literal 311struct crypt_op { 312 u_int32_t ses; 313 u_int16_t op; /* e.g. COP_ENCRYPT */ 314 u_int16_t flags; 315 u_int len; 316 void * src, *dst; 317 void * mac; /* must be large enough for result */ 318 void * iv; 319}; 320 321.Ed 322Request a symmetric-key (or hash) operation. 323The file descriptor argument to 324.Xr ioctl 4 325must have been bound to a valid session. 326To encrypt, set 327.Fa cr_op-\*[Gt]op 328to 329.Dv COP_ENCRYPT . 330To decrypt, set 331.Fa cr_op-\*[Gt]op 332to 333.Dv COP_DECRYPT . 334The field 335.Fa cr_op-\*[Gt]len 336supplies the length of the input buffer; the fields 337.Fa cr_op-\*[Gt]src , 338.Fa cr_op-\*[Gt]dst , 339.Fa cr_op-\*[Gt]mac , 340.Fa cr_op-\*[Gt]iv 341supply the addresses of the input buffer, output buffer, 342one-way hash, and initialization vector, respectively. 343.It Dv CIOCNCRYPTM Fa struct crypt_mop *cr_mop 344.Bd -literal 345struct crypt_mop { 346 size_t count; /* how many */ 347 struct crypt_n_op * reqs; /* where to get them */ 348}; 349 350struct crypt_n_op { 351 u_int32_t ses; 352 u_int16_t op; /* e.g. COP_ENCRYPT */ 353 u_int16_t flags; 354 u_int len; 355 356 u_int32_t reqid; /* request id */ 357 int status; /* accepted or not */ 358 359 void *opaque; /* opaque pointer ret to user */ 360 u_int32_t keylen; /* cipher key - optional */ 361 void * key; 362 u_int32_t mackeylen; /* mac key - optional */ 363 void * mackey; 364 365 void * src, * dst; 366 void * mac; 367 void * iv; 368}; 369 370.Ed 371This is the asynchronous version of CIOCCRYPT, which allows multiple 372symmetric-key (or hash) operations to be started (see CIOCRYPT 373above for the details for each operation). 374.Pp 375The 376.Fa cr_mop-\*[Gt]count 377field specifies the number of operations provided in the cr_mop->reqs array. 378.Pp 379Each operation is assigned a unique request id returned in the 380.Fa cr_mop-\*[Gt]reqs[n].reqid 381field. 382.Pp 383Each operation can accept an opaque value from the user to be passed back 384to the user when the operation completes ((e.g. to track context for the 385request). The opaque field is 386.Fa cr_mop-\*[Gt]reqs[n].opaque. 387.Pp 388If a problem occurs with starting any of the operations then that 389operation's 390.Fa cr_mop-\*[Gt]reqs[n].status 391field is filled with the error code. The failure of an operation does not 392prevent the other operations from being started. 393.Pp 394The 395.Xr select 2 396or 397.Xr poll 2 398functions must be used on the device file descriptor to detect that 399some operation has completed; results are then retrieved with 400.Dv CIOCNCRYPTRETM . 401.Pp 402The 403.Fa key 404and 405.Fa mackey 406fields of the 407operation structure are currently unused. They are intended for use to 408immediately rekey an existing session before processing a new request. 409.It Dv CIOCFSESSION Fa void 410Destroys the /dev/crypto session associated with the file-descriptor 411argument. 412.It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop; 413.Bd -literal 414struct crypt_sfop { 415 size_t count; 416 u_int32_t *sesid; 417}; 418 419.Ed 420Destroys the 421.Fa sfop-\*[Gt]count 422sessions specified by the 423.Fa sfop 424array of session identifiers. 425.El 426.\" 427.Sh ASYMMETRIC-KEY OPERATION 428.Ss Asymmetric-key algorithms 429Contingent upon hardware support, the following asymmetric 430(public-key/private-key; or key-exchange subroutine) operations may 431also be available: 432.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact 433.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter" 434.It Em " " Ta "Count" Ta "Count" 435.It Dv CRK_MOD_EXP Ta 3 Ta 1 436.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1 437.It Dv CRK_MOD_ADD Ta 3 Ta 1 438.It Dv CRK_MOD_ADDINV Ta 2 Ta 1 439.It Dv CRK_MOD_SUB Ta 3 Ta 1 440.It Dv CRK_MOD_MULT Ta 3 Ta 1 441.It Dv CRK_MOD_MULTINV Ta 2 Ta 1 442.It Dv CRK_MOD Ta 2 Ta 1 443.It Dv CRK_DSA_SIGN Ta 5 Ta 2 444.It Dv CRK_DSA_VERIFY Ta 7 Ta 0 445.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1 446.El 447.Pp 448See below for discussion of the input and output parameter counts. 449.Ss Asymmetric-key commands 450.Bl -tag -width CIOCFKEY 451.It Dv CIOCASSYMFEAT Fa int *feature_mask 452Returns a bitmask of supported asymmetric-key operations. 453Each of the above-listed asymmetric operations is present 454if and only if the bit position numbered by the code for that operation 455is set. 456For example, 457.Dv CRK_MOD_EXP 458is available if and only if the bit 459.Pq 1 \*[Lt]\*[Lt] Dv CRK_MOD_EX 460is set. 461.It Dv CIOCFKEY Fa struct crypt_kop *kop 462.Bd -literal 463struct crypt_kop { 464 u_int crk_op; /* e.g. CRK_MOD_EXP */ 465 u_int crk_status; /* return status */ 466 u_short crk_iparams; /* # of input params */ 467 u_short crk_oparams; /* # of output params */ 468 u_int crk_pad1; 469 struct crparam crk_param[CRK_MAXPARAM]; 470}; 471 472/* Bignum parameter, in packed bytes. */ 473struct crparam { 474 void * crp_p; 475 u_int crp_nbits; 476}; 477 478.Ed 479Performs an asymmetric-key operation from the list above. 480The specific operation is supplied in 481.Fa kop-\*[Gt]crk_op ; 482final status for the operation is returned in 483.Fa kop-\*[Gt]crk_status . 484The number of input arguments and the number of output arguments 485is specified in 486.Fa kop-\*[Gt]crk_iparams 487and 488.Fa kop-\*[Gt]crk_iparams , 489respectively. 490The field 491.Fa crk_param[] 492must be filled in with exactly 493.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams 494arguments, each encoded as a 495.Fa struct crparam 496(address, bitlength) pair. 497.Pp 498The semantics of these arguments are currently undocumented. 499.It Dv CIOCNFKEYM Fa struct crypt_mkop *mkop 500.Bd -literal 501struct crypt_mkop { 502 size_t count; /* how many */ 503 struct crypt_n_op * reqs; /* where to get them */ 504}; 505 506struct crypt_n_kop { 507 u_int crk_op; /* e.g. CRK_MOD_EXP */ 508 u_int crk_status; /* accepted or not */ 509 u_short crk_iparams; /* # of input params */ 510 u_short crk_oparams; /* # of output params */ 511 u_int32_t crk_reqid; /* request id */ 512 struct crparam crk_param[CRK_MAXPARAM]; 513 void *crk_opaque; /* opaque pointer ret to user */ 514}; 515 516.Ed 517This is the asynchronous version of 518.Dv CIOCFKEY, 519which starts one or more key operations. See 520.Dv CIOCNCRYPTM 521above and 522.Dv CIOCNCRYPTRETM 523below 524for descriptions of the 525.Fa mkop\*[Gt]count , 526.Fa mkop\*[Gt]reqs , 527.Fa mkop\*[Gt]reqs[n].crk_reqid , 528.Fa mkop\*[Gt]reqs[n].crk_status , 529and 530.Fa mkop\*[Gt]reqs[n].crk_opaque 531fields of the argument structure, and result retrieval. 532.El 533.Ss Asynchronous status commands 534When requests are submitted with the 535.Dv CIOCNCRYPTM 536or 537.Dv CIOCNFKEYM 538commands, result retrieval is asynchronous (the submit ioctls return 539immediately). Use the 540.Xr select 2 541or 542.Xr poll 2 543functions to determine when the file descriptor has completed operations ready 544to be retrieved. 545.Bl -tag -width CIOCFKEY 546.It Dv CIOCNCRYPTRET Fa struct crypt_result *cres 547.Bd -literal 548struct crypt_result { 549 u_int32_t reqid; /* request ID */ 550 u_int32_t status; /* 0 if successful */ 551 void * opaque; /* pointer from user */ 552}; 553 554.Ed 555Check for the status of the request specified by 556.Fa cres-\*[Gt]reqid . 557This requires a linear search through all completed requests and should 558be used with extreme care if the number of requests pending on this 559file descriptor may be large. 560.Pp 561The 562.Fa cres-\*[Gt]status field is set as follows: 563.Bl -tag -width EINPROGRESS 564.It 0 565The request has completed, and its results have been copied out to 566the original 567.Fa crypt_n_op or 568.Fa crypt_n_kop 569structure used to start the request. The copyout occurs during this 570ioctl, so the calling process must be the process that started the request. 571.It EINPROGRESS 572The request has not yet completed. 573.It EINVAL 574The request was not found. 575.El 576.Pp 577Other values indicate a problem during the processing of the request. 578.It Dv CIOCNCRYPTRETM Fa struct cryptret_t *cret 579.Bd -literal 580struct cryptret { 581 size_t count; /* space for how many */ 582 struct crypt_result * results; /* where to put them */ 583}; 584 585.Ed 586Retrieve a number of completed requests. This ioctl accepts a count and 587an array (each array element is a 588.Fa crypt_result_t 589structure as used by 590.Dv CIOCNCRYPTRET 591above) and fills the array with up to 592.Fa cret-\*[Gt]count 593results of completed requests. 594.Pp 595This ioctl fills in the 596.Fa cret-\*[Gt]results[n].reqid field , 597so that the request which has completed 598may be identified by the application. Note that the results may include 599requests submitted both as symmetric and asymmetric operations. 600.El 601.Pp 602.Sh SEE ALSO 603.Xr hifn 4 , 604.Xr ubsec 4 , 605.Xr opencrypto 9 606.Sh HISTORY 607The 608.Nm 609driver is derived from a version which appeared in 610.Fx 4.8 , 611which in turn is based on code which appeared in 612.Ox 3.2 . 613.Pp 614The "new API" for asynchronous operation with multiple basic operations 615per system call (the "N" ioctl variants) was contributed by Coyote Point 616Systems, Inc. and first appeared in 617.Nx 5.0 . 618.Sh BUGS 619Error checking and reporting is weak. 620.Pp 621The values specified for symmetric-key key sizes to 622.Dv CIOCGSESSION 623must exactly match the values expected by 624.Xr opencrypto 9 . 625The output buffer and MAC buffers supplied to 626.Dv CIOCCRYPT 627must follow whether privacy or integrity algorithms were specified for 628session: if you request a 629.No non- Ns Dv NULL 630algorithm, you must supply a suitably-sized buffer. 631.Pp 632The scheme for passing arguments for asymmetric requests is Baroque. 633.Pp 634The naming inconsistency between 635.Dv CRIOGET 636and the various 637.Dv CIOC Ns \&* 638names is an unfortunate historical artifact. 639