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