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