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