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