document the keying operations

1 files changed, 103 insertions, 27 deletions

diff --git a/share/man/man9/crypto.9 b/share/man/man9/crypto.9
index 9b88c0a6121..4c98a75d88d 100644
--- a/share/man/man9/crypto.9
+++ b/share/man/man9/crypto.9
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: crypto.9,v 1.15 2002/01/26 18:12:09 angelos Exp $
+.\"	$OpenBSD: crypto.9,v 1.16 2002/04/23 21:45:49 deraadt Exp $
 .\"
 .\" The author of this man page is Angelos D. Keromytis (angelos@cis.upenn.edu)
 .\"
@@ -28,15 +28,21 @@
 .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 *)"
 .Ft int
+.Fn crypto_kregister "u_int32_t" "int" "u_int32_t" "int (*)(struct cryptkop *)"
+.Ft int
 .Fn crypto_unregister "u_int32_t" "int"
 .Ft void
 .Fn crypto_done "struct cryptop *"
+.Ft void
+.Fn crypto_kdone "struct cryptkop *"
 .Ft int
 .Fn crypto_newsession "u_int64_t *" "struct cryptoini *" "int"
 .Ft int
 .Fn crypto_freesession "u_int64_t"
 .Ft int
 .Fn crypto_dispatch "struct cryptop *"
+.Ft int
+.Fn crypto_kdispatch "struct cryptkop *"
 .Ft struct cryptop *
 .Fn crypto_getreq "int"
 .Ft void
@@ -46,36 +52,57 @@
 #define EALG_MAX_BLOCK_LEN      16
 
 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;
+	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;
+	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_opaque;
-    struct cryptodesc *crp_desc;
-    int              (*crp_callback) (struct cryptop *);
-    struct cryptop    *crp_next;
-    caddr_t            crp_mac;
+	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;
+};
+
+struct crparam {
+        caddr_t         crp_p;
+        u_int           crp_nbits;
+};
+
+#define CRK_MAXPARAM    8
+
+struct cryptkop {
+        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;
+        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
@@ -96,6 +123,11 @@ 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
+Keying operations are supported as well.  Unlike the symmetric operators
+described above,
+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 .
@@ -114,6 +146,7 @@ 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.
+.br
 .Pp
 The
 .Fn crypto_newsession
@@ -122,7 +155,7 @@ routine is called by consumers of cryptographic services (such as the
 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 third argument indicates wether a
+the driver to establish the session.  The third argument indicates whether a
 hardware driver (1) should be used or not (0).  The various fields in the
 .Fa cryptoini
 structure are:
@@ -360,10 +393,35 @@ callback routine to do the necessary cleanups associated with the
 opaque field in the
 .Fa cryptop
 structure.
+.Pp
+.Fn crypto_kdispatch
+is called to perform a keying operation.  The various fields in the
+.Fa crytokop
+structure are:
+.Bl -tag -width crp_alloctype
+.It Fa krp_op
+Operation code, such as CRK_MOD_EXP.
+.It Fa krp_status
+Return code.  This errno-style variable indicates whether lower level reasons
+for operation failure.
+.It Fa krp_iparams
+Number if input parameters to the specified operation.
+Note that each operation has a (typically hardwired) number of such parameters. 
+.It Fa krp_oparams
+Number if output parameters from the specified operation.
+Note that each operation has a (typically hardwired) number of such parameters. 
+.It Fa krp_kvp
+An array of kernel memory blocks containing the parameters.
+.It Fa krp_hid
+Identifier specifying which low-level driver is being used.
+.It Fa krp_callback
+Callback called on completion of a keying operation. 
+.El
 .Sh DRIVER-SIDE API
 The
 .Fn crypto_get_driverid ,
 .Fn crypto_register ,
+.Fn crypto_kregister ,
 .Fn crypto_unregister ,
 and
 .Fn crypto_done
@@ -380,7 +438,7 @@ 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., wether an hardware RNG is
+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
 .Fn crypto_register
@@ -403,6 +461,7 @@ The calling convention for the three driver-supplied routines is:
 int (*newsession) (u_int32_t *, struct cryptoini *);
 int (*freesession) (u_int64_t);
 int (*process) (struct cryptop *);
+int (*kprocess) (struct cryptkop *);
 .Ed
 .Pp
 On invocation, the first argument to
@@ -437,8 +496,25 @@ When the request is completed, or an error is detected, the
 routine should invoked
 .Fn crypto_done .
 Session migration may be performed, as mentioned previously.
+.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
+.Fa krp_status
+field of the
+.Fa cryptkop
+structure.
+When the request is completed, or an error is detected, the
+.Fn kprocess
+routine should invoked
+.Fn crypto_kdone .
 .Sh RETURN VALUES
 .Fn crypto_register ,
+.Fn crypto_kregister ,
 .Fn crypto_unregister ,
 .Fn crypto_newsession ,
 and