270 lines
8.6 KiB
Groff
270 lines
8.6 KiB
Groff
.\" $NetBSD: crypto.4,v 1.10 2006/09/23 20:38:51 elad Exp $
|
|
.\"
|
|
.\" Copyright (c) 2004
|
|
.\" Jonathan Stone <jonathan@dsg.stanford.edu>. 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 September 23, 2006
|
|
.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.
|
|
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.
|
|
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 CRIOGET 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 CIOCGSESSION Fa struct session_op *sessp
|
|
Persistently bind a file descriptor returned by a previous
|
|
.Dv CRIOGET
|
|
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 crypt_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 CIOCGSESSION
|
|
must exactly match the values expected by
|
|
.Xr opencrypto 9 .
|
|
The output buffer and MAC buffers supplied to
|
|
.Dv CIOCCRYPT
|
|
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.
|
|
.Pp
|
|
The naming inconsistency between
|
|
.Dv CRIOGET
|
|
and the various
|
|
.Dv CIOC Ns \&*
|
|
names is an unfortunate historical artifact.
|