1.\" $OpenBSD: crypto.9,v 1.31 2008/06/09 18:55:58 jmc Exp $ 2.\" 3.\" The author of this man 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.Dd $Mdocdate: June 9 2008 $ 19.Dt CRYPTO 9 20.Os 21.Sh NAME 22.Nm crypto 23.Nd API for cryptographic services in the kernel 24.Sh SYNOPSIS 25.Fd #include <crypto/cryptodev.h> 26.Ft int32_t 27.Fn crypto_get_driverid "u_int8_t" 28.Ft int 29.Fn crypto_register "u_int32_t" "int *" "int (*)(u_int32_t *, struct cryptoini *)" "int (*)(u_int64_t)" "int (*)(struct cryptop *)" 30.Ft int 31.Fn crypto_kregister "u_int32_t" "int *" "int (*)(struct cryptkop *)" 32.Ft int 33.Fn crypto_unregister "u_int32_t" "int" 34.Ft void 35.Fn crypto_done "struct cryptop *" 36.Ft void 37.Fn crypto_kdone "struct cryptkop *" 38.Ft int 39.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" "int" 40.Ft int 41.Fn crypto_freesession "u_int64_t" 42.Ft int 43.Fn crypto_dispatch "struct cryptop *" 44.Ft int 45.Fn crypto_kdispatch "struct cryptkop *" 46.Ft struct cryptop * 47.Fn crypto_getreq "int" 48.Ft void 49.Fn crypto_freereq "struct cryptop *" 50.Bd -literal 51 52#define EALG_MAX_BLOCK_LEN 16 53 54struct cryptoini { 55 int cri_alg; 56 int cri_klen; 57 int cri_rnd; 58 caddr_t cri_key; 59 u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; 60 struct cryptoini *cri_next; 61}; 62 63struct cryptodesc { 64 int crd_skip; 65 int crd_len; 66 int crd_inject; 67 int crd_flags; 68 struct cryptoini CRD_INI; 69 struct cryptodesc *crd_next; 70}; 71 72struct cryptop { 73 u_int64_t crp_sid; 74 int crp_ilen; 75 int crp_olen; 76 int crp_alloctype; 77 int crp_etype; 78 int crp_flags; 79 void *crp_buf; 80 void *crp_opaque; 81 struct cryptodesc *crp_desc; 82 int (*crp_callback)(struct cryptop *); 83 struct cryptop *crp_next; 84 caddr_t crp_mac; 85}; 86 87struct crparam { 88 caddr_t crp_p; 89 u_int crp_nbits; 90}; 91 92#define CRK_MAXPARAM 8 93 94struct cryptkop { 95 u_int krp_op; /* ie. CRK_MOD_EXP or other */ 96 u_int krp_status; /* return status */ 97 u_short krp_iparams; /* # of input parameters */ 98 u_short krp_oparams; /* # of output parameters */ 99 u_int32_t krp_hid; 100 struct crparam krp_param[CRK_MAXPARAM]; /* kvm */ 101 int (*krp_callback)(struct cryptkop *); 102 struct cryptkop *krp_next; 103}; 104.Ed 105.Sh DESCRIPTION 106.Nm 107is a framework for drivers of cryptographic hardware to register with 108the kernel so 109.Dq consumers 110(other kernel subsystems, and eventually 111users through an appropriate device) are able to make use of it. 112Drivers register with the framework the algorithms they support, 113and provide entry points (functions) the framework may call to 114establish, use, and tear down sessions. 115Sessions are used to cache cryptographic information in a particular driver 116(or associated hardware), so initialization is not needed with every request. 117Consumers of cryptographic services pass a set of 118descriptors that instruct the framework (and the drivers registered 119with it) of the operations that should be applied on the data (more 120than one cryptographic operation can be requested). 121.Pp 122Keying operations are supported as well. 123Unlike the symmetric operators described above, 124these sessionless commands perform mathematical operations using 125input and output parameters. 126.Pp 127Since the consumers may not be associated with a process, drivers may 128not use 129.Xr tsleep 9 . 130The same holds for the framework. 131Thus, a callback mechanism is used 132to notify a consumer that a request has been completed (the 133callback is specified by the consumer on an per-request basis). 134The callback is invoked by the framework whether the request was 135successfully completed or not. 136An error indication is provided in the latter case. 137A specific error code, 138.Er EAGAIN , 139is used to indicate that a session number has changed and that the 140request may be re-submitted immediately with the new session number. 141Errors are only returned to the invoking function if not 142enough information to call the callback is available (meaning, there 143was a fatal error in verifying the arguments). 144For session initialization and teardown there is no callback mechanism used. 145.Pp 146The 147.Fn crypto_newsession 148routine is called by consumers of cryptographic services (such as the 149.Xr ipsec 4 150stack) that wish to establish a new session with the framework. 151On success, the first argument will contain the Session Identifier (SID). 152The second argument contains all the necessary information for 153the driver to establish the session. 154The third argument indicates whether a 155hardware driver should be used (1) or not (0). 156The various fields in the 157.Fa cryptoini 158structure are: 159.Bl -tag -width foobarmoocow 160.It Fa cri_alg 161Contains an algorithm identifier. 162Currently supported algorithms are: 163.Bd -literal 164CRYPTO_DES_CBC 165CRYPTO_3DES_CBC 166CRYPTO_BLF_CBC 167CRYPTO_CAST_CBC 168CRYPTO_SKIPJACK_CBC 169CRYPTO_MD5_HMAC 170CRYPTO_SHA1_HMAC 171CRYPTO_RIPEMD160_HMAC 172CRYPTO_MD5_KPDK 173CRYPTO_SHA1_KPDK 174CRYPTO_AES_CBC 175CRYPTO_AES_CTR 176CRYPTO_AES_XTS 177CRYPTO_ARC4 178CRYPTO_MD5 179CRYPTO_SHA1 180.Ed 181.Pp 182.It Fa cri_klen 183Specifies the length of the key in bits, for variable-size key 184algorithms. 185.It Fa cri_rnd 186Specifies the number of rounds to be used with the algorithm, for 187variable-round algorithms. 188.It Fa cri_key 189Contains the key to be used with the algorithm. 190.It Fa cri_iv 191Contains an explicit initialization vector (IV), if it does not prefix 192the data. 193This field is ignored during initialization. 194If no IV is explicitly passed (see below on details), a random IV is used 195by the device driver processing the request. 196.Pp 197In the case of the CRYPTO_AES_XTS transform, the IV should be provided 198as a 64-bit block number in host byte order. 199.It Fa cri_next 200Contains a pointer to another 201.Fa cryptoini 202structure. 203Multiple such structures may be linked to establish multi-algorithm sessions 204.Pf ( Xr ipsec 4 205is an example consumer of such a feature). 206.El 207.Pp 208The 209.Fa cryptoini 210structure and its contents will not be modified by the framework (or 211the drivers used). 212Subsequent requests for processing that use the 213SID returned will avoid the cost of re-initializing the hardware (in 214essence, SID acts as an index in the session cache of the driver). 215.Pp 216.Fn crypto_freesession 217is called with the SID returned by 218.Fn crypto_newsession 219to disestablish the session. 220.Pp 221.Fn crypto_dispatch 222is called to process a request. 223The various fields in the 224.Fa cryptop 225structure are: 226.Bl -tag -width crp_alloctype 227.It Fa crp_sid 228Contains the SID. 229.It Fa crp_ilen 230Indicates the total length in bytes of the buffer to be processed. 231.It Fa crp_olen 232On return, contains the length of the result, not including 233.Fa crd_skip . 234For symmetric crypto operations, this will be the same as the input length. 235.It Fa crp_alloctype 236Indicates the type of buffer, as used in the kernel 237.Xr malloc 9 238routine. 239This will be used if the framework needs to allocate a new 240buffer for the result (or for re-formatting the input). 241.It Fa crp_callback 242This routine is invoked upon completion of the request, whether 243successful or not. 244It is invoked through the 245.Fn crypto_done 246routine. 247If the request was not successful, an error code is set in the 248.Fa crp_etype 249field. 250It is the responsibility of the callback routine to set the appropriate 251.Xr spl 9 252level. 253.It Fa crp_etype 254Contains the error type, if any errors were encountered, or zero if 255the request was successfully processed. 256If the 257.Er EAGAIN 258error code is returned, the SID has changed (and has been recorded in the 259.Fa crp_sid 260field). 261The consumer should record the new SID and use it in all subsequent requests. 262In this case, the request may be re-submitted immediately. 263This mechanism is used by the framework to perform 264session migration (move a session from one driver to another, because 265of availability, performance, or other considerations). 266.Pp 267Note that this field only makes sense when examined by 268the callback routine specified in 269.Fa crp_callback . 270Errors are returned to the invoker of 271.Fn crypto_process 272only when enough information is not present to call the callback 273routine (i.e., if the pointer passed is 274.Dv NULL 275or if no callback routine was specified). 276.It Fa crp_flags 277Is a bitmask of flags associated with this request. 278Currently defined flags are: 279.Bl -tag -width CRYPTO_F_IMBUF 280.It Dv CRYPTO_F_IMBUF 281The buffer pointed to by 282.Fa crp_buf 283is an mbuf chain. 284.El 285.Pp 286.It Fa crp_buf 287Points to the input buffer. 288On return (when the callback is invoked), 289it contains the result of the request. 290The input buffer may be an mbuf 291chain or a struct uio depending on 292.Fa crp_flags . 293.It Fa crp_opaque 294This is passed through the crypto framework untouched and is 295intended for the invoking application's use. 296.It Fa crp_desc 297This is a linked list of descriptors. 298Each descriptor provides 299information about what type of cryptographic operation should be done 300on the input buffer. 301The various fields are: 302.Bl -tag 303.It Fa crd_skip 304The offset in the input buffer where processing should start. 305.It Fa crd_len 306How many bytes, after 307.Fa Fa crd_skip , 308should be processed. 309.It Fa crd_inject 310Offset from the beginning of the buffer to insert any results. 311For encryption algorithms, this is where the initialization vector 312(IV) will be inserted when encrypting or where it can be found when 313decrypting (subject to 314.Fa Fa crd_flags ) . 315For MAC algorithms, this is where the result of the keyed hash will be 316inserted. 317.It Fa crd_flags 318The following flags are defined: 319.Bl -tag -width CRD_F_IV_EXPLICIT 320.It Dv CRD_F_ENCRYPT 321For encryption algorithms, this bit is set when encryption is required 322(when not set, decryption is performed). 323.It Dv CRD_F_IV_PRESENT 324For encryption algorithms, this bit is set when the IV already 325precedes the data, so the 326.Fa crd_inject 327value will be ignored and no IV will be written in the buffer. 328Otherwise, the IV used to encrypt the packet will be written 329at the location pointed to by 330.Fa crd_inject . 331The IV length is assumed to be equal to the blocksize of the 332encryption algorithm. 333Some applications that do special 334.Dq IV cooking , 335such as the half-IV mode in 336.Xr ipsec 4 , 337can use this flag to indicate that the IV should not be written on the packet. 338This flag is typically used in conjunction with the 339.Dv CRD_F_IV_EXPLICIT 340flag. 341.It Dv CRD_F_IV_EXPLICIT 342For encryption algorithms, this bit is set when the IV is explicitly 343provided by the consumer in the 344.Fa crd_iv 345fields. 346Otherwise, for encryption operations the IV is provided for by 347the driver used to perform the operation, whereas for decryption 348operations it is pointed to by the 349.Fa crd_inject 350field. 351This flag is typically used when the IV is calculated 352.Dq on the fly 353by the consumer, and does not precede the data (some 354.Xr ipsec 4 355configurations, and the encrypted swap are two such examples). 356.It Dv CRD_F_COMP 357For compression algorithms, this bit is set when compression is required (when 358not set, decompression is performed). 359.El 360.It Fa CRD_INI 361This 362.Fa cryptoini 363structure will not be modified by the framework or the device drivers. 364Since this information accompanies every cryptographic 365operation request, drivers may re-initialize state on-demand 366(typically an expensive operation). 367Furthermore, the cryptographic 368framework may re-route requests as a result of full queues or hardware 369failure, as described above. 370.It Fa crd_next 371Point to the next descriptor. 372Linked operations are useful in protocols such as 373.Xr ipsec 4 , 374where multiple cryptographic transforms may be applied on the same 375block of data. 376.El 377.El 378.Pp 379.Fn crypto_getreq 380allocates a 381.Fa cryptop 382structure with a linked list of as many 383.Fa cryptodesc 384structures as were specified in the argument passed to it. 385.Pp 386.Fn crypto_freereq 387deallocates a structure 388.Fa cryptop 389and any 390.Fa cryptodesc 391structures linked to it. 392Note that it is the responsibility of the 393callback routine to do the necessary cleanups associated with the 394opaque field in the 395.Fa cryptop 396structure. 397.Pp 398.Fn crypto_kdispatch 399is called to perform a keying operation. 400The various fields in the 401.Fa cryptkop 402structure are: 403.Bl -tag -width crp_alloctype 404.It Fa krp_op 405Operation code, such as CRK_MOD_EXP. 406.It Fa krp_status 407Return code. 408This errno-style variable indicates whether there were lower level reasons 409for operation failure. 410.It Fa krp_iparams 411Number of input parameters to the specified operation. 412Note that each operation has a (typically hardwired) number of such parameters. 413.It Fa krp_oparams 414Number of output parameters from the specified operation. 415Note that each operation has a (typically hardwired) number of such parameters. 416.It Fa krp_kvp 417An array of kernel memory blocks containing the parameters. 418.It Fa krp_hid 419Identifier specifying which low-level driver is being used. 420.It Fa krp_callback 421Callback called on completion of a keying operation. 422.El 423.Sh DRIVER-SIDE API 424The 425.Fn crypto_get_driverid , 426.Fn crypto_register , 427.Fn crypto_kregister , 428.Fn crypto_unregister , 429and 430.Fn crypto_done 431routines are used by drivers that provide support for cryptographic 432primitives to register and unregister with the kernel crypto services 433framework. 434Drivers must first use the 435.Fn crypto_get_driverid 436function to acquire a driver identifier, specifying the 437.Fa cc_flags 438as an argument (normally 0, but software-only drivers should specify 439.Dv CRYPTOCAP_F_SOFTWARE ) . 440For each algorithm the driver supports, it must then call 441.Fn crypto_register . 442The first argument is the driver identifier. 443The second argument is an array of 444.Dv CRYPTO_ALGORITHM_MAX + 1 445elements, indicating which algorithms are supported. 446The last three arguments are pointers to three 447driver-provided functions that the framework may call to establish new 448cryptographic context with the driver, free already established 449context, and ask for a request to be processed (encrypt, decrypt, etc.\&) 450.Fn crypto_unregister 451is called by drivers that wish to withdraw support for an algorithm. 452The two arguments are the driver and algorithm identifiers, respectively. 453Typically, drivers for 454.Xr pcmcia 4 455crypto cards that are being ejected will invoke this routine for all 456algorithms supported by the card. 457If called with 458.Dv CRYPTO_ALGORITHM_ALL , 459all algorithms registered for a driver will be unregistered in one go 460and the driver will be disabled (no new sessions will be allocated on 461that driver, and any existing sessions will be migrated to other 462drivers). 463The same will be done if all algorithms associated with a driver are 464unregistered one by one. 465.Pp 466The calling convention for the three driver-supplied routines is: 467.Bd -literal 468int (*newsession) (u_int32_t *, struct cryptoini *); 469int (*freesession) (u_int64_t); 470int (*process) (struct cryptop *); 471int (*kprocess) (struct cryptkop *); 472.Ed 473.Pp 474On invocation, the first argument to 475.Fn newsession 476contains the driver identifier obtained via 477.Fn crypto_get_driverid . 478On successfully returning, it should contain a driver-specific session 479identifier. 480The second argument is identical to that of 481.Fn crypto_newsession . 482.Pp 483The 484.Fn freesession 485routine takes as argument the SID (which is the concatenation of the 486driver identifier and the driver-specific session identifier). 487It should clear any context associated with the session (clear hardware 488registers, memory, etc.). 489.Pp 490The 491.Fn process 492routine is invoked with a request to perform crypto processing. 493This routine must not block, but should queue the request and return 494immediately. 495Upon processing the request, the callback routine should be invoked. 496In case of error, the error indication must be placed in the 497.Fa crp_etype 498field of the 499.Fa cryptop 500structure. 501When the request is completed, or an error is detected, the 502.Fn process 503routine should invoke 504.Fn crypto_done . 505Session migration may be performed, as mentioned previously. 506.Pp 507The 508.Fn kprocess 509routine is invoked with a request to perform crypto key processing. 510This routine must not block, but should queue the request and return 511immediately. 512Upon processing the request, the callback routine should be invoked. 513In case of error, the error indication must be placed in the 514.Fa krp_status 515field of the 516.Fa cryptkop 517structure. 518When the request is completed, or an error is detected, the 519.Fn kprocess 520routine should invoke 521.Fn crypto_kdone . 522.Sh RETURN VALUES 523.Fn crypto_register , 524.Fn crypto_kregister , 525.Fn crypto_unregister , 526.Fn crypto_newsession , 527and 528.Fn crypto_freesession 529return 0 on success, or an error code on failure. 530.Fn crypto_get_driverid 531returns a non-negative value on error, and \-1 on failure. 532.Fn crypto_getreq 533returns a pointer to a 534.Fa cryptop 535structure and 536.Dv NULL 537on failure. 538.Fn crypto_dispatch 539returns 540.Er EINVAL 541if its argument or the callback function was 542.Dv NULL , 543and 0 otherwise. 544The callback is provided with an error code in case of failure, in the 545.Fa crp_etype 546field. 547.Sh FILES 548.Bl -tag -width sys/crypto/crypto.c 549.It Pa sys/crypto/crypto.c 550most of the framework code 551.El 552.Sh SEE ALSO 553.Xr ipsec 4 , 554.Xr pcmcia 4 , 555.Xr malloc 9 , 556.Xr tsleep 9 557.Sh HISTORY 558The cryptographic framework first appeared in 559.Ox 2.7 560and was written by 561.An Angelos D. Keromytis Aq angelos@openbsd.org . 562.Sh BUGS 563The framework currently assumes that all the algorithms in a 564.Fn crypto_newsession 565operation must be available by the same driver. 566If that's not the case, session initialization will fail. 567.Pp 568The framework also needs a mechanism for determining which driver is 569best for a specific set of algorithms associated with a session. 570Some type of benchmarking is in order here. 571.Pp 572Multiple instances of the same algorithm in the same session are not 573supported. 574Note that 3DES is considered one algorithm (and not three 575instances of DES). 576Thus, 3DES and DES could be mixed in the same request. 577.Pp 578A queue for completed operations should be implemented and processed 579at some software 580.Xr spl 9 581level, to avoid overall system latency issues, and potential kernel 582stack exhaustion while processing a callback. 583.Pp 584When SMP time comes, we will support use of a second processor (or 585more) as a crypto device (this is actually AMP, but we need the same 586basic support). 587