From 1403a8c73e7df9a899069b54eff21618de5c687e Mon Sep 17 00:00:00 2001 From: Sam Leffler Date: Mon, 14 Oct 2002 20:23:41 +0000 Subject: [PATCH] update to better reflect reality: o describe additional argument in driver callbacks o describe flow-control mechanism for processing crypto requests o remove old cruft o remove openbsd-specific cruft o fixup some references o yada yada ... --- share/man/man9/crypto.9 | 116 ++++++++++++++++++++++------------------ 1 file changed, 65 insertions(+), 51 deletions(-) diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9 index 93d3ddfaceac..4d4949f6631a 100644 --- a/share/man/man9/crypto.9 +++ b/share/man/man9/crypto.9 @@ -16,22 +16,24 @@ .\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR .\" PURPOSE. .\" -.Dd October 3, 2002 +.Dd October 14, 2002 .Dt CRYPTO 9 .Os .Sh NAME .Nm crypto .Nd API for cryptographic services in the kernel .Sh SYNOPSIS -.Fd #include +.Fd #include .Ft int32_t .Fn crypto_get_driverid "u_int8_t" .Ft int -.Fn crypto_register "u_int32_t" "int" "u_int16_t" "u_int32_t" "int (*)(u_int32_t *, struct cryptoini *)" "int (*)(u_int64_t)" "int (*)(struct cryptop *)" +.Fn crypto_register "u_int32_t" "int" "u_int16_t" "u_int32_t" "int (*)(void *, u_int32_t *, struct cryptoini *)" "int (*)(void *, u_int64_t)" "int (*)(void *, struct cryptop *)" "void *" .Ft int -.Fn crypto_kregister "u_int32_t" "int" "u_int32_t" "int (*)(struct cryptkop *)" +.Fn crypto_kregister "u_int32_t" "int" "u_int32_t" "int (*)(void *, struct cryptkop *)" "void *" .Ft int .Fn crypto_unregister "u_int32_t" "int" +.Ft int +.Fn crypto_unregister_all "u_int32_t" .Ft void .Fn crypto_done "struct cryptop *" .Ft void @@ -44,12 +46,17 @@ .Fn crypto_dispatch "struct cryptop *" .Ft int .Fn crypto_kdispatch "struct cryptkop *" +.Ft int +.Fn crypto_unblock "u_int32_t" "int" .Ft struct cryptop * .Fn crypto_getreq "int" .Ft void .Fn crypto_freereq "void" .Bd -literal +#define CRYPTO_SYMQ 0x1 +#define CRYPTO_ASYMQ 0x2 + #define EALG_MAX_BLOCK_LEN 16 struct cryptoini { @@ -71,17 +78,16 @@ struct cryptodesc { }; struct cryptop { + TAILQ_ENTRY(cryptop) crp_next; u_int64_t crp_sid; int crp_ilen; int crp_olen; - int crp_alloctype; int crp_etype; int crp_flags; caddr_t crp_buf; caddr_t crp_opaque; struct cryptodesc *crp_desc; int (*crp_callback) (struct cryptop *); - struct cryptop *crp_next; caddr_t crp_mac; }; @@ -93,17 +99,14 @@ struct crparam { #define CRK_MAXPARAM 8 struct cryptkop { + TAILQ_ENTRY(cryptkop) krp_next; u_int krp_op; /* ie. CRK_MOD_EXP or other */ u_int krp_status; /* return status */ u_short krp_iparams; /* # of input parameters */ u_short krp_oparams; /* # of output parameters */ - u_int krp_pad1; + u_int32_t krp_hid; struct crparam krp_param[CRK_MAXPARAM]; - struct crparam krp_kvp[CRK_MAXPARAM]; - - u_int32_t krp_hid; int (*krp_callback)(struct cryptkop *); - struct cryptkop *krp_next; }; .Ed .br @@ -112,8 +115,10 @@ struct cryptkop { is a framework for drivers of cryptographic hardware to register with the kernel so .Dq consumers -(other kernel subsystems, and eventually -users through an appropriate device) are able to make use of it. +(other kernel subsystems, and +users through the +.Pa /dev/crypto +device) are able to make use of it. Drivers register with the framework the algorithms they support, and provide entry points (functions) the framework may call to establish, use, and tear down sessions. @@ -130,8 +135,8 @@ these sessionless commands perform mathematical operations using input and output parameters. .Pp Since the consumers may not be associated with a process, drivers may -not use -.Xr tsleep 9 . +not +.Xr sleep 9 . The same holds for the framework. Thus, a callback mechanism is used to notify a consumer that a request has been completed (the @@ -181,6 +186,9 @@ CRYPTO_AES_CBC CRYPTO_ARC4 CRYPTO_MD5 CRYPTO_SHA1 +CRYPTO_SHA2_HMAC +CRYPTO_NULL_HMAC +CRYPTO_NULL_CBC .Ed .Pp .It Fa cri_klen @@ -232,10 +240,6 @@ Indicates the total length in bytes of the buffer to be processed. .It Fa crp_olen On return, contains the total length of the result. For symmetric crypto operations, this will be the same as the input length. -.It Fa crp_alloctype -Indicates the type of buffer, as used in the kernel -.Xr malloc 9 -routine. This will be used if the framework needs to allocate a new buffer for the result (or for re-formatting the input). .It Fa crp_callback @@ -288,8 +292,7 @@ Points to the input buffer. On return (when the callback is invoked), it contains the result of the request. The input buffer may be an mbuf -chain or a contiguous buffer (of a type identified by -.Fa crp_alloctype ) , +chain or a contiguous buffer, depending on .Fa crp_flags . .It Fa crp_opaque @@ -428,6 +431,7 @@ The .Fn crypto_register , .Fn crypto_kregister , .Fn crypto_unregister , +.Fn crypto_unblock , and .Fn crypto_done routines are used by drivers that provide support for cryptographic @@ -443,26 +447,24 @@ For each algorithm the driver supports, it must then call .Fn crypto_register . The first two arguments are the driver and algorithm identifiers. The next two arguments specify the largest possible operator length (in bits, -important for public key operations) and flags (e.g., whether an hardware RNG is -available) for this algorithm. -The last three arguments must be provided in the first call to +important for public key operations) and flags for this algorithm. +The last four arguments must be provided in the first call to .Fn crypto_register and are ignored in all subsequent calls. They are pointers to three driver-provided functions that the framework may call to establish new cryptographic context with the driver, free already established context, and ask for a request to be processed (encrypt, decrypt, -etc.) +etc.); and an opaque parameter to pass when calling each of these routines. .Fn crypto_unregister is called by drivers that wish to withdraw support for an algorithm. The two arguments are the driver and algorithm identifiers, respectively. Typically, drivers for -.Xr pcmcia 4 +PCMCIA crypto cards that are being ejected will invoke this routine for all algorithms supported by the card. -If called with -.Dv CRYPTO_ALGORITHM_ALL , -all algorithms registered for a driver will be unregistered in one go +.Fn crypto_unregister_all +will unregister all algorithms registered by a driver and the driver will be disabled (no new sessions will be allocated on that driver, and any existing sessions will be migrated to other drivers). @@ -471,24 +473,29 @@ unregistered one by one. .Pp The calling convention for the three driver-supplied routines is: .Bd -literal -int (*newsession) (u_int32_t *, struct cryptoini *); -int (*freesession) (u_int64_t); -int (*process) (struct cryptop *); -int (*kprocess) (struct cryptkop *); +int (*newsession) (void *, u_int32_t *, struct cryptoini *); +int (*freesession) (void *, u_int64_t); +int (*process) (void *, struct cryptop *); +int (*kprocess) (void *, struct cryptkop *); .Ed .Pp On invocation, the first argument to +all routines is an opaque data value supplied when the algorithm +is registered with +.Fn crypto_register . +The second argument to .Fn newsession contains the driver identifier obtained via .Fn crypto_get_driverid . On successfully returning, it should contain a driver-specific session identifier. -The second argument is identical to that of +The third argument is identical to that of .Fn crypto_newsession . .Pp The .Fn freesession -routine takes as argument the SID (which is the concatenation of the +routine takes as arguments the opaque data value and the SID +(which is the concatenation of the driver identifier and the driver-specific session identifier). It should clear any context associated with the session (clear hardware registers, memory, etc.). @@ -499,24 +506,41 @@ routine is invoked with a request to perform crypto processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. -In case of error, the error indication must be placed in the +In case of an unrecoverable error, the error indication must be placed in the .Fa crp_etype field of the .Fa cryptop structure. When the request is completed, or an error is detected, the .Fn process -routine should invoked +routine should invoke .Fn crypto_done . Session migration may be performed, as mentioned previously. .Pp +In case of a temporary resource exhaustion, the +.FN process +routine may return +.Er ERESTART +in which case the crypto services will requeue the request, mark the driver +as ``blocked'', and stop submitting requests for processing. +The driver is then responsible for notifying the crypto services +when it is again able to process requests through the +.Fn crypto_unblock +routine. +This simple flow control mechanism should only be used for short-lived +resource exhaustion as it causes operations to be queued in the crypto +layer. +Doing so is preferrable to returning an error in such cases as +it can cause network prrotocols to degrade performance by treating the +failure much like a lost packet. +.Pp The .Fn kprocess routine is invoked with a request to perform crypto key processing. This routine must not block, but should queue the request and return immediately. Upon processing the request, the callback routine should be invoked. -In case of error, the error indication must be placed in the +In case of an unrecoverable error, the error indication must be placed in the .Fa krp_status field of the .Fa cryptkop @@ -530,8 +554,9 @@ routine should invoked .Fn crypto_kregister , .Fn crypto_unregister , .Fn crypto_newsession , +.Fn crypto_freesession , and -.Fn crypto_freesession +.Fb crypto_unblock return 0 on success, or an error code on failure. .Fn crypto_get_driverid returns a non-negative value on error, and \-1 on failure. @@ -557,9 +582,8 @@ most of the framework code .El .Sh SEE ALSO .Xr ipsec 4 , -.Xr pcmcia 4 , .Xr malloc 9 , -.Xr tsleep 9 +.Xr sleep 9 .Sh HISTORY The cryptographic framework first appeared in OpenBSD 2.7 @@ -579,13 +603,3 @@ supported. Note that 3DES is considered one algorithm (and not three instances of DES). Thus, 3DES and DES could be mixed in the same request. -.Pp -A queue for completed operations should be implemented and processed -at some software -.Xr spl 9 -level, to avoid overall system latency issues, and potential kernel -stack exhaustion while processing a callback. -.Pp -When SMP time comes, we will support use of a second processor (or -more) as a crypto device (this is actually AMP, but we need the same -basic support).