[src/uebayasi-xip]: src/share/man/man4 Document also kern.cryptodevallowsoft.

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

details:   https://anonhg.NetBSD.org/src/rev/61c5e145fcae
branches:  uebayasi-xip
changeset: 751668:61c5e145fcae
user:      jruoho <jruoho%NetBSD.org@localhost>
date:      Tue Apr 20 08:37:23 2010 +0000

description:
Document also kern.cryptodevallowsoft.

diffstat:

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

diffs (truncated from 665 to 300 lines):

diff -r d6de1b8bc9ec -r 61c5e145fcae share/man/man4/crypto.4
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man4/crypto.4   Tue Apr 20 08:37:23 2010 +0000
@@ -0,0 +1,661 @@
+.\"    $NetBSD: crypto.4,v 1.21.2.2 2010/04/20 08:37:23 jruoho Exp $
+.\"
+.\" Copyright (c) 2008 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Coyote Point Systems, Inc.
+.\"
+.\" 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 THE NETBSD FOUNDATION, INC. 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 THE FOUNDATION OR CONTRIBUTORS
+.\" 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.
+.\"
+.\"
+.\"
+.\" 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 20, 2010
+.Dt CRYPTO 4
+.Os
+.Sh NAME
+.Nm crypto ,
+.Nm swcrypto
+.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
+.Cd pseudo-device swcrypto
+.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.
+.Pp
+The
+.Cm swcrypto
+driver is a software-only implementation of the
+.Xr opencrypto 9
+interface, and must be included to use the interface without hardware
+acceleration.
+.Pp
+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.
+User-mode access to
+.Pa /dev/crypto
+is generally controlled by three
+.Xr sysctl 8
+variables,
+.Ic kern.usercrypto ,
+.Ic kern.userasymcrypto ,
+and
+.Ic kern.cryptodevallowsoft .
+See
+.Xr sysctl 7
+for additional details.
+.Pp
+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 arithmetic (for Diffie-Hellman key exchange and other
+cryptographic protocols).
+The two modes are described separately below.
+.Sh THEORY OF OPERATION
+Regardless of whether symmetric-key or asymmetric-key operations are
+to be performed, use of the device requires a basic series of steps:
+.Pp
+.Bl -enum
+.It
+Open a file descriptor for the device.
+See
+.Xr open 2 .
+.It
+If any symmetric operation will be performed,
+create one session, with
+.Dv CIOCGSESSION ,
+or multiple sessions, with
+.Dv CIOCNGSESSION .
+Most applications will require at least one symmetric session.
+Since cipher and MAC keys are tied to sessions, many
+applications will require more.
+Asymmetric operations do not use sessions.
+.It
+Submit requests, synchronously with
+.Dv CIOCCRYPT
+(symmetric)
+or
+.Dv CIOCKEY
+(asymmetric)
+or asynchronously with
+.Dv CIOCNCRYPTM
+(symmetric)
+or
+.Dv CIOCNFKEYM
+(asymmetric).
+The asynchronous interface allows multiple requests to be submitted in one
+call if the user so desires.
+.It
+If the asynchronous interface is used, wait for results with
+.Xr select 2
+or
+.Xr poll 2 ,
+then collect them with
+.Dv CIOCNCRYPTRET
+(a particular request)
+or
+.Dv CIOCNCRYPTRETM
+(multiple requests).
+.It
+Destroy one session with
+.Dv CIOCFSESSION
+or many at once with
+.Dv CIOCNFSESSION .
+.It
+Close the device with
+.Xr close 2 .
+.El
+.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:
+.Pp
+.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:
+.Pp
+.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
+.Pp
+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 CIOCKEY
+.\"
+.It Dv CRIOGET Fa int *fd
+This operation is deprecated and will be removed after
+.Nx 5.0 .
+It clones the fd argument to
+.Xr ioctl 2 ,
+yielding a new file descriptor for the creation of sessions.
+Because the device now clones on open, this operation is unnecessary.
+.\"
+.It Dv CIOCGSESSION Fa struct session_op *sessp
+.Bd -literal
+struct session_op {
+    u_int32_t cipher;  /* e.g. CRYPTO_DES_CBC */
+    u_int32_t mac;     /* e.g. CRYPTO_MD5_HMAC */
+
+    u_int32_t keylen;  /* cipher key */
+    void * key;
+    int mackeylen;     /* mac key */
+    void * mackey;
+
+    u_int32_t ses;     /* returns: ses # */
+};
+
+.Ed
+Create a new cryptographic session on a file descriptor for the device;
+that is, a persistent object specific 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
+Multiple sessions may be bound to a single file descriptor.
+The session ID returned in
+.Fa sessp-\*[Gt]ses
+is supplied as a required field in the symmetric-operation structure
+.Fa crypt_op
+for future encryption or hashing requests.
+.Pp
+This implementation will never return a session ID of 0 for a successful
+creation of a session, which is a
+.Nx
+extension.
+.Pp
+For non-zero symmetric-key privacy algorithms, the privacy algorithm
+must be specified in
+.Fa sessp-\*[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 CIOCNGSESSION Fa struct crypt_sgop *sgop
+.Bd -literal
+struct crypt_sgop {
+    size_t     count;                  /* how many */
+    struct session_n_op * sessions; /* where to get them */
+};