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