1f4bf4335SSam Leffler.\" $OpenBSD: crypto.9,v 1.19 2002/07/16 06:31:57 angelos Exp $ 2f4bf4335SSam Leffler.\" 3f4bf4335SSam Leffler.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu) 4f4bf4335SSam Leffler.\" 5f4bf4335SSam Leffler.\" Copyright (c) 2000, 2001 Angelos D. Keromytis 6f4bf4335SSam Leffler.\" 7f4bf4335SSam Leffler.\" Permission to use, copy, and modify this software with or without fee 8f4bf4335SSam Leffler.\" is hereby granted, provided that this entire notice is included in 9f4bf4335SSam Leffler.\" all source code copies of any software which is or includes a copy or 10f4bf4335SSam Leffler.\" modification of this software. 11f4bf4335SSam Leffler.\" 12f4bf4335SSam Leffler.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR 13f4bf4335SSam Leffler.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY 14f4bf4335SSam Leffler.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE 15f4bf4335SSam Leffler.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR 16f4bf4335SSam Leffler.\" PURPOSE. 17f4bf4335SSam Leffler.\" 187621fdabSRuslan Ermilov.\" $FreeBSD$ 197621fdabSRuslan Ermilov.\" 201403a8c7SSam Leffler.Dd October 14, 2002 21f4bf4335SSam Leffler.Dt CRYPTO 9 22f4bf4335SSam Leffler.Os 23f4bf4335SSam Leffler.Sh NAME 24f4bf4335SSam Leffler.Nm crypto 25f4bf4335SSam Leffler.Nd API for cryptographic services in the kernel 26f4bf4335SSam Leffler.Sh SYNOPSIS 277621fdabSRuslan Ermilov.In opencrypto/cryptodev.h 28f4bf4335SSam Leffler.Ft int32_t 297621fdabSRuslan Ermilov.Fn crypto_get_driverid u_int8_t 30f4bf4335SSam Leffler.Ft int 317621fdabSRuslan Ermilov.Fn crypto_register u_int32_t int u_int16_t u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, u_int32_t *, struct cryptoini *\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, u_int64_t\*[rp]" "int \*[lp]*\*[rp]\*[lp]void *, struct cryptop *\*[rp]" "void *" 32f4bf4335SSam Leffler.Ft int 337621fdabSRuslan Ermilov.Fn crypto_kregister u_int32_t int u_int32_t "int \*[lp]*\*[rp]\*[lp]void *, struct cryptkop *\*[rp]" "void *" 34f4bf4335SSam Leffler.Ft int 357621fdabSRuslan Ermilov.Fn crypto_unregister u_int32_t int 361403a8c7SSam Leffler.Ft int 377621fdabSRuslan Ermilov.Fn crypto_unregister_all u_int32_t 38f4bf4335SSam Leffler.Ft void 39f4bf4335SSam Leffler.Fn crypto_done "struct cryptop *" 40f4bf4335SSam Leffler.Ft void 41f4bf4335SSam Leffler.Fn crypto_kdone "struct cryptkop *" 42f4bf4335SSam Leffler.Ft int 437621fdabSRuslan Ermilov.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" int 44f4bf4335SSam Leffler.Ft int 457621fdabSRuslan Ermilov.Fn crypto_freesession u_int64_t 46f4bf4335SSam Leffler.Ft int 47f4bf4335SSam Leffler.Fn crypto_dispatch "struct cryptop *" 48f4bf4335SSam Leffler.Ft int 49f4bf4335SSam Leffler.Fn crypto_kdispatch "struct cryptkop *" 501403a8c7SSam Leffler.Ft int 517621fdabSRuslan Ermilov.Fn crypto_unblock u_int32_t int 527621fdabSRuslan Ermilov.Ft "struct cryptop *" 537621fdabSRuslan Ermilov.Fn crypto_getreq int 54f4bf4335SSam Leffler.Ft void 557621fdabSRuslan Ermilov.Fn crypto_freereq void 56f4bf4335SSam Leffler.Bd -literal 571403a8c7SSam Leffler#define CRYPTO_SYMQ 0x1 581403a8c7SSam Leffler#define CRYPTO_ASYMQ 0x2 591403a8c7SSam Leffler 60f4bf4335SSam Leffler#define EALG_MAX_BLOCK_LEN 16 61f4bf4335SSam Leffler 62f4bf4335SSam Lefflerstruct cryptoini { 63f4bf4335SSam Leffler int cri_alg; 64f4bf4335SSam Leffler int cri_klen; 65f4bf4335SSam Leffler int cri_rnd; 66f4bf4335SSam Leffler caddr_t cri_key; 67f4bf4335SSam Leffler u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; 68f4bf4335SSam Leffler struct cryptoini *cri_next; 69f4bf4335SSam Leffler}; 70f4bf4335SSam Leffler 71f4bf4335SSam Lefflerstruct cryptodesc { 72f4bf4335SSam Leffler int crd_skip; 73f4bf4335SSam Leffler int crd_len; 74f4bf4335SSam Leffler int crd_inject; 75f4bf4335SSam Leffler int crd_flags; 76f4bf4335SSam Leffler struct cryptoini CRD_INI; 77f4bf4335SSam Leffler struct cryptodesc *crd_next; 78f4bf4335SSam Leffler}; 79f4bf4335SSam Leffler 80f4bf4335SSam Lefflerstruct cryptop { 811403a8c7SSam Leffler TAILQ_ENTRY(cryptop) crp_next; 82f4bf4335SSam Leffler u_int64_t crp_sid; 83f4bf4335SSam Leffler int crp_ilen; 84f4bf4335SSam Leffler int crp_olen; 85f4bf4335SSam Leffler int crp_etype; 86f4bf4335SSam Leffler int crp_flags; 87f4bf4335SSam Leffler caddr_t crp_buf; 88f4bf4335SSam Leffler caddr_t crp_opaque; 89f4bf4335SSam Leffler struct cryptodesc *crp_desc; 90f4bf4335SSam Leffler int (*crp_callback) (struct cryptop *); 91f4bf4335SSam Leffler caddr_t crp_mac; 92f4bf4335SSam Leffler}; 93f4bf4335SSam Leffler 94f4bf4335SSam Lefflerstruct crparam { 95f4bf4335SSam Leffler caddr_t crp_p; 96f4bf4335SSam Leffler u_int crp_nbits; 97f4bf4335SSam Leffler}; 98f4bf4335SSam Leffler 99f4bf4335SSam Leffler#define CRK_MAXPARAM 8 100f4bf4335SSam Leffler 101f4bf4335SSam Lefflerstruct cryptkop { 1021403a8c7SSam Leffler TAILQ_ENTRY(cryptkop) krp_next; 103f4bf4335SSam Leffler u_int krp_op; /* ie. CRK_MOD_EXP or other */ 104f4bf4335SSam Leffler u_int krp_status; /* return status */ 105f4bf4335SSam Leffler u_short krp_iparams; /* # of input parameters */ 106f4bf4335SSam Leffler u_short krp_oparams; /* # of output parameters */ 107f4bf4335SSam Leffler u_int32_t krp_hid; 1081403a8c7SSam Leffler struct crparam krp_param[CRK_MAXPARAM]; 109f4bf4335SSam Leffler int (*krp_callback)(struct cryptkop *); 110f4bf4335SSam Leffler}; 111f4bf4335SSam Leffler.Ed 112f4bf4335SSam Leffler.Sh DESCRIPTION 113f4bf4335SSam Leffler.Nm 114f4bf4335SSam Leffleris a framework for drivers of cryptographic hardware to register with 115f4bf4335SSam Lefflerthe kernel so 116f4bf4335SSam Leffler.Dq consumers 1171403a8c7SSam Leffler(other kernel subsystems, and 1181403a8c7SSam Lefflerusers through the 1191403a8c7SSam Leffler.Pa /dev/crypto 1201403a8c7SSam Lefflerdevice) are able to make use of it. 121f4bf4335SSam LefflerDrivers register with the framework the algorithms they support, 122f4bf4335SSam Lefflerand provide entry points (functions) the framework may call to 123f4bf4335SSam Lefflerestablish, use, and tear down sessions. 124f4bf4335SSam LefflerSessions are used to cache cryptographic information in a particular driver 125f4bf4335SSam Leffler(or associated hardware), so initialization is not needed with every request. 126f4bf4335SSam LefflerConsumers of cryptographic services pass a set of 127f4bf4335SSam Lefflerdescriptors that instruct the framework (and the drivers registered 128f4bf4335SSam Lefflerwith it) of the operations that should be applied on the data (more 129f4bf4335SSam Lefflerthan one cryptographic operation can be requested). 130f4bf4335SSam Leffler.Pp 131f4bf4335SSam LefflerKeying operations are supported as well. 132f4bf4335SSam LefflerUnlike the symmetric operators described above, 133f4bf4335SSam Lefflerthese sessionless commands perform mathematical operations using 134f4bf4335SSam Lefflerinput and output parameters. 135f4bf4335SSam Leffler.Pp 136f4bf4335SSam LefflerSince the consumers may not be associated with a process, drivers may 1371403a8c7SSam Lefflernot 1381403a8c7SSam Leffler.Xr sleep 9 . 139f4bf4335SSam LefflerThe same holds for the framework. 140f4bf4335SSam LefflerThus, a callback mechanism is used 141f4bf4335SSam Lefflerto notify a consumer that a request has been completed (the 142f4bf4335SSam Lefflercallback is specified by the consumer on an per-request basis). 143f4bf4335SSam LefflerThe callback is invoked by the framework whether the request was 144f4bf4335SSam Lefflersuccessfully completed or not. 145f4bf4335SSam LefflerAn error indication is provided in the latter case. 146f4bf4335SSam LefflerA specific error code, 147f4bf4335SSam Leffler.Er EAGAIN , 148f4bf4335SSam Leffleris used to indicate that a session number has changed and that the 149f4bf4335SSam Lefflerrequest may be re-submitted immediately with the new session number. 150f4bf4335SSam LefflerErrors are only returned to the invoking function if not 151f4bf4335SSam Lefflerenough information to call the callback is available (meaning, there 152f4bf4335SSam Lefflerwas a fatal error in verifying the arguments). 153f4bf4335SSam LefflerFor session initialization and teardown there is no callback mechanism used. 154f4bf4335SSam Leffler.Pp 155f4bf4335SSam LefflerThe 156f4bf4335SSam Leffler.Fn crypto_newsession 157f4bf4335SSam Lefflerroutine is called by consumers of cryptographic services (such as the 158f4bf4335SSam Leffler.Xr ipsec 4 159f4bf4335SSam Lefflerstack) that wish to establish a new session with the framework. 160f4bf4335SSam LefflerOn success, the first argument will contain the Session Identifier (SID). 161f4bf4335SSam LefflerThe second argument contains all the necessary information for 162f4bf4335SSam Lefflerthe driver to establish the session. 163f4bf4335SSam LefflerThe third argument indicates whether a 164f4bf4335SSam Lefflerhardware driver (1) should be used or not (0). 165f4bf4335SSam LefflerThe various fields in the 1667621fdabSRuslan Ermilov.Vt cryptoini 167f4bf4335SSam Lefflerstructure are: 1687621fdabSRuslan Ermilov.Bl -tag -width ".Va cri_next" 1697621fdabSRuslan Ermilov.It Va cri_alg 170f4bf4335SSam LefflerContains an algorithm identifier. 171f4bf4335SSam LefflerCurrently supported algorithms are: 172f4bf4335SSam Leffler.Pp 1737621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRYPTO_RIPEMD160_HMAC" -compact 1747621fdabSRuslan Ermilov.It Dv CRYPTO_DES_CBC 1757621fdabSRuslan Ermilov.It Dv CRYPTO_3DES_CBC 1767621fdabSRuslan Ermilov.It Dv CRYPTO_BLF_CBC 1777621fdabSRuslan Ermilov.It Dv CRYPTO_CAST_CBC 1787621fdabSRuslan Ermilov.It Dv CRYPTO_SKIPJACK_CBC 1797621fdabSRuslan Ermilov.It Dv CRYPTO_MD5_HMAC 1807621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1_HMAC 1817621fdabSRuslan Ermilov.It Dv CRYPTO_RIPEMD160_HMAC 1827621fdabSRuslan Ermilov.It Dv CRYPTO_MD5_KPDK 1837621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1_KPDK 1847621fdabSRuslan Ermilov.It Dv CRYPTO_AES_CBC 1857621fdabSRuslan Ermilov.It Dv CRYPTO_ARC4 1867621fdabSRuslan Ermilov.It Dv CRYPTO_MD5 1877621fdabSRuslan Ermilov.It Dv CRYPTO_SHA1 1887621fdabSRuslan Ermilov.It Dv CRYPTO_SHA2_HMAC 1897621fdabSRuslan Ermilov.It Dv CRYPTO_NULL_HMAC 1907621fdabSRuslan Ermilov.It Dv CRYPTO_NULL_CBC 1917621fdabSRuslan Ermilov.El 1927621fdabSRuslan Ermilov.It Va cri_klen 193f4bf4335SSam LefflerSpecifies the length of the key in bits, for variable-size key 194f4bf4335SSam Leffleralgorithms. 1957621fdabSRuslan Ermilov.It Va cri_rnd 196f4bf4335SSam LefflerSpecifies the number of rounds to be used with the algorithm, for 197f4bf4335SSam Lefflervariable-round algorithms. 1987621fdabSRuslan Ermilov.It Va cri_key 199f4bf4335SSam LefflerContains the key to be used with the algorithm. 2007621fdabSRuslan Ermilov.It Va cri_iv 201f4bf4335SSam LefflerContains an explicit initialization vector (IV), if it does not prefix 202f4bf4335SSam Lefflerthe data. 203f4bf4335SSam LefflerThis field is ignored during initialization. 204f4bf4335SSam LefflerIf no IV is explicitly passed (see below on details), a random IV is used 205f4bf4335SSam Lefflerby the device driver processing the request. 2067621fdabSRuslan Ermilov.It Va cri_next 207f4bf4335SSam LefflerContains a pointer to another 2087621fdabSRuslan Ermilov.Vt cryptoini 209f4bf4335SSam Lefflerstructure. 210f4bf4335SSam LefflerMultiple such structures may be linked to establish multi-algorithm sessions 2117621fdabSRuslan Ermilov.Xr ( ipsec 4 212f4bf4335SSam Leffleris an example consumer of such a feature). 213f4bf4335SSam Leffler.El 214f4bf4335SSam Leffler.Pp 215f4bf4335SSam LefflerThe 2167621fdabSRuslan Ermilov.Vt cryptoini 217f4bf4335SSam Lefflerstructure and its contents will not be modified by the framework (or 218f4bf4335SSam Lefflerthe drivers used). 219f4bf4335SSam LefflerSubsequent requests for processing that use the 220f4bf4335SSam LefflerSID returned will avoid the cost of re-initializing the hardware (in 221f4bf4335SSam Leffleressence, SID acts as an index in the session cache of the driver). 222f4bf4335SSam Leffler.Pp 223f4bf4335SSam Leffler.Fn crypto_freesession 224f4bf4335SSam Leffleris called with the SID returned by 225f4bf4335SSam Leffler.Fn crypto_newsession 226f4bf4335SSam Lefflerto disestablish the session. 227f4bf4335SSam Leffler.Pp 228f4bf4335SSam Leffler.Fn crypto_dispatch 229f4bf4335SSam Leffleris called to process a request. 230f4bf4335SSam LefflerThe various fields in the 2317621fdabSRuslan Ermilov.Vt cryptop 232f4bf4335SSam Lefflerstructure are: 2337621fdabSRuslan Ermilov.Bl -tag -width ".Va crp_callback" 2347621fdabSRuslan Ermilov.It Va crp_sid 235f4bf4335SSam LefflerContains the SID. 2367621fdabSRuslan Ermilov.It Va crp_ilen 237f4bf4335SSam LefflerIndicates the total length in bytes of the buffer to be processed. 2387621fdabSRuslan Ermilov.It Va crp_olen 239f4bf4335SSam LefflerOn return, contains the total length of the result. 240f4bf4335SSam LefflerFor symmetric crypto operations, this will be the same as the input length. 241f4bf4335SSam LefflerThis will be used if the framework needs to allocate a new 242f4bf4335SSam Lefflerbuffer for the result (or for re-formatting the input). 2437621fdabSRuslan Ermilov.It Va crp_callback 244f4bf4335SSam LefflerThis routine is invoked upon completion of the request, whether 245f4bf4335SSam Lefflersuccessful or not. 246f4bf4335SSam LefflerIt is invoked through the 247f4bf4335SSam Leffler.Fn crypto_done 248f4bf4335SSam Lefflerroutine. 249f4bf4335SSam LefflerIf the request was not successful, an error code is set in the 2507621fdabSRuslan Ermilov.Va crp_etype 251f4bf4335SSam Lefflerfield. 252f4bf4335SSam LefflerIt is the responsibility of the callback routine to set the appropriate 253f4bf4335SSam Leffler.Xr spl 9 254f4bf4335SSam Lefflerlevel. 2557621fdabSRuslan Ermilov.It Va crp_etype 256f4bf4335SSam LefflerContains the error type, if any errors were encountered, or zero if 257f4bf4335SSam Lefflerthe request was successfully processed. 258f4bf4335SSam LefflerIf the 259f4bf4335SSam Leffler.Er EAGAIN 260f4bf4335SSam Lefflererror code is returned, the SID has changed (and has been recorded in the 2617621fdabSRuslan Ermilov.Va crp_sid 262f4bf4335SSam Lefflerfield). 263f4bf4335SSam LefflerThe consumer should record the new SID and use it in all subsequent requests. 264f4bf4335SSam LefflerIn this case, the request may be re-submitted immediately. 265f4bf4335SSam LefflerThis mechanism is used by the framework to perform 266f4bf4335SSam Lefflersession migration (move a session from one driver to another, because 267f4bf4335SSam Lefflerof availability, performance, or other considerations). 268f4bf4335SSam Leffler.Pp 269f4bf4335SSam LefflerNote that this field only makes sense when examined by 270f4bf4335SSam Lefflerthe callback routine specified in 2717621fdabSRuslan Ermilov.Va crp_callback . 272f4bf4335SSam LefflerErrors are returned to the invoker of 273f4bf4335SSam Leffler.Fn crypto_process 274f4bf4335SSam Leffleronly when enough information is not present to call the callback 275f4bf4335SSam Lefflerroutine (i.e., if the pointer passed is 276f4bf4335SSam Leffler.Dv NULL 277f4bf4335SSam Leffleror if no callback routine was specified). 2787621fdabSRuslan Ermilov.It Va crp_flags 279f4bf4335SSam LefflerIs a bitmask of flags associated with this request. 280f4bf4335SSam LefflerCurrently defined flags are: 2817621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRYPTO_F_IMBUF" 282f4bf4335SSam Leffler.It Dv CRYPTO_F_IMBUF 283f4bf4335SSam LefflerThe buffer pointed to by 2847621fdabSRuslan Ermilov.Va crp_buf 285f4bf4335SSam Leffleris an mbuf chain. 286f4bf4335SSam Leffler.El 2877621fdabSRuslan Ermilov.It Va crp_buf 288f4bf4335SSam LefflerPoints to the input buffer. 289f4bf4335SSam LefflerOn return (when the callback is invoked), 290f4bf4335SSam Lefflerit contains the result of the request. 291f4bf4335SSam LefflerThe input buffer may be an mbuf 2921403a8c7SSam Lefflerchain or a contiguous buffer, 293f4bf4335SSam Lefflerdepending on 2947621fdabSRuslan Ermilov.Va crp_flags . 2957621fdabSRuslan Ermilov.It Va crp_opaque 296f4bf4335SSam LefflerThis is passed through the crypto framework untouched and is 297f4bf4335SSam Lefflerintended for the invoking application's use. 2987621fdabSRuslan Ermilov.It Va crp_desc 299f4bf4335SSam LefflerThis is a linked list of descriptors. 300f4bf4335SSam LefflerEach descriptor provides 301f4bf4335SSam Lefflerinformation about what type of cryptographic operation should be done 302f4bf4335SSam Leffleron the input buffer. 303f4bf4335SSam LefflerThe various fields are: 3047621fdabSRuslan Ermilov.Bl -tag -width ".Va crd_inject" 3057621fdabSRuslan Ermilov.It Va crd_skip 306f4bf4335SSam LefflerThe offset in the input buffer where processing should start. 3077621fdabSRuslan Ermilov.It Va crd_len 308f4bf4335SSam LefflerHow many bytes, after 3097621fdabSRuslan Ermilov.Va crd_skip , 310f4bf4335SSam Lefflershould be processed. 3117621fdabSRuslan Ermilov.It Va crd_inject 312f4bf4335SSam LefflerOffset from the beginning of the buffer to insert any results. 313f4bf4335SSam LefflerFor encryption algorithms, this is where the initialization vector 314f4bf4335SSam Leffler(IV) will be inserted when encrypting or where it can be found when 315f4bf4335SSam Lefflerdecrypting (subject to 3167621fdabSRuslan Ermilov.Va crd_flags ) . 317f4bf4335SSam LefflerFor MAC algorithms, this is where the result of the keyed hash will be 318f4bf4335SSam Lefflerinserted. 3197621fdabSRuslan Ermilov.It Va crd_flags 320f4bf4335SSam LefflerThe following flags are defined: 3217621fdabSRuslan Ermilov.Bl -tag -width ".Dv CRD_F_IV_EXPLICIT" 322f4bf4335SSam Leffler.It Dv CRD_F_ENCRYPT 323f4bf4335SSam LefflerFor encryption algorithms, this bit is set when encryption is required 324f4bf4335SSam Leffler(when not set, decryption is performed). 325f4bf4335SSam Leffler.It Dv CRD_F_IV_PRESENT 326f4bf4335SSam LefflerFor encryption algorithms, this bit is set when the IV already 327f4bf4335SSam Lefflerprecedes the data, so the 3287621fdabSRuslan Ermilov.Va crd_inject 329f4bf4335SSam Lefflervalue will be ignored and no IV will be written in the buffer. 330f4bf4335SSam LefflerOtherwise, the IV used to encrypt the packet will be written 331f4bf4335SSam Lefflerat the location pointed to by 3327621fdabSRuslan Ermilov.Va crd_inject . 333f4bf4335SSam LefflerThe IV length is assumed to be equal to the blocksize of the 334f4bf4335SSam Lefflerencryption algorithm. 335f4bf4335SSam LefflerSome applications that do special 3367621fdabSRuslan Ermilov.Dq "IV cooking" , 337f4bf4335SSam Lefflersuch as the half-IV mode in 338f4bf4335SSam Leffler.Xr ipsec 4 , 339f4bf4335SSam Lefflercan use this flag to indicate that the IV should not be written on the packet. 340f4bf4335SSam LefflerThis flag is typically used in conjunction with the 341f4bf4335SSam Leffler.Dv CRD_F_IV_EXPLICIT 342f4bf4335SSam Lefflerflag. 343f4bf4335SSam Leffler.It Dv CRD_F_IV_EXPLICIT 344f4bf4335SSam LefflerFor encryption algorithms, this bit is set when the IV is explicitly 345f4bf4335SSam Lefflerprovided by the consumer in the 3467621fdabSRuslan Ermilov.Va cri_iv 347f4bf4335SSam Lefflerfields. 348f4bf4335SSam LefflerOtherwise, for encryption operations the IV is provided for by 349f4bf4335SSam Lefflerthe driver used to perform the operation, whereas for decryption 350f4bf4335SSam Leffleroperations it is pointed to by the 3517621fdabSRuslan Ermilov.Va crd_inject 352f4bf4335SSam Lefflerfield. 353f4bf4335SSam LefflerThis flag is typically used when the IV is calculated 3547621fdabSRuslan Ermilov.Dq "on the fly" 355f4bf4335SSam Lefflerby the consumer, and does not precede the data (some 356f4bf4335SSam Leffler.Xr ipsec 4 357f4bf4335SSam Lefflerconfigurations, and the encrypted swap are two such examples). 358f4bf4335SSam Leffler.It Dv CRD_F_COMP 359f4bf4335SSam LefflerFor compression algorithms, this bit is set when compression is required (when 360f4bf4335SSam Lefflernot set, decompression is performed). 361f4bf4335SSam Leffler.El 3627621fdabSRuslan Ermilov.It Va CRD_INI 363f4bf4335SSam LefflerThis 3647621fdabSRuslan Ermilov.Vt cryptoini 365f4bf4335SSam Lefflerstructure will not be modified by the framework or the device drivers. 366f4bf4335SSam LefflerSince this information accompanies every cryptographic 367f4bf4335SSam Leffleroperation request, drivers may re-initialize state on-demand 368f4bf4335SSam Leffler(typically an expensive operation). 369f4bf4335SSam LefflerFurthermore, the cryptographic 370f4bf4335SSam Lefflerframework may re-route requests as a result of full queues or hardware 371f4bf4335SSam Lefflerfailure, as described above. 3727621fdabSRuslan Ermilov.It Va crd_next 373f4bf4335SSam LefflerPoint to the next descriptor. 374f4bf4335SSam LefflerLinked operations are useful in protocols such as 375f4bf4335SSam Leffler.Xr ipsec 4 , 376f4bf4335SSam Lefflerwhere multiple cryptographic transforms may be applied on the same 377f4bf4335SSam Lefflerblock of data. 378f4bf4335SSam Leffler.El 379f4bf4335SSam Leffler.El 380f4bf4335SSam Leffler.Pp 381f4bf4335SSam Leffler.Fn crypto_getreq 382f4bf4335SSam Lefflerallocates a 3837621fdabSRuslan Ermilov.Vt cryptop 384f4bf4335SSam Lefflerstructure with a linked list of as many 3857621fdabSRuslan Ermilov.Vt cryptodesc 386f4bf4335SSam Lefflerstructures as were specified in the argument passed to it. 387f4bf4335SSam Leffler.Pp 388f4bf4335SSam Leffler.Fn crypto_freereq 389f4bf4335SSam Lefflerdeallocates a structure 3907621fdabSRuslan Ermilov.Vt cryptop 391f4bf4335SSam Lefflerand any 3927621fdabSRuslan Ermilov.Vt cryptodesc 393f4bf4335SSam Lefflerstructures linked to it. 394f4bf4335SSam LefflerNote that it is the responsibility of the 395f4bf4335SSam Lefflercallback routine to do the necessary cleanups associated with the 396f4bf4335SSam Leffleropaque field in the 3977621fdabSRuslan Ermilov.Vt cryptop 398f4bf4335SSam Lefflerstructure. 399f4bf4335SSam Leffler.Pp 400f4bf4335SSam Leffler.Fn crypto_kdispatch 401f4bf4335SSam Leffleris called to perform a keying operation. 402f4bf4335SSam LefflerThe various fields in the 4037621fdabSRuslan Ermilov.Vt cryptkop 404f4bf4335SSam Lefflerstructure are: 4057621fdabSRuslan Ermilov.Bl -tag -width ".Va krp_callback' 4067621fdabSRuslan Ermilov.It Va krp_op 4077621fdabSRuslan ErmilovOperation code, such as 4087621fdabSRuslan Ermilov.Dv CRK_MOD_EXP . 4097621fdabSRuslan Ermilov.It Va krp_status 410f4bf4335SSam LefflerReturn code. 4117621fdabSRuslan ErmilovThis 4127621fdabSRuslan Ermilov.Va errno Ns -style 4137621fdabSRuslan Ermilovvariable indicates whether lower level reasons 414f4bf4335SSam Lefflerfor operation failure. 4157621fdabSRuslan Ermilov.It Va krp_iparams 416f4bf4335SSam LefflerNumber if input parameters to the specified operation. 417f4bf4335SSam LefflerNote that each operation has a (typically hardwired) number of such parameters. 4187621fdabSRuslan Ermilov.It Va krp_oparams 419f4bf4335SSam LefflerNumber if output parameters from the specified operation. 420f4bf4335SSam LefflerNote that each operation has a (typically hardwired) number of such parameters. 4217621fdabSRuslan Ermilov.It Va krp_kvp 422f4bf4335SSam LefflerAn array of kernel memory blocks containing the parameters. 4237621fdabSRuslan Ermilov.It Va krp_hid 424f4bf4335SSam LefflerIdentifier specifying which low-level driver is being used. 4257621fdabSRuslan Ermilov.It Va krp_callback 426f4bf4335SSam LefflerCallback called on completion of a keying operation. 427f4bf4335SSam Leffler.El 428f4bf4335SSam Leffler.Sh DRIVER-SIDE API 429f4bf4335SSam LefflerThe 430f4bf4335SSam Leffler.Fn crypto_get_driverid , 431f4bf4335SSam Leffler.Fn crypto_register , 432f4bf4335SSam Leffler.Fn crypto_kregister , 433f4bf4335SSam Leffler.Fn crypto_unregister , 4341403a8c7SSam Leffler.Fn crypto_unblock , 435f4bf4335SSam Lefflerand 436f4bf4335SSam Leffler.Fn crypto_done 437f4bf4335SSam Lefflerroutines are used by drivers that provide support for cryptographic 438f4bf4335SSam Lefflerprimitives to register and unregister with the kernel crypto services 439f4bf4335SSam Lefflerframework. 440f4bf4335SSam LefflerDrivers must first use the 441f4bf4335SSam Leffler.Fn crypto_get_driverid 442f4bf4335SSam Lefflerfunction to acquire a driver identifier, specifying the 443f4bf4335SSam Leffler.Fa cc_flags 444f4bf4335SSam Leffleras an argument (normally 0, but software-only drivers should specify 4457621fdabSRuslan Ermilov.Dv CRYPTOCAP_F_SOFTWARE ) . 446f4bf4335SSam LefflerFor each algorithm the driver supports, it must then call 447f4bf4335SSam Leffler.Fn crypto_register . 448f4bf4335SSam LefflerThe first two arguments are the driver and algorithm identifiers. 449f4bf4335SSam LefflerThe next two arguments specify the largest possible operator length (in bits, 4501403a8c7SSam Lefflerimportant for public key operations) and flags for this algorithm. 4511403a8c7SSam LefflerThe last four arguments must be provided in the first call to 452f4bf4335SSam Leffler.Fn crypto_register 453f4bf4335SSam Lefflerand are ignored in all subsequent calls. 454f4bf4335SSam LefflerThey are pointers to three 455f4bf4335SSam Lefflerdriver-provided functions that the framework may call to establish new 456f4bf4335SSam Lefflercryptographic context with the driver, free already established 457f4bf4335SSam Lefflercontext, and ask for a request to be processed (encrypt, decrypt, 4581403a8c7SSam Leffleretc.); and an opaque parameter to pass when calling each of these routines. 459f4bf4335SSam Leffler.Fn crypto_unregister 460f4bf4335SSam Leffleris called by drivers that wish to withdraw support for an algorithm. 461f4bf4335SSam LefflerThe two arguments are the driver and algorithm identifiers, respectively. 462f4bf4335SSam LefflerTypically, drivers for 4631403a8c7SSam LefflerPCMCIA 464f4bf4335SSam Lefflercrypto cards that are being ejected will invoke this routine for all 465f4bf4335SSam Leffleralgorithms supported by the card. 4661403a8c7SSam Leffler.Fn crypto_unregister_all 4671403a8c7SSam Lefflerwill unregister all algorithms registered by a driver 468f4bf4335SSam Lefflerand the driver will be disabled (no new sessions will be allocated on 469f4bf4335SSam Lefflerthat driver, and any existing sessions will be migrated to other 470f4bf4335SSam Lefflerdrivers). 471f4bf4335SSam LefflerThe same will be done if all algorithms associated with a driver are 472f4bf4335SSam Lefflerunregistered one by one. 473f4bf4335SSam Leffler.Pp 474f4bf4335SSam LefflerThe calling convention for the three driver-supplied routines is: 4757621fdabSRuslan Ermilov.Pp 4767621fdabSRuslan Ermilov.Bl -item -compact 4777621fdabSRuslan Ermilov.It 4787621fdabSRuslan Ermilov.Ft int 4797621fdabSRuslan Ermilov.Fn \*[lp]*newsession\*[rp] "void *" "u_int32_t *" "struct cryptoini *" ; 4807621fdabSRuslan Ermilov.It 4817621fdabSRuslan Ermilov.Ft int 4827621fdabSRuslan Ermilov.Fn \*[lp]*freesession\*[rp] "void *" "u_int64_t" ; 4837621fdabSRuslan Ermilov.It 4847621fdabSRuslan Ermilov.Ft int 4857621fdabSRuslan Ermilov.Fn \*[lp]*process\*[rp] "void *" "struct cryptop *" ; 4867621fdabSRuslan Ermilov.It 4877621fdabSRuslan Ermilov.Ft int 4887621fdabSRuslan Ermilov.Fn \*[lp]*kprocess\*[rp] "void *" "struct cryptkop *" ; 4897621fdabSRuslan Ermilov.El 490f4bf4335SSam Leffler.Pp 491f4bf4335SSam LefflerOn invocation, the first argument to 4921403a8c7SSam Lefflerall routines is an opaque data value supplied when the algorithm 4931403a8c7SSam Leffleris registered with 4941403a8c7SSam Leffler.Fn crypto_register . 4951403a8c7SSam LefflerThe second argument to 496f4bf4335SSam Leffler.Fn newsession 497f4bf4335SSam Lefflercontains the driver identifier obtained via 498f4bf4335SSam Leffler.Fn crypto_get_driverid . 4997621fdabSRuslan ErmilovOn successful return, it should contain a driver-specific session 500f4bf4335SSam Leffleridentifier. 5011403a8c7SSam LefflerThe third argument is identical to that of 502f4bf4335SSam Leffler.Fn crypto_newsession . 503f4bf4335SSam Leffler.Pp 504f4bf4335SSam LefflerThe 505f4bf4335SSam Leffler.Fn freesession 5061403a8c7SSam Lefflerroutine takes as arguments the opaque data value and the SID 5071403a8c7SSam Leffler(which is the concatenation of the 508f4bf4335SSam Lefflerdriver identifier and the driver-specific session identifier). 509f4bf4335SSam LefflerIt should clear any context associated with the session (clear hardware 510f4bf4335SSam Lefflerregisters, memory, etc.). 511f4bf4335SSam Leffler.Pp 512f4bf4335SSam LefflerThe 513f4bf4335SSam Leffler.Fn process 514f4bf4335SSam Lefflerroutine is invoked with a request to perform crypto processing. 515f4bf4335SSam LefflerThis routine must not block, but should queue the request and return 516f4bf4335SSam Lefflerimmediately. 517f4bf4335SSam LefflerUpon processing the request, the callback routine should be invoked. 5181403a8c7SSam LefflerIn case of an unrecoverable error, the error indication must be placed in the 5197621fdabSRuslan Ermilov.Va crp_etype 520f4bf4335SSam Lefflerfield of the 5217621fdabSRuslan Ermilov.Vt cryptop 522f4bf4335SSam Lefflerstructure. 523f4bf4335SSam LefflerWhen the request is completed, or an error is detected, the 524f4bf4335SSam Leffler.Fn process 5251403a8c7SSam Lefflerroutine should invoke 526f4bf4335SSam Leffler.Fn crypto_done . 527f4bf4335SSam LefflerSession migration may be performed, as mentioned previously. 528f4bf4335SSam Leffler.Pp 5291403a8c7SSam LefflerIn case of a temporary resource exhaustion, the 5307621fdabSRuslan Ermilov.Fn process 5311403a8c7SSam Lefflerroutine may return 5321403a8c7SSam Leffler.Er ERESTART 5331403a8c7SSam Lefflerin which case the crypto services will requeue the request, mark the driver 5347621fdabSRuslan Ermilovas 5357621fdabSRuslan Ermilov.Dq blocked , 5367621fdabSRuslan Ermilovand stop submitting requests for processing. 5371403a8c7SSam LefflerThe driver is then responsible for notifying the crypto services 5381403a8c7SSam Lefflerwhen it is again able to process requests through the 5391403a8c7SSam Leffler.Fn crypto_unblock 5401403a8c7SSam Lefflerroutine. 5411403a8c7SSam LefflerThis simple flow control mechanism should only be used for short-lived 5421403a8c7SSam Lefflerresource exhaustion as it causes operations to be queued in the crypto 5431403a8c7SSam Lefflerlayer. 5447621fdabSRuslan ErmilovDoing so is preferable to returning an error in such cases as 5457621fdabSRuslan Ermilovit can cause network protocols to degrade performance by treating the 5461403a8c7SSam Lefflerfailure much like a lost packet. 5471403a8c7SSam Leffler.Pp 548f4bf4335SSam LefflerThe 549f4bf4335SSam Leffler.Fn kprocess 550f4bf4335SSam Lefflerroutine is invoked with a request to perform crypto key processing. 551f4bf4335SSam LefflerThis routine must not block, but should queue the request and return 552f4bf4335SSam Lefflerimmediately. 553f4bf4335SSam LefflerUpon processing the request, the callback routine should be invoked. 5541403a8c7SSam LefflerIn case of an unrecoverable error, the error indication must be placed in the 5557621fdabSRuslan Ermilov.Va krp_status 556f4bf4335SSam Lefflerfield of the 5577621fdabSRuslan Ermilov.Vt cryptkop 558f4bf4335SSam Lefflerstructure. 559f4bf4335SSam LefflerWhen the request is completed, or an error is detected, the 560f4bf4335SSam Leffler.Fn kprocess 561f4bf4335SSam Lefflerroutine should invoked 562f4bf4335SSam Leffler.Fn crypto_kdone . 563f4bf4335SSam Leffler.Sh RETURN VALUES 564f4bf4335SSam Leffler.Fn crypto_register , 565f4bf4335SSam Leffler.Fn crypto_kregister , 566f4bf4335SSam Leffler.Fn crypto_unregister , 567f4bf4335SSam Leffler.Fn crypto_newsession , 5681403a8c7SSam Leffler.Fn crypto_freesession , 569f4bf4335SSam Lefflerand 5707621fdabSRuslan Ermilov.Fn crypto_unblock 571f4bf4335SSam Lefflerreturn 0 on success, or an error code on failure. 572f4bf4335SSam Leffler.Fn crypto_get_driverid 573f4bf4335SSam Lefflerreturns a non-negative value on error, and \-1 on failure. 574f4bf4335SSam Leffler.Fn crypto_getreq 575f4bf4335SSam Lefflerreturns a pointer to a 5767621fdabSRuslan Ermilov.Vt cryptop 577f4bf4335SSam Lefflerstructure and 578f4bf4335SSam Leffler.Dv NULL 579f4bf4335SSam Leffleron failure. 580f4bf4335SSam Leffler.Fn crypto_dispatch 581f4bf4335SSam Lefflerreturns 582f4bf4335SSam Leffler.Er EINVAL 5837621fdabSRuslan Ermilovif its argument or the callback function was 584f4bf4335SSam Leffler.Dv NULL , 585f4bf4335SSam Lefflerand 0 otherwise. 586f4bf4335SSam LefflerThe callback is provided with an error code in case of failure, in the 5877621fdabSRuslan Ermilov.Va crp_etype 588f4bf4335SSam Lefflerfield. 589f4bf4335SSam Leffler.Sh FILES 5907621fdabSRuslan Ermilov.Bl -tag -width ".Pa sys/crypto/crypto.c" 591f4bf4335SSam Leffler.It Pa sys/crypto/crypto.c 592f4bf4335SSam Lefflermost of the framework code 593f4bf4335SSam Leffler.El 594f4bf4335SSam Leffler.Sh SEE ALSO 595f4bf4335SSam Leffler.Xr ipsec 4 , 596f4bf4335SSam Leffler.Xr malloc 9 , 5971403a8c7SSam Leffler.Xr sleep 9 598f4bf4335SSam Leffler.Sh HISTORY 599f4bf4335SSam LefflerThe cryptographic framework first appeared in 6007621fdabSRuslan Ermilov.Ox 2.7 6017621fdabSRuslan Ermilovand was written by 6027621fdabSRuslan Ermilov.An "Angelos D. Keromytis" Aq angelos@openbsd.org . 603f4bf4335SSam Leffler.Sh BUGS 604f4bf4335SSam LefflerThe framework currently assumes that all the algorithms in a 605f4bf4335SSam Leffler.Fn crypto_newsession 606f4bf4335SSam Leffleroperation must be available by the same driver. 6077621fdabSRuslan ErmilovIf that is not the case, session initialization will fail. 608f4bf4335SSam Leffler.Pp 609f4bf4335SSam LefflerThe framework also needs a mechanism for determining which driver is 610f4bf4335SSam Lefflerbest for a specific set of algorithms associated with a session. 611f4bf4335SSam LefflerSome type of benchmarking is in order here. 612f4bf4335SSam Leffler.Pp 613f4bf4335SSam LefflerMultiple instances of the same algorithm in the same session are not 614f4bf4335SSam Lefflersupported. 615f4bf4335SSam LefflerNote that 3DES is considered one algorithm (and not three 616f4bf4335SSam Lefflerinstances of DES). 617f4bf4335SSam LefflerThus, 3DES and DES could be mixed in the same request. 618