[src/trunk]: src/share/man/man4 Commit first draft of a manpage for crypto(4)...

[jonathan <jonathan%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/7480f55258cc
branches:  trunk
changeset: 566113:7480f55258cc
user:      jonathan <jonathan%NetBSD.org@localhost>
date:      Tue Apr 27 21:34:10 2004 +0000

description:
Commit first draft of a manpage for crypto(4), the user-mode API
to opencrypto(9).

diffstat:

 share/man/man4/Makefile |    5 +-
 share/man/man4/crypto.4 |  253 ++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 256 insertions(+), 2 deletions(-)

diffs (276 lines):

diff -r c4814d1557d9 -r 7480f55258cc share/man/man4/Makefile
--- a/share/man/man4/Makefile   Tue Apr 27 20:59:43 2004 +0000
+++ b/share/man/man4/Makefile   Tue Apr 27 21:34:10 2004 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile,v 1.316 2004/04/27 01:48:27 jonathan Exp $
+#      $NetBSD: Makefile,v 1.317 2004/04/27 21:34:10 jonathan Exp $
 #      @(#)Makefile    8.1 (Berkeley) 6/18/93
 
 MAN=   aac.4 acardide.4 aceride.4 acphy.4 adc.4 adv.4 \
@@ -9,7 +9,8 @@
        brgphy.4 bridge.4 cac.4 cardbus.4 ccd.4 cd.4 \
        cec.4 cgd.4 cfb.4 ch.4 clcs.4 clct.4 clnp.4 \
        clockctl.4 cltp.4 cmdide.4 cmpci.4 cms.4 cnw.4 \
-       com.4 cs80bus.4 cypide.4 ddb.4 dge.4 de.4 dmoverio.4 \
+       com.4 crypto.4 cs80bus.4 cypide.4 \
+       ddb.4 dge.4 de.4 dmoverio.4 \
        dmphy.4 dpt.4 dpti.4 drum.4 eap.4 ebus.4 edc.4 \
        elmc.4 emuxki.4 en.4 envsys.4 ep.4 esh.4 esis.4 \
        esa.4 esiop.4 esl.4 esm.4 eso.4 exphy.4 fast_ipsec.4 fd.4 \
diff -r c4814d1557d9 -r 7480f55258cc share/man/man4/crypto.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/crypto.4   Tue Apr 27 21:34:10 2004 +0000
@@ -0,0 +1,253 @@
+.\"    $NetBSD: crypto.4,v 1.1 2004/04/27 21:34:10 jonathan Exp $
+.\"
+.\" Copyright (c) 2004
+.\"    Jonathan Stone <jonathan%dsg.stanford.edu@localhost>. All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY Jonathan Stone AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL Jonathan Stone OR THE VOICES IN HIS HEAD
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF
+.\" THE POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd April 25 23, 2004
+.Dt CRYPTO 4
+.Os
+.Sh NAME
+.Nm "crypto"
+.Nd user-mode access to hardware-accelerated cryptography
+.Sh SYNOPSIS
+.Cd  "hifn*   at pci? dev ? function ?"
+.Cd  "ubsec*  at pci? dev ? function ?"
+.Pp
+.Cd "pseudo-device crypto"
+.Pp
+.In sys/ioctl.h
+.In cryptodev.h
+.Sh DESCRIPTION
+The
+.Nm
+driver gives user-mode applications access to hardware-accelerated
+cryptographic transforms, as implemented by the 
+.Xr opencrypto 9
+in-kernel interface.
+The
+.Pa /dev/crypto
+special device provides an 
+.Xr ioctl 2
+based interface. User-mode applications should open the special device,
+then issue 
+.Xr ioctl 2 
+calls on the descriptor. The 
+.Nm
+device provides two distinct modes of operation: one mode for
+symmetric-keyed cryptographic requests, and a second mode for
+both asymmetric-key (public-key/private-key) requests, and for
+modular exponentiation (for Diffie-Hellman key exchange).
+The two modes are described separately below.
+.Sh SYMMETRIC-KEY OPERATION
+The symmetric-key operation mode provides a context-based API
+to traditional symmetric-key encryption (or privacy) algorithms,
+or to keyed and unkeyed one-way hash (HMAC and MAC) algorithms.
+The symmetric-key mode also permits fused operation,
+where the hardware performs both a privacy algorithm and an integrity-check
+algorithm in a single pass over the data: either a fudised
+encrypt/HMAC-generate operation, or a fused HMAC-verify/decrypt operation.
+.Pp
+To use symmetric mode, you must first create a session specifying
+the algorithm(s) and key(s) to use; then issue encrypt or decrypt
+requests against the session. 
+.Ss Symmetric-key privacy algorithms
+Contingent upon device drivers for installed cryptographic hardware
+registering with
+.Xr opencrypto 9 ,
+as providers of a given algorithm, some or all of the following
+symmetric-key privacy algorithms may be available:
+.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent
+.It CRYPTO_DES_CBC
+.It CRYPTO_3DES_CBC
+.It CRYPTO_BLF_CBC
+.It CRYPTO_CAST_CBC
+.It CRYPTO_SKIPJACK_CBC
+.It CRYPTO_AES_CBC
+.It CRYPTO_ARC4
+.El
+.Pp
+.Ss Integrity-check operations
+Contingent upon hardware support, some or all of the following
+keyed one-way hash algorithms may be available:
+.Bl -tag -compact -width CRYPTO_RIPEMD160_HMAC -offset indent
+.It CRYPTO_RIPEMD160_HMAC
+.It CRYPTO_MD5_KPDK
+.It CRYPTO_SHA1_KPDK
+.It CRYPTO_MD5_HMAC
+.It CRYPTO_SHA1_HMAC
+.It CRYPTO_SHA2_HMAC
+.It CRYPTO_MD5
+.It CRYPTO_SHA1
+.El
+The 
+.Em CRYPTO_MD5
+and
+.Em CRYPTO_SHA1
+algorithms are actually unkeyed, but should be requested
+as symmetric-key hash algorithms with a zero-length key.
+.Ss IOCTL Request Descriptions
+.\"
+.Bl -tag -width CIOCFKEY
+.\"
+.It Dv CRIOCGET Fa int *fd
+Clone the fd argument to 
+.Xr ioctl 4 ,
+yielding a new file descriptor which can be used to create
+crypto sessions and request crypto operations.
+.\"
+.It Dv CRIOCGSESSION Fa struct session_op *sessp
+Persistently bind a file descriptor returned by a previous 
+.Dv CRIOCGET 
+to a session: that is, to the chosen privacy algorithm, integrity
+algorithm, and keys specified in 
+.Fa sessp .
+The special value 0 for either privacy or integrity 
+is reserved to indicate that the indicated operation (privacy or integrity) 
+is not desired for this session. 
+.Pp
+For non-zero symmetric-key privacy algorithms, the privacy algorithm 
+must be specified in
+.Fa sess->cipher ,
+the key length in
+.Fa sessp->keylen ,
+and the key value in the octets addressed by 
+.Fa sessp->key .
+.Pp
+For keyed one-way hash algorithms, the one-way hash must be specified
+in
+.Fa sessp->mac ,
+the key length in
+.Fa sessp->mackey ,
+and the key value in the octets addressed by 
+.Fa sessp->mackeylen .
+.\"
+.Pp
+Support for a specific combination of fused privacy  and
+integrity-check algorithms depends on whether the underlying
+hardware supports that combination. Not all combinations are supported
+by all hardware, even if the hardware supports each operation as a 
+stand-alone non-fused operation.
+.It Dv CIOCCRYPT Fa struct crpyto_op *cr_op
+Request a symmetric-key (or unkeyed hash) operation. 
+The file descriptor argument to
+.Xr ioctl 4 
+must have been bound to a valid session.
+To encrypt, set
+.Fa cr_op->op
+to COP_ENCRYPT. To decrypt, set
+.Fa cr_op->op
+to COP_DECRYPT.
+The field
+.Fa cr_op->len 
+supplies the length of the input buffer; the fields
+.Fa cr_op->src ,
+.Fa cr_op->dst ,
+.Fa cr_op->mac ,
+.Fa cr_op->iv 
+supply the addresses of the input buffer, output buffer, 
+one-way hash, and initialization vector, respectively.
+.It Dv CIOCFSESSION Fa void
+Destroys the /dev/crypto session associated with the file-descriptor
+argument.
+.El
+.\"
+.\"
+.\"
+.Sh ASYMMETRIC-KEY OPERATION
+.Pp
+.Ss Asymmetric-key algorithms
+Contingent upon hardware support, the following asymmetric
+(public-key/private-key; or key-exchange subroutine) operations may
+also be available:
+.Bl -column "CRK_DH_COMPUTE_KEY" "Input parameter" "Output parameter" -offset indent -compact
+.It Em "Algorithm" Ta "Input parameter" Ta "Output parameter"
+.It Em " " Ta "Count" Ta "Count"
+.It Dv CRK_MOD_EXP Ta 3 Ta 1
+.It Dv CRK_MOD_EXP_CRT Ta 6 Ta 1
+.It Dv CRK_DSA_SIGN Ta 5 Ta 2
+.It Dv CRK_DSA_VERIFY Ta 7 Ta 0
+.It Dv CRK_DH_COMPUTE_KEY Ta 3 Ta 1
+.El
+.Pp
+See below for discussion of the input and output parameter counts.
+.Ss Asymmetric-key commands
+.Bl -tag -width CIOCFKEY
+.\"
+.It Dv CIOCASSYMFEAT Fa int *feature_mask
+Returns a bitmask of supported asymmetric-key operations.
+Each of the above-listed asymmetric operations is present
+if and only the bit position numbered by the code for that operation
+is set.
+For example, 
+.Dv CRK_MOD_EXP
+is available if and only if the bit
+.Dv (1 << CRK_MOD_EX)
+is set.
+.It Dv CIOCFKEY Fa struct crypt_kop *kop
+Performs an asymmetric-key operation from the list above.
+ The specific operation is supplied in 
+.Fa kop->crk_op ;
+final status for the operation is returned in
+.Fa kop->crk_status .
+The number of input arguments and the number of output arguments
+is specified in 
+.Fa kop->crk_iparams
+and
+.Fa kop->crk_iparams ,
+respectively. The field
+.Fa crk_param[]
+must be filled in with exactly
+.Fa kop->crk_iparams + kop->crk_oparams
+arguments, each encoded as a
+.Fa struct crparam
+(address, bitlength) pair.
+.El
+.Pp
+The semantics of these arguments is currently undocumented.
+.\"
+.Sh SEE ALSO
+.Xr hifn 4 ,
+.Xr ubsec 4 , 
+.Xr opencrypto 9 .
+.Sh BUGS
+.Pp
+Error checking and reporting is weak. The values specified for
+symmetric-key key sizes to
+.Dv CRIOCGSESSION ,
+must exactly match the values expected by
+.XR opencrypto 9 .
+The output buffer and MAC buffers supplied to 
+.Dv CRIOCRYPT
+must follow whether privacy or integrity algorithms were specified for
+session: if you request a non-NULL algorithm, you must supply a suitably-sized
+buffer.
+.Pp
+The scheme for passing arguments for asymmetric requests is Baroque.
+.Sh HISTORY
+The
+.Nm
+driver is derived from a version which appeared
+.Fx 4.8 ,
+which in turn is based on code which appeared in
+.Ox 3.2 .