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