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