[src/netbsd-2-0]: src/share/man/man4 Pullup rev 0-1.5 (requested by jonathan ...

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

details:   https://anonhg.NetBSD.org/src/rev/985f5637dcf8
branches:  netbsd-2-0
changeset: 560739:985f5637dcf8
user:      jmc <jmc%NetBSD.org@localhost>
date:      Thu May 06 05:02:55 2004 +0000

description:
Pullup rev 0-1.5 (requested by jonathan in ticket #237)

Add manpages for crypto(4),and for the hifn(4) and ubsec(4) hardware crypto accelerators.

diffstat:

 share/man/man4/crypto.4 |  255 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 255 insertions(+), 0 deletions(-)

diffs (259 lines):

diff -r 745cf307868b -r 985f5637dcf8 share/man/man4/crypto.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/crypto.4   Thu May 06 05:02:55 2004 +0000
@@ -0,0 +1,255 @@
+.\"    $NetBSD: crypto.4,v 1.5.2.2 2004/05/06 05:02:55 jmc 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 27, 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 sys/time.h
+.In crypto/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 fused
+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
+.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-\*[Gt]cipher ,
+the key length in
+.Fa sessp-\*[Gt]keylen ,
+and the key value in the octets addressed by
+.Fa sessp-\*[Gt]key .
+.Pp
+For keyed one-way hash algorithms, the one-way hash must be specified
+in
+.Fa sessp-\*[Gt]mac ,
+the key length in
+.Fa sessp-\*[Gt]mackey ,
+and the key value in the octets addressed by
+.Fa sessp-\*[Gt]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-\*[Gt]op
+to
+.Dv COP_ENCRYPT .
+To decrypt, set
+.Fa cr_op-\*[Gt]op
+to
+.Dv COP_DECRYPT .
+The field
+.Fa cr_op-\*[Gt]len
+supplies the length of the input buffer; the fields
+.Fa cr_op-\*[Gt]src ,
+.Fa cr_op-\*[Gt]dst ,
+.Fa cr_op-\*[Gt]mac ,
+.Fa cr_op-\*[Gt]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
+.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 if 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
+.Pq 1 \*[Lt]\*[Lt] Dv 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-\*[Gt]crk_op ;
+final status for the operation is returned in
+.Fa kop-\*[Gt]crk_status .
+The number of input arguments and the number of output arguments
+is specified in
+.Fa kop-\*[Gt]crk_iparams
+and
+.Fa kop-\*[Gt]crk_iparams ,
+respectively.
+The field
+.Fa crk_param[]
+must be filled in with exactly
+.Fa kop-\*[Gt]crk_iparams + kop-\*[Gt]crk_oparams
+arguments, each encoded as a
+.Fa struct crparam
+(address, bitlength) pair.
+.El
+.Pp
+The semantics of these arguments are currently undocumented.
+.Sh SEE ALSO
+.Xr hifn 4 ,
+.Xr ubsec 4 ,
+.Xr opencrypto 9
+.Sh HISTORY
+The
+.Nm
+driver is derived from a version which appeared in
+.Fx 4.8 ,
+which in turn is based on code which appeared in
+.Ox 3.2 .
+.Sh BUGS
+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
+.No non- Ns Dv NULL
+algorithm, you must supply a suitably-sized buffer.
+.Pp
+The scheme for passing arguments for asymmetric requests is Baroque.