man page for the kernel crypto framework, more or less complete

(hopefully accurate too).

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).