1.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ 2.\" 3.\" The author of this manual page is Angelos D. Keromytis (angelos@cis.upenn.edu) 4.\" 5.\" Copyright (c) 2000, 2001 Angelos D. Keromytis 6.\" 7.\" Permission to use, copy, and modify this software with or without fee 8.\" is hereby granted, provided that this entire notice is included in 9.\" all source code copies of any software which is or includes a copy or 10.\" modification of this software. 11.\" 12.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 13.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY 14.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 15.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 16.\" PURPOSE. 17.\" 18.\" $FreeBSD: src/share/man/man9/crypto.9,v 1.14 2007/09/19 16:28:46 brueffer Exp $ 19.\" 20.Dd October 3, 2009 21.Dt CRYPTO 9 22.Os 23.Sh NAME 24.Nm crypto 25.Nd API for cryptographic services in the kernel 26.Sh SYNOPSIS 27.In opencrypto/cryptodev.h 28.Ft int32_t 29.Fn crypto_get_driverid "device_t dev" "int flags" 30.Ft int 31.Fn crypto_find_driver "const char *match" 32.Ft device_t 33.Fn crypto_find_device_byhid "int hid" 34.Ft int 35.Fn crypto_getcaps "int hid" 36.Ft int 37.Fn crypto_register "u_int32_t driverid" "int alg" "u_int16_t maxoplen" "u_int32_t flags" 38.Ft int 39.Fn crypto_kregister "u_int32_t driverid" "int kalg" "u_int32_t flags" 40.Ft int 41.Fn crypto_unregister "u_int32_t driverid" "int alg" 42.Ft int 43.Fn crypto_unregister_all "u_int32_t driverid" 44.Ft void 45.Fn crypto_done "struct cryptop *crp" 46.Ft void 47.Fn crypto_kdone "struct cryptkop *krp" 48.Ft int 49.Fn crypto_newsession "u_int64_t *sid" "struct cryptoini *cri" "int crid" 50.Ft int 51.Fn crypto_freesession "u_int64_t *sid" 52.Ft int 53.Fn crypto_dispatch "struct cryptop *crp" 54.Ft int 55.Fn crypto_kdispatch "struct cryptkop *krp" 56.Ft int 57.Fn crypto_unblock "u_int32_t driverid" "int what" 58.Ft "struct cryptop *" 59.Fn crypto_getreq "int num" 60.Ft void 61.Fn crypto_freereq "struct cryptop *crp" 62.Bd -literal 63#define CRYPTO_SYMQ 0x1 64#define CRYPTO_ASYMQ 0x2 65 66#define EALG_MAX_BLOCK_LEN 16 67 68struct cryptoini { 69 int cri_alg; 70 int cri_klen; 71 int cri_mlen; 72 caddr_t cri_key; 73 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; 74 struct cryptoini *cri_next; 75}; 76 77struct cryptodesc { 78 int crd_skip; 79 int crd_len; 80 int crd_inject; 81 int crd_flags; 82 struct cryptoini CRD_INI; 83#define crd_iv CRD_INI.cri_iv 84#define crd_key CRD_INI.cri_key 85#define crd_alg CRD_INI.cri_alg 86#define crd_klen CRD_INI.cri_klen 87 struct cryptodesc *crd_next; 88}; 89 90struct cryptop { 91 TAILQ_ENTRY(cryptop) crp_next; 92 u_int64_t crp_sid; 93 int crp_ilen; 94 int crp_olen; 95 int crp_etype; 96 int crp_flags; 97 caddr_t crp_buf; 98 caddr_t crp_opaque; 99 struct cryptodesc *crp_desc; 100 int (*crp_callback) (struct cryptop *); 101 caddr_t crp_mac; 102}; 103 104struct crparam { 105 caddr_t crp_p; 106 u_int crp_nbits; 107}; 108 109#define CRK_MAXPARAM 8 110 111struct cryptkop { 112 TAILQ_ENTRY(cryptkop) krp_next; 113 u_int krp_op; /* ie. CRK_MOD_EXP or other */ 114 u_int krp_status; /* return status */ 115 u_short krp_iparams; /* # of input parameters */ 116 u_short krp_oparams; /* # of output parameters */ 117 u_int32_t krp_hid; 118 struct crparam krp_param[CRK_MAXPARAM]; 119 int (*krp_callback)(struct cryptkop *); 120}; 121.Ed 122.Sh DESCRIPTION 123.Nm 124is a framework for drivers of cryptographic hardware to register with 125the kernel so 126.Dq consumers 127(other kernel subsystems, and 128users through the 129.Pa /dev/crypto 130device) are able to make use of it. 131Drivers register with the framework the algorithms they support, 132and provide entry points (functions) the framework may call to 133establish, use, and tear down sessions. 134Sessions are used to cache cryptographic information in a particular driver 135(or associated hardware), so initialization is not needed with every request. 136Consumers of cryptographic services pass a set of 137descriptors that instruct the framework (and the drivers registered 138with it) of the operations that should be applied on the data (more 139than one cryptographic operation can be requested). 140.Pp 141Keying operations are supported as well. 142Unlike the symmetric operators described above, 143these sessionless commands perform mathematical operations using 144input and output parameters. 145.Pp 146Since the consumers may not be associated with a process, drivers may 147not 148.Xr sleep 9 . 149The same holds for the framework. 150Thus, a callback mechanism is used 151to notify a consumer that a request has been completed (the 152callback is specified by the consumer on an per-request basis). 153The callback is invoked by the framework whether the request was 154successfully completed or not. 155An error indication is provided in the latter case. 156A specific error code, 157.Er EAGAIN , 158is used to indicate that a session number has changed and that the 159request may be re-submitted immediately with the new session number. 160Errors are only returned to the invoking function if not 161enough information to call the callback is available (meaning, there 162was a fatal error in verifying the arguments). 163For session initialization and teardown there is no callback mechanism used. 164.Pp 165The 166.Fn crypto_newsession 167routine is called by consumers of cryptographic services (such as the 168.Xr ipsec 4 169stack) that wish to establish a new session with the framework. 170On success, the first argument will contain the Session Identifier (SID). 171The second argument contains all the necessary information for 172the driver to establish the session. 173The third argument indicates whether a 174hardware driver (1) should be used or not (0). 175The various fields in the 176.Vt cryptoini 177structure are: 178.Bl -tag -width ".Va cri_next" 179.It Va cri_alg 180Contains an algorithm identifier. 181Currently supported algorithms are: 182.Pp 183.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact 184.It Dv CRYPTO_AES_CBC 185.It Dv CRYPTO_ARC4 186.It Dv CRYPTO_BLF_CBC 187.It Dv CRYPTO_CAMELLIA_CBC 188.It Dv CRYPTO_CAST_CBC 189.It Dv CRYPTO_DES_CBC 190.It Dv CRYPTO_3DES_CBC 191.It Dv CRYPTO_SKIPJACK_CBC 192.It Dv CRYPTO_MD5 193.It Dv CRYPTO_MD5_HMAC 194.It Dv CRYPTO_MD5_KPDK 195.It Dv CRYPTO_RIPEMD160_HMAC 196.It Dv CRYPTO_SHA1 197.It Dv CRYPTO_SHA1_HMAC 198.It Dv CRYPTO_SHA1_KPDK 199.It Dv CRYPTO_SHA2_256_HMAC 200.It Dv CRYPTO_SHA2_384_HMAC 201.It Dv CRYPTO_SHA2_512_HMAC 202.It Dv CRYPTO_NULL_HMAC 203.It Dv CRYPTO_NULL_CBC 204.El 205.It Va cri_klen 206Specifies the length of the key in bits, for variable-size key 207algorithms. 208.It Va cri_mlen 209Specifies how many bytes from the calculated hash should be copied back. 2100 means entire hash. 211.It Va cri_key 212Contains the key to be used with the algorithm. 213.It Va cri_iv 214Contains an explicit initialization vector (IV), if it does not prefix 215the data. 216This field is ignored during initialization. 217If no IV is explicitly passed (see below on details), a random IV is used 218by the device driver processing the request. 219.It Va cri_next 220Contains a pointer to another 221.Vt cryptoini 222structure. 223Multiple such structures may be linked to establish multi-algorithm sessions 224.Xr ( ipsec 4 225is an example consumer of such a feature). 226.El 227.Pp 228The 229.Vt cryptoini 230structure and its contents will not be modified by the framework (or 231the drivers used). 232Subsequent requests for processing that use the 233SID returned will avoid the cost of re-initializing the hardware (in 234essence, SID acts as an index in the session cache of the driver). 235.Pp 236.Fn crypto_freesession 237is called with the SID returned by 238.Fn crypto_newsession 239to disestablish the session. 240.Pp 241.Fn crypto_dispatch 242is called to process a request. 243The various fields in the 244.Vt cryptop 245structure are: 246.Bl -tag -width ".Va crp_callback" 247.It Va crp_sid 248Contains the SID. 249.It Va crp_ilen 250Indicates the total length in bytes of the buffer to be processed. 251.It Va crp_olen 252On return, contains the total length of the result. 253For symmetric crypto operations, this will be the same as the input length. 254This will be used if the framework needs to allocate a new 255buffer for the result (or for re-formatting the input). 256.It Va crp_callback 257This routine is invoked upon completion of the request, whether 258successful or not. 259It is invoked through the 260.Fn crypto_done 261routine. 262If the request was not successful, an error code is set in the 263.Va crp_etype 264field. 265It is the responsibility of the callback routine to enter a critical 266section. 267.It Va crp_etype 268Contains the error type, if any errors were encountered, or zero if 269the request was successfully processed. 270If the 271.Er EAGAIN 272error code is returned, the SID has changed (and has been recorded in the 273.Va crp_sid 274field). 275The consumer should record the new SID and use it in all subsequent requests. 276In this case, the request may be re-submitted immediately. 277This mechanism is used by the framework to perform 278session migration (move a session from one driver to another, because 279of availability, performance, or other considerations). 280.Pp 281Note that this field only makes sense when examined by 282the callback routine specified in 283.Va crp_callback . 284Errors are returned to the invoker of 285.Fn crypto_process 286only when enough information is not present to call the callback 287routine (i.e., if the pointer passed is 288.Dv NULL 289or if no callback routine was specified). 290.It Va crp_flags 291Is a bitmask of flags associated with this request. 292Currently defined flags are: 293.Bl -tag -width ".Dv CRYPTO_F_CBIFSYNC" 294.It Dv CRYPTO_F_IMBUF 295The buffer pointed to by 296.Va crp_buf 297is an mbuf chain. 298.It Dv CRYPTO_F_IOV 299The buffer pointed to by 300.Va crp_buf 301is an 302.Vt uio 303structure. 304.It Dv CRYPTO_F_REL 305Must return data in the same place. 306.It Dv CRYPTO_F_BATCH 307Batch operation if possible. 308.It Dv CRYPTO_F_CBIMM 309Do callback immediately instead of doing it from a dedicated kernel thread. 310.It Dv CRYPTO_F_DONE 311Operation completed. 312.It Dv CRYPTO_F_CBIFSYNC 313Do callback immediately if operation is synchronous. 314.El 315.It Va crp_buf 316Points to the input buffer. 317On return (when the callback is invoked), 318it contains the result of the request. 319The input buffer may be an mbuf 320chain or a contiguous buffer, 321depending on 322.Va crp_flags . 323.It Va crp_opaque 324This is passed through the crypto framework untouched and is 325intended for the invoking application's use. 326.It Va crp_desc 327This is a linked list of descriptors. 328Each descriptor provides 329information about what type of cryptographic operation should be done 330on the input buffer. 331The various fields are: 332.Bl -tag -width ".Va crd_inject" 333.It Va crd_iv 334The field where IV should be provided when the 335.Dv CRD_F_IV_EXPLICIT 336flag is given. 337.It Va crd_key 338When the 339.Dv CRD_F_KEY_EXPLICIT 340flag is given, the 341.Va crd_key 342points to a buffer with encryption or authentication key. 343.It Va crd_alg 344An algorithm to use. 345Must be the same as the one given at newsession time. 346.It Va crd_klen 347The 348.Va crd_key 349key length. 350.It Va crd_skip 351The offset in the input buffer where processing should start. 352.It Va crd_len 353How many bytes, after 354.Va crd_skip , 355should be processed. 356.It Va crd_inject 357Offset from the beginning of the buffer to insert any results. 358For encryption algorithms, this is where the initialization vector 359(IV) will be inserted when encrypting or where it can be found when 360decrypting (subject to 361.Va crd_flags ) . 362For MAC algorithms, this is where the result of the keyed hash will be 363inserted. 364.It Va crd_flags 365The following flags are defined: 366.Bl -tag -width 3n 367.It Dv CRD_F_ENCRYPT 368For encryption algorithms, this bit is set when encryption is required 369(when not set, decryption is performed). 370.It Dv CRD_F_IV_PRESENT 371For encryption algorithms, this bit is set when the IV already 372precedes the data, so the 373.Va crd_inject 374value will be ignored and no IV will be written in the buffer. 375Otherwise, the IV used to encrypt the packet will be written 376at the location pointed to by 377.Va crd_inject . 378The IV length is assumed to be equal to the blocksize of the 379encryption algorithm. 380Some applications that do special 381.Dq "IV cooking" , 382such as the half-IV mode in 383.Xr ipsec 4 , 384can use this flag to indicate that the IV should not be written on the packet. 385This flag is typically used in conjunction with the 386.Dv CRD_F_IV_EXPLICIT 387flag. 388.It Dv CRD_F_IV_EXPLICIT 389For encryption algorithms, this bit is set when the IV is explicitly 390provided by the consumer in the 391.Va crd_iv 392field. 393Otherwise, for encryption operations the IV is provided for by 394the driver used to perform the operation, whereas for decryption 395operations it is pointed to by the 396.Va crd_inject 397field. 398This flag is typically used when the IV is calculated 399.Dq "on the fly" 400by the consumer, and does not precede the data (some 401.Xr ipsec 4 402configurations, and the encrypted swap are two such examples). 403.It Dv CRD_F_KEY_EXPLICIT 404For encryption and authentication (MAC) algorithms, this bit is set when the key 405is explicitly provided by the consumer in the 406.Va crd_key 407field for the given operation. 408Otherwise, the key is taken at newsession time from the 409.Va cri_key 410field. 411.It Dv CRD_F_COMP 412For compression algorithms, this bit is set when compression is required (when 413not set, decompression is performed). 414.El 415.It Va CRD_INI 416This 417.Vt cryptoini 418structure will not be modified by the framework or the device drivers. 419Since this information accompanies every cryptographic 420operation request, drivers may re-initialize state on-demand 421(typically an expensive operation). 422Furthermore, the cryptographic 423framework may re-route requests as a result of full queues or hardware 424failure, as described above. 425.It Va crd_next 426Point to the next descriptor. 427Linked operations are useful in protocols such as 428.Xr ipsec 4 , 429where multiple cryptographic transforms may be applied on the same 430block of data. 431.El 432.El 433.Pp 434.Fn crypto_getreq 435allocates a 436.Vt cryptop 437structure with a linked list of as many 438.Vt cryptodesc 439structures as were specified in the argument passed to it. 440.Pp 441.Fn crypto_freereq 442deallocates a structure 443.Vt cryptop 444and any 445.Vt cryptodesc 446structures linked to it. 447Note that it is the responsibility of the 448callback routine to do the necessary cleanups associated with the 449opaque field in the 450.Vt cryptop 451structure. 452.Pp 453.Fn crypto_kdispatch 454is called to perform a keying operation. 455The various fields in the 456.Vt cryptkop 457structure are: 458.Bl -tag -width ".Va krp_callback" 459.It Va krp_op 460Operation code, such as 461.Dv CRK_MOD_EXP . 462.It Va krp_status 463Return code. 464This 465.Va errno Ns -style 466variable indicates whether lower level reasons 467for operation failure. 468.It Va krp_iparams 469Number if input parameters to the specified operation. 470Note that each operation has a (typically hardwired) number of such parameters. 471.It Va krp_oparams 472Number if output parameters from the specified operation. 473Note that each operation has a (typically hardwired) number of such parameters. 474.It Va krp_kvp 475An array of kernel memory blocks containing the parameters. 476.It Va krp_hid 477Identifier specifying which low-level driver is being used. 478.It Va krp_callback 479Callback called on completion of a keying operation. 480.El 481.Sh DRIVER-SIDE API 482The 483.Fn crypto_get_driverid , 484.Fn crypto_register , 485.Fn crypto_kregister , 486.Fn crypto_unregister , 487.Fn crypto_unblock , 488and 489.Fn crypto_done 490routines are used by drivers that provide support for cryptographic 491primitives to register and unregister with the kernel crypto services 492framework. 493Drivers must first use the 494.Fn crypto_get_driverid 495function to acquire a driver identifier, specifying the 496.Fa cc_flags 497as an argument (normally 0, but software-only drivers should specify 498.Dv CRYPTOCAP_F_SOFTWARE ) . 499For each algorithm the driver supports, it must then call 500.Fn crypto_register . 501The first two arguments are the driver and algorithm identifiers. 502The next two arguments specify the largest possible operator length (in bits, 503important for public key operations) and flags for this algorithm. 504The last four arguments must be provided in the first call to 505.Fn crypto_register 506and are ignored in all subsequent calls. 507They are pointers to three 508driver-provided functions that the framework may call to establish new 509cryptographic context with the driver, free already established 510context, and ask for a request to be processed (encrypt, decrypt, 511etc.); and an opaque parameter to pass when calling each of these routines. 512.Fn crypto_unregister 513is called by drivers that wish to withdraw support for an algorithm. 514The two arguments are the driver and algorithm identifiers, respectively. 515Typically, drivers for 516PCMCIA 517crypto cards that are being ejected will invoke this routine for all 518algorithms supported by the card. 519.Fn crypto_unregister_all 520will unregister all algorithms registered by a driver 521and the driver will be disabled (no new sessions will be allocated on 522that driver, and any existing sessions will be migrated to other 523drivers). 524The same will be done if all algorithms associated with a driver are 525unregistered one by one. 526.Pp 527The calling convention for the three driver-supplied routines is: 528.Pp 529.Bl -item -compact 530.It 531.Ft int 532.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ; 533.It 534.Ft int 535.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ; 536.It 537.Ft int 538.Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ; 539.It 540.Ft int 541.Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ; 542.El 543.Pp 544On invocation, the first argument to 545all routines is an opaque data value supplied when the algorithm 546is registered with 547.Fn crypto_register . 548The second argument to 549.Fn newsession 550contains the driver identifier obtained via 551.Fn crypto_get_driverid . 552On successful return, it should contain a driver-specific session 553identifier. 554The third argument is identical to that of 555.Fn crypto_newsession . 556.Pp 557The 558.Fn freesession 559routine takes as arguments the opaque data value and the SID 560(which is the concatenation of the 561driver identifier and the driver-specific session identifier). 562It should clear any context associated with the session (clear hardware 563registers, memory, etc.). 564.Pp 565The 566.Fn process 567routine is invoked with a request to perform crypto processing. 568This routine must not block, but should queue the request and return 569immediately. 570Upon processing the request, the callback routine should be invoked. 571In case of an unrecoverable error, the error indication must be placed in the 572.Va crp_etype 573field of the 574.Vt cryptop 575structure. 576When the request is completed, or an error is detected, the 577.Fn process 578routine should invoke 579.Fn crypto_done . 580Session migration may be performed, as mentioned previously. 581.Pp 582In case of a temporary resource exhaustion, the 583.Fn process 584routine may return 585.Er ERESTART 586in which case the crypto services will requeue the request, mark the driver 587as 588.Dq blocked , 589and stop submitting requests for processing. 590The driver is then responsible for notifying the crypto services 591when it is again able to process requests through the 592.Fn crypto_unblock 593routine. 594This simple flow control mechanism should only be used for short-lived 595resource exhaustion as it causes operations to be queued in the crypto 596layer. 597Doing so is preferable to returning an error in such cases as 598it can cause network protocols to degrade performance by treating the 599failure much like a lost packet. 600.Pp 601The 602.Fn kprocess 603routine is invoked with a request to perform crypto key processing. 604This routine must not block, but should queue the request and return 605immediately. 606Upon processing the request, the callback routine should be invoked. 607In case of an unrecoverable error, the error indication must be placed in the 608.Va krp_status 609field of the 610.Vt cryptkop 611structure. 612When the request is completed, or an error is detected, the 613.Fn kprocess 614routine should invoked 615.Fn crypto_kdone . 616.Sh RETURN VALUES 617.Fn crypto_register , 618.Fn crypto_kregister , 619.Fn crypto_unregister , 620.Fn crypto_newsession , 621.Fn crypto_freesession , 622and 623.Fn crypto_unblock 624return 0 on success, or an error code on failure. 625.Fn crypto_get_driverid 626returns a non-negative value on error, and \-1 on failure. 627.Fn crypto_getreq 628returns a pointer to a 629.Vt cryptop 630structure and 631.Dv NULL 632on failure. 633.Fn crypto_dispatch 634returns 635.Er EINVAL 636if its argument or the callback function was 637.Dv NULL , 638and 0 otherwise. 639The callback is provided with an error code in case of failure, in the 640.Va crp_etype 641field. 642.Sh FILES 643.Bl -tag -width ".Pa sys/opencrypto/crypto.c" 644.It Pa sys/opencrypto/crypto.c 645most of the framework code 646.El 647.Sh SEE ALSO 648.Xr ipsec 4 , 649.Xr kmalloc 9 , 650.Xr sleep 9 651.Sh HISTORY 652The cryptographic framework first appeared in 653.Ox 2.7 654and was written by 655.An "Angelos D. Keromytis" Aq angelos@openbsd.org . 656.Sh BUGS 657The framework currently assumes that all the algorithms in a 658.Fn crypto_newsession 659operation must be available by the same driver. 660If that is not the case, session initialization will fail. 661.Pp 662The framework also needs a mechanism for determining which driver is 663best for a specific set of algorithms associated with a session. 664Some type of benchmarking is in order here. 665.Pp 666Multiple instances of the same algorithm in the same session are not 667supported. 668Note that 3DES is considered one algorithm (and not three 669instances of DES). 670Thus, 3DES and DES could be mixed in the same request. 671