NetBSD/share/man/man4/crypto.4

.\"	$NetBSD: crypto.4,v 1.23 2011/02/25 21:10:33 wiz 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>. 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 February 25, 2011
.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_256_HMAC
.It CRYPTO_SHA2_384_HMAC
.It CRYPTO_SHA2_512_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 */
};

struct session_n_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;
    u_int32_t mackeylen;	/* mac key */
    void * mackey;

    u_int32_t ses;		/* returns: session # */
    int status;
};

.Ed
Create one or more sessions.
Takes a counted array of
.Fa session_n_op
structures in
.Fa sgop .
For each requested session (array element n), the session number is returned in
.Fa sgop-\*[Gt]sessions[n].ses
and the status for that session creation in
.Fa sgop-\*[Gt]sessions[n].status .
.\"
.It Dv CIOCCRYPT Fa struct crypt_op *cr_op
.Bd -literal
struct crypt_op {
    u_int32_t ses;
    u_int16_t op;	/* e.g. COP_ENCRYPT */
    u_int16_t flags;
    u_int len;
    void * src, *dst;
    void * mac;		/* must be large enough for result */
    void * iv;
};

.Ed
Request a symmetric-key (or hash) operation.
The file descriptor argument to
.Xr ioctl 2
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 CIOCNCRYPTM Fa struct crypt_mop *cr_mop
.Bd -literal
struct crypt_mop {
    size_t count;		/* how many */
    struct crypt_n_op * reqs;	/* where to get them */
};

struct crypt_n_op {
    u_int32_t ses;
    u_int16_t op;		/* e.g. COP_ENCRYPT */
    u_int16_t flags;
    u_int len;

    u_int32_t reqid;		/* request id */
    int status;			/* accepted or not */

    void *opaque;		/* opaque pointer ret to user */
    u_int32_t keylen;		/* cipher key - optional */
    void * key;
    u_int32_t mackeylen;	/* mac key - optional */
    void * mackey;

    void * src, * dst;
    void * mac;
    void * iv;
};

.Ed
This is the asynchronous version of CIOCCRYPT, which allows multiple
symmetric-key (or hash) operations to be started (see CIOCRYPT
above for the details for each operation).
.Pp
The
.Fa cr_mop-\*[Gt]count
field specifies the number of operations provided in the
cr_mop-\*[Gt]reqs array.
.Pp
Each operation is assigned a unique request id returned in the
.Fa cr_mop-\*[Gt]reqs[n].reqid
field.
.Pp
Each operation can accept an opaque value from the user to be passed back
to the user when the operation completes
(e.g., to track context for the request).
The opaque field is
.Fa cr_mop-\*[Gt]reqs[n].opaque .
.Pp
If a problem occurs with starting any of the operations then that
operation's
.Fa cr_mop-\*[Gt]reqs[n].status
field is filled with the error code.
The failure of an operation does not
prevent the other operations from being started.
.Pp
The
.Xr select 2
or
.Xr poll 2
functions must be used on the device file descriptor to detect that
some operation has completed; results are then retrieved with
.Dv CIOCNCRYPTRETM .
.Pp
The
.Fa key
and
.Fa mackey
fields of the
operation structure are currently unused.
They are intended for use to
immediately rekey an existing session before processing a new request.
.It Dv CIOCFSESSION Fa void
Destroys the /dev/crypto session associated with the file-descriptor
argument.
.It Dv CIOCNFSESSION Fa struct crypt_sfop *sfop ;
.Bd -literal
struct crypt_sfop {
    size_t count;
    u_int32_t *sesid;
};

.Ed
Destroys the
.Fa sfop-\*[Gt]count
sessions specified by the
.Fa sfop
array of session identifiers.
.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:
.Pp
.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_MOD_ADD Ta 3 Ta 1
.It Dv CRK_MOD_ADDINV Ta 2 Ta 1
.It Dv CRK_MOD_SUB Ta 3 Ta 1
.It Dv CRK_MOD_MULT Ta 3 Ta 1
.It Dv CRK_MOD_MULTINV Ta 2 Ta 1
.It Dv CRK_MOD Ta 2 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 CIOCKEY
.It Dv CIOCASYMFEAT 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_EXP
is set.
.It Dv CIOCKEY Fa struct crypt_kop *kop
.Bd -literal
struct crypt_kop {
    u_int crk_op;		/* e.g. CRK_MOD_EXP */
    u_int crk_status;		/* return status */
    u_short crk_iparams;	/* # of input params */
    u_short crk_oparams;	/* # of output params */
    u_int crk_pad1;
    struct crparam crk_param[CRK_MAXPARAM];
};

/* Bignum parameter, in packed bytes. */
struct crparam {
    void * crp_p;
    u_int crp_nbits;
};

.Ed
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.
.Pp
The semantics of these arguments are currently undocumented.
.It Dv CIOCNFKEYM Fa struct crypt_mkop *mkop
.Bd -literal
struct crypt_mkop {
    size_t count;		/* how many */
    struct crypt_n_op * reqs;	/* where to get them */
};

struct crypt_n_kop {
    u_int crk_op;		/* e.g. CRK_MOD_EXP */
    u_int crk_status;		/* accepted or not */
    u_short crk_iparams;	/* # of input params */
    u_short crk_oparams;	/* # of output params */
    u_int32_t crk_reqid;	/* request id */
    struct crparam crk_param[CRK_MAXPARAM];
    void *crk_opaque;		/* opaque pointer ret to user */
};

.Ed
This is the asynchronous version of
.Dv CIOCKEY ,
which starts one or more key operations.
See
.Dv CIOCNCRYPTM
above and
.Dv CIOCNCRYPTRETM
below
for descriptions of the
.Fa mkop\*[Gt]count ,
.Fa mkop\*[Gt]reqs ,
.Fa mkop\*[Gt]reqs[n].crk_reqid ,
.Fa mkop\*[Gt]reqs[n].crk_status ,
and
.Fa  mkop\*[Gt]reqs[n].crk_opaque
fields of the argument structure, and result retrieval.
.El
.Ss Asynchronous status commands
When requests are submitted with the
.Dv CIOCNCRYPTM
or
.Dv CIOCNFKEYM
commands, result retrieval is asynchronous
(the submit ioctls return immediately).
Use the
.Xr select 2
or
.Xr poll 2
functions to determine when the file descriptor has completed operations ready
to be retrieved.
.Bl -tag -width CIOCKEY
.It Dv CIOCNCRYPTRET Fa struct crypt_result *cres
.Bd -literal
struct crypt_result {
    u_int32_t reqid;	/* request ID */
    u_int32_t status;	/* 0 if successful */
    void * opaque;	/* pointer from user */
};

.Ed
Check for the status of the request specified by
.Fa cres-\*[Gt]reqid .
This requires a linear search through all completed requests and should
be used with extreme care if the number of requests pending on this
file descriptor may be large.
.Pp
The
.Fa cres-\*[Gt]status
field is set as follows:
.Bl -tag -width EINPROGRESS
.It 0
The request has completed, and its results have been copied out to
the original
.Fa crypt_n_op or
.Fa crypt_n_kop
structure used to start the request.
The copyout occurs during this ioctl,
so the calling process must be the process that started the request.
.It EINPROGRESS
The request has not yet completed.
.It EINVAL
The request was not found.
.El
.Pp
Other values indicate a problem during the processing of the request.
.It Dv CIOCNCRYPTRETM Fa struct cryptret_t *cret
.Bd -literal
struct cryptret {
    size_t count;			/* space for how many */
    struct crypt_result * results;	/* where to put them */
};

.Ed
Retrieve a number of completed requests.
This ioctl accepts a count and
an array (each array element is a
.Fa crypt_result_t
structure as used by
.Dv CIOCNCRYPTRET
above) and fills the array with up to
.Fa cret-\*[Gt]count
results of completed requests.
.Pp
This ioctl fills in the
.Fa cret-\*[Gt]results[n].reqid field ,
so that the request which has completed
may be identified by the application.
Note that the results may include
requests submitted both as symmetric and asymmetric operations.
.El
.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 .
.Pp
The "new API" for asynchronous operation with multiple basic operations
per system call (the "N" ioctl variants) was contributed by Coyote Point
Systems, Inc. and first appeared in
.Nx 5.0 .
.Sh BUGS
Error checking and reporting is weak.
.Pp
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.