diff options
| -rw-r--r-- | share/man/man9/crypto.9 | 467 |
1 files changed, 467 insertions, 0 deletions
diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9 new file mode 100644 index 00000000000..a19626f7f04 --- /dev/null +++ b/share/man/man9/crypto.9 @@ -0,0 +1,467 @@ +.\" $OpenBSD: crypto.9,v 1.1 2000/04/28 05:42:50 angelos Exp $ +.\" +.\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu) +.\" +.\" Copyright (c) 2000 Angelos D. Keromytis +.\" +.\" Permission to use, copy, and modify this software without fee +.\" is hereby granted, provided that this entire notice is included in +.\" all source code copies of any software which is or includes a copy or +.\" modification of this software. +.\" +.\" THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR +.\" IMPLIED WARRANTY. IN PARTICULAR, NONE OF THE AUTHORS MAKES ANY +.\" REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE +.\" MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR +.\" PURPOSE. +.\" +.Dd April 21, 2000 +.Dt CRYPTO 9 +.Os +.Sh NAME +.Nm crypto +.Nd API for cryptographic services in the kernel +.Sh SYNOPSIS +.Fd #include <crypto/crypto> +.Ft int32_t +.Fn crypto_get_driverid "void" +.Ft int +.Fn crypto_register "u_int32_t" "int" "void *" "void *" "void *" +.Ft int +.Fn crypto_unregister "u_int32_t" "int" +.Ft int +.Fn crypto_newsession "u_int64_t *" "struct cryptoini *" +.Ft int +.Fn crypto_freesession "u_int64_t" +.Ft int +.Fn crypto_dispatch "struct cryptop *" +.Ft struct cryptop * +.Fn crypto_getreq "int" +.Ft void +.Fn crypto_freereq "void" +.Bd -literal + +#define EALG_MAX_BLOCK_LEN 8 + +struct cryptoini +{ + int cri_alg; + int cri_klen; + int cri_rnd; + caddr_t cri_key; + u_int8_t cri_iv[EALG_MAX_BLOCK_LEN]; + struct cryptoini *cri_next; +}; + +struct cryptodesc +{ + int crd_skip; + int crd_len; + int crd_inject; + int crd_flags; + struct cryptoini CRD_INI; + struct cryptodesc *crd_next; +}; + +struct cryptop +{ + 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_opaque1; + caddr_t crp_opaque2; + caddr_t crp_opaque3; + caddr_t crp_opaque4; + struct cryptodesc *crp_desc; + int (*crp_callback) (struct cryptop *); +}; +.Ed +.br +.Sh DESCRIPTION +.Nm +is a framework for drivers of cryptographic hardware to register with +the kernel so ``consumers'' (other kernel subsystems, and eventually +users through an appropriate 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. Sessions are used to cache +cryptographic information in a particular driver (or associated +hardware), so initialization is not needed with every +request. Consumers of cryptographic services pass a set of +descriptors that instruct the framework (and the drivers registered +with it) of the operations that should be applied on the data (more +than one cryptographic operation can be requested). +.Pp +Since the consumers may not be associated with a process, drivers may +not use +.Xr tsleep 9 . +The same holds for the framework. Thus, a callback mechanism is used +to notify a consumer that a request has been completed (the +callback is specified by the consumer on an per-request basis). The +callback is invoked by the framework whether the request was +successfully completed or not. An error indication is provided in the +latter case. A specific error code, +.Va EAGAIN , +is used to indicate that a session number has changed and that the +request may be re-submitted immediately with the new session +number. Errors are only returned to the invoking function if not +enough information to call the callback is available (meaning, there +was a fatal error in verifying the arguments). For session +initialization and teardown there is no callback mechanism used. +.Pp +The +.Fn crypto_newsession +routine is called by consumers of cryptographic services (such as the +.Xr ipsec 4 +stack) that wish to establish a new session with the framework. On +success, the first argument will contain the Session Identifier +(SID). The second argument contains all the necessary information for +the driver to establish the session. The various fields in the +.Va cryptoini +structure are: +.Bl -tag -width foobarmoocow +.It cri_alg +Contains an algorithm identifier. Currently supported algorithms are: +.Bd -literal +CRYPTO_DES_CBC +CRYPTO_3DES_CBC +CRYPTO_BLF_CBC +CRYPTO_CAST_CBC +CRYPTO_SKIPJACK_CBC +CRYPTO_MD5_HMAC96 +CRYPTO_SHA1_HMAC96 +CRYPTO_RIPEMD160_HMAC96 +CRYPTO_MD5_KPDK +CRYPTO_SHA1_KPDK +.Ed +.Br +.It cri_klen +Specifies the length of the key in bits, for variable-size key +algorithms. +.It cri_rnd +Specifies the number of rounds to be used with the algorithm, for +variable-round algorithms. +.It cri_key +Contains the key to be used with the algorithm. +.It cri_iv +Contains an explicit initialization vector (IV), if it does not prefix +the data. This field is ignored during initialization. If no IV is +explicitly passed (see below on details), a random IV is used by the +device driver processing the request. +.It cri_next +Contains a pointer to another +.Va cryptoini +structure. Multiple such structures may be linked, to establish +multi-algorithm sessions ( +.Xr ipsec 4 +is an example consumer of such a feature). +.El +.Pp +The +.Va cryptoini +structure and its contents will not be modified by the framework (or +the drivers used). Subsequent requests for processing that use the +SID returned will avoid the cost of re-initializing the hardware (in +essence, SID acts as an index in the session cache of the driver). +.Pp +.Fn crypto_freesession +is called with the SID returned by +.Fn crypto_newsession +to disestablish the session. +.Pp +.Fn crypto_dispatch +is called to process a request. The various fields in the +.Va cryptop +structure are: +.Bl -tag -width crp_alloctype +.It crp_sid +Contains the SID. +.It crp_ilen +Indicates the total length in bytes of the buffer to be processed. +.It 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 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 crp_callback +This routine is invoked upon completion of the request, whether +successful or not. If the request was not successful, an error code is +set in the +.Va crp_etype +field. +.It crp_etype +Contains the error type, if any errors were encountered, or zero if +the request was successfully processed. If the +.Va EAGAIN +error code is returned, the SID has changed (and has been recorded in +the +.Va crp_sid +field). The consumer should record the new SID and use it in all +subsequent requests. In this case, the request may be re-submitted +immediately. This mechanism is used by the framework to perform +session migration (move a session from one driver to another, because +of availability, performance, or other considerations). +.Pp +Note that this field only makes sense when examined by +the callback routine specified in +.Va crp_callback . +Errors are returned to the invoker of +.Fn crypto_process +only when enough information is not present to call the callback +routine (i.e., if the pointer passed is +.Dv NULL +or if no callback routine was specified). +.It crp_flags +Is a bitmask of flags associated with this request. Currently defined +flags are: +.Bl -tag -width CRYPTO_F_IMBUF +.It CRYPTO_F_IMBUF +The buffer pointed to by +.Va crp_buf +is an mbuf chain. +.El +.Br +.It crp_buf +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 +.Va crp_alloctype ), +depending on +.Va crp_flags . +.It crp_opaque1 +.It crp_opaque2 +.It crp_opaque3 +.It crp_opaque4 +These are passed through the crypto framework untouched and are +intended for the invoking application's use. +.It crp_desc +This is a linked list of descriptors. Each descriptor provides +information about what type of cryptographic operation should be done +on the input buffer. The various fields are: +.Bl -tag -width=crd_inject +.It crd_skip +The offset in the input buffer where processing should start. +.It crd_len +How many bytes, after +.Va crd_skip , +should be processed. +.It crd_inject +Offset from the beginning of the buffer to insert any results. For +encryption algorithms, this is where the initialization vector +(IV) will be inserted when encrypting or where it can be found when +decrypting (subject to +.Va crd_flags ). +For MAC algorithms, this is where the result of the keyed hash will be +inserted. +.It crd_flags +The following flags are defined: +.Bl -tag -width=CRD_F_IV_EXPLICIT +.it CRD_F_ENCRYPT +For encryption algorithms, this bit is set when encryption is required +(when not set, decryption is performed). +.It CRD_F_IV_PRESENT +For encryption algorithms, this bit is set when the IV already +precedes the data, so the +.Va crd_inject +value will be ignored and no IV will be written in the +buffer. Otherwise, the IV used to encrypt the packet will be written +at the location pointed to by +.Va crd_inject . +The IV length is assumed to be equal to the blocksize of the +encryption algorithm. Some applications that do special ``IV +cooking'', such as the half-IV mode in +.Xr ipsec 4 , +can use this flag to indicate the the IV should not be written on the +packet. This flag is typically used in conjunction with the +.Va CRD_F_IV_EXPLICIT +flag. +.It CRD_F_IV_EXPLICIT +For encryption algorithms, this bit is set when the IV is explicitly +provided by the consumer in the +.Va crd_iv +fiels. Otherwise, for encryption operations the IV is provided for by +the driver used to perform the operation, whereas for decryption +operations it is pointed to by the +.Va crd_inject +field. This flag is typically used when the IV is calculated ``on the +fly'' by the consumer, and does not precede the data (some +.Xr ipsec 4 +configurations, and the encrypted swap are two such examples). +.El +.It crd_alg +.It crd_klen +.It crd_rnd +.It crd_key +.It crd_iv +These have the exact same meaning as the corresponding fields in the +.Va cryptoini +structure. These fields will not be modified by the framework or the +device drivers. Since this information accompanies every cryptographic +operation request, drivers may re-initialize state on-demand +(typically an expensive operation). Furthermore, the cryptographic +framework may re-route requests as a result of full queues or hardware +failure, as described above. +.It crd_next +Point to the next descriptor. Linked operations are useful in +protocols such as +.Xr ipsec 4 , +where multiple cryptographic transforms may be applied on the same +block of data. +.El +.El +.Pp +.Fn crypto_getreq +allocates a +.Va cryptop +structure with a linked list of as many +.Va cryptodesc +structures as were specified in the argument passed to it. +.Pp +.Fn crypto_freereq +deallocates a structure +.Va cryptop +and any +.Va cryptodesc +structures linked to it. Note that it is the responsibility of the +callback routine to do the necessary cleanups associated with the +opaque fields in the +.Va cryptop +structure. +.Pp +.Sh DRIVER-SIDE API +The +.Fn crypto_get_driverid , +.Fn crypto_register , +and +.Fn crypto_unregister +routines are used by drivers that provide support for cryptographic +primitives to register and unregister with the kernel crypto services +framework. Drivers must first use the +.Fn crypto_get_driverid +function to acquire a driver identifier. For each algorithm the driver +supports, it must then call +.Fn crypto_register . +The first two arguments are the driver and algorithm identifiers. The +last three 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.) +.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 +crypto cards that are being ejected will invoke this routine for all +algorithms supported by the card. +.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 *); +.Ed +.Pp +On invocation, the first 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 +.Fn crypto_newsession . +.Pp +The +.Fn freesession +routine takes as argument 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.) +.Pp +The +.Fn process +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 +.Va crp_etype +field of the +.Va cryptop +structure, and the callback routine invoked as well, to perform the +necessary cleanup or to re-issue the request. Session migration may be +performed, as mentioned previously. +.Pp +.Sh RETURN VALUES +.Fn crypto_register , +.Fn crypto_unregister , +.Fn crypto_newsession , +and +.Fn crypto_freesession +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. +.Fn crypto_getreq +returns a pointer to a +.Va cryptop +structure and +.Dv NULL +on failure. +.Fn crypto_dispatch +returns +.Dv EINVAL +is its argument or the callback function was +.Dv NULL , +and 0 otherwise. The callback is provided with an error code in case +of failure, in the +.Va crp_etype +field. +.Br +.Sh CODE REFERENCES +Most of the framework code can be found in +.Pa sys/crypto/crypto.c +.Br +.Sh SEE ALSO +.Xr ipsec 4 , +.Xr malloc 9 , +.Xr pcmcia 4 , +.Xr tsleep 9 +.Br +.Sh BUGS +The framework currently assumes that all the algorithms in a +.Fn crypto_newsession +operation must be available by the same driver. If that's not the +case, session initialization will fail. +.Pp +The framework also needs a mechanism for determining which driver is +best for a specific set of algorithms associated with a session. Some +type of benchmarking is in order here. +.Pp +Multiple instances of the same algorithm in the same session are not +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 +We need a userland device for exposing the framework to userland. This +will be particularly useful for public key operations in hardware. +.Pp +We have not experimented yet with public key operations hardware. The +framework should support this. +.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). |