NAME
crypto,
swcrypto —
user-mode access to hardware-accelerated cryptography
SYNOPSIS
hifn* at pci? dev ? function ?
ubsec* at pci? dev ? function ?
pseudo-device crypto
pseudo-device swcrypto
#include <sys/ioctl.h>
#include <sys/time.h>
#include <crypto/cryptodev.h>
DESCRIPTION
The
crypto driver gives user-mode applications access to
hardware-accelerated cryptographic transforms, as implemented by the
opencrypto(9) in-kernel
interface.
The
swcrypto driver is a software-only implementation of the
opencrypto(9) interface, and
must be included to use the interface without hardware acceleration.
The
/dev/crypto special device provides an
ioctl(2) based interface.
User-mode applications should open the special device, then issue
ioctl(2) calls on the descriptor.
User-mode access to
/dev/crypto is generally controlled by
three
sysctl(8) variables,
kern.usercrypto,
kern.userasymcrypto, and
kern.cryptodevallowsoft. See
sysctl(7) for additional
details.
The
crypto 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.
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:
- Open a file descriptor for the device. See
open(2).
- If any symmetric operation will be performed, create one
session, with
CIOCGSESSION
, or multiple sessions,
with 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.
- Submit requests, synchronously with
CIOCCRYPT
(symmetric) or
CIOCKEY
(asymmetric) or asynchronously with
CIOCNCRYPTM
(symmetric) or
CIOCNFKEYM
(asymmetric). The asynchronous
interface allows multiple requests to be submitted in one call if the user
so desires.
- If the asynchronous interface is used, wait for results
with select(2) or
poll(2), then collect them
with
CIOCNCRYPTRET
(a particular request) or
CIOCNCRYPTRETM
(multiple requests).
- Destroy one session with
CIOCFSESSION
or many at once with
CIOCNFSESSION
.
- Close the device with
close(2).
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.
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.
Symmetric-key privacy
algorithms
Contingent upon device drivers for installed cryptographic hardware registering
with
opencrypto(9), as
providers of a given algorithm, some or all of the following symmetric-key
privacy algorithms may be available:
- CRYPTO_DES_CBC
-
- CRYPTO_3DES_CBC
-
- CRYPTO_BLF_CBC
-
- CRYPTO_CAST_CBC
-
- CRYPTO_SKIPJACK_CBC
-
- CRYPTO_AES_CBC
-
- CRYPTO_ARC4
-
Integrity-check operations
Contingent upon hardware support, some or all of the following keyed one-way
hash algorithms may be available:
- CRYPTO_RIPEMD160_HMAC
-
- CRYPTO_MD5_KPDK
-
- CRYPTO_SHA1_KPDK
-
- CRYPTO_MD5_HMAC
-
- CRYPTO_SHA1_HMAC
-
- CRYPTO_SHA2_256_HMAC
-
- CRYPTO_SHA2_384_HMAC
-
- CRYPTO_SHA2_512_HMAC
-
- CRYPTO_MD5
-
- CRYPTO_SHA1
-
The
CRYPTO_MD5 and
CRYPTO_SHA1 algorithms
are actually unkeyed, but should be requested as symmetric-key hash algorithms
with a zero-length key.
IOCTL Request Descriptions
-
-
CRIOGET
int *fd
- This operation is deprecated and will be removed after
NetBSD 5.0. It clones the fd argument to
ioctl(2), yielding a new file
descriptor for the creation of sessions. Because the device now clones on
open, this operation is unnecessary.
-
-
CIOCGSESSION
struct session_op *sessp
-
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 # */
};
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 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.
Multiple sessions may be bound to a single file descriptor. The session ID
returned in sessp->ses is supplied as a required
field in the symmetric-operation structure crypt_op
for future encryption or hashing requests.
This implementation will never return a session ID of 0 for a successful
creation of a session, which is a NetBSD
extension.
For non-zero symmetric-key privacy algorithms, the privacy algorithm must be
specified in sessp->cipher, the key length in
sessp->keylen, and the key value in the octets
addressed by sessp->key.
For keyed one-way hash algorithms, the one-way hash must be specified in
sessp->mac, the key length in
sessp->mackey, and the key value in the octets
addressed by sessp->mackeylen.
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.
-
-
CIOCNGSESSION
struct crypt_sgop *sgop
-
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;
};
Create one or more sessions. Takes a counted array of
session_n_op structures in
sgop. For each requested session (array element n),
the session number is returned in
sgop->sessions[n].ses and the status for that
session creation in
sgop->sessions[n].status.
-
-
CIOCCRYPT
struct crypt_op *cr_op
-
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;
};
Request a symmetric-key (or hash) operation. The file descriptor argument to
ioctl(2) must have been bound
to a valid session. To encrypt, set cr_op->op to
COP_ENCRYPT
. To decrypt, set
cr_op->op to COP_DECRYPT
.
The field cr_op->len supplies the length of the
input buffer; the fields cr_op->src,
cr_op->dst, cr_op->mac,
cr_op->iv supply the addresses of the input
buffer, output buffer, one-way hash, and initialization vector,
respectively.
-
-
CIOCNCRYPTM
struct crypt_mop *cr_mop
-
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;
};
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).
The cr_mop->count field specifies the number of
operations provided in the cr_mop->reqs array.
Each operation is assigned a unique request id returned in the
cr_mop->reqs[n].reqid field.
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
cr_mop->reqs[n].opaque.
If a problem occurs with starting any of the operations then that
operation's cr_mop->reqs[n].status field is
filled with the error code. The failure of an operation does not prevent
the other operations from being started.
The select(2) or
poll(2) functions must be used
on the device file descriptor to detect that some operation has completed;
results are then retrieved with CIOCNCRYPTRETM
.
The key and 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.
-
-
CIOCFSESSION
u_int32_t *ses_id
- Destroys the /dev/crypto session associated with the
file-descriptor argument.
-
-
CIOCNFSESSION
struct crypt_sfop *sfop
-
struct crypt_sfop {
size_t count;
u_int32_t *sesid;
};
Destroys the sfop->count sessions specified by the
sfop array of session identifiers.
ASYMMETRIC-KEY OPERATION
Asymmetric-key algorithms
Contingent upon hardware support, the following asymmetric
(public-key/private-key; or key-exchange subroutine) operations may also be
available:
Algorithm |
Input parameter |
Output parameter |
|
Count |
Count |
CRK_MOD_EXP |
3 |
1 |
CRK_MOD_EXP_CRT |
6 |
1 |
CRK_MOD_ADD |
3 |
1 |
CRK_MOD_ADDINV |
2 |
1 |
CRK_MOD_SUB |
3 |
1 |
CRK_MOD_MULT |
3 |
1 |
CRK_MOD_MULTINV |
2 |
1 |
CRK_MOD |
2 |
1 |
CRK_DSA_SIGN |
5 |
2 |
CRK_DSA_VERIFY |
7 |
0 |
CRK_DH_COMPUTE_KEY |
3 |
1 |
See below for discussion of the input and output parameter counts.
Asymmetric-key commands
-
-
CIOCASYMFEAT
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,
CRK_MOD_EXP
is available if and only if
the bit (1 << CRK_MOD_EXP
) is set.
-
-
CIOCKEY
struct crypt_kop *kop
-
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;
};
Performs an asymmetric-key operation from the list above. The specific
operation is supplied in kop->crk_op; final
status for the operation is returned in
kop->crk_status. The number of input arguments
and the number of output arguments is specified in
kop->crk_iparams and
kop->crk_iparams, respectively. The field
crk_param[] must be filled in with exactly
kop->crk_iparams + kop->crk_oparams arguments,
each encoded as a struct crparam (address,
bitlength) pair.
The semantics of these arguments are currently undocumented.
-
-
CIOCNFKEYM
struct crypt_mkop *mkop
-
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 */
};
This is the asynchronous version of CIOCKEY
, which
starts one or more key operations. See CIOCNCRYPTM
above and CIOCNCRYPTRETM
below for descriptions of
the mkop>count,
mkop>reqs,
mkop>reqs[n].crk_reqid,
mkop>reqs[n].crk_status, and
mkop>reqs[n].crk_opaque fields of the argument
structure, and result retrieval.
Asynchronous status
commands
When requests are submitted with the
CIOCNCRYPTM
or
CIOCNFKEYM
commands, result retrieval is asynchronous
(the submit ioctls return immediately). Use the
select(2) or
poll(2) functions to determine
when the file descriptor has completed operations ready to be retrieved.
-
-
CIOCNCRYPTRET
struct crypt_result *cres
-
struct crypt_result {
u_int32_t reqid; /* request ID */
u_int32_t status; /* 0 if successful */
void * opaque; /* pointer from user */
};
Check for the status of the request specified by
cres->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.
The cres->status field is set as follows:
-
-
- 0
- The request has completed, and its results have been
copied out to the original crypt_n_op or
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.
-
-
- EINPROGRESS
- The request has not yet completed.
-
-
- EINVAL
- The request was not found.
Other values indicate a problem during the processing of the request.
-
-
CIOCNCRYPTRETM
struct cryptret_t *cret
-
struct cryptret {
size_t count; /* space for how many */
struct crypt_result * results; /* where to put them */
};
Retrieve a number of completed requests. This ioctl accepts a count and an
array (each array element is a crypt_result_t
structure as used by CIOCNCRYPTRET
above) and
fills the array with up to cret->count results of
completed requests.
This ioctl fills in the cret->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.
SEE ALSO
hifn(4),
ubsec(4),
opencrypto(9)
HISTORY
The
crypto driver is derived from a version which appeared in
FreeBSD 4.8, which in turn is based on code which
appeared in
OpenBSD 3.2.
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
NetBSD
5.0.
BUGS
Error checking and reporting is weak.
The values specified for symmetric-key key sizes to
CIOCGSESSION
must exactly match the values expected by
opencrypto(9). The output
buffer and MAC buffers supplied to
CIOCCRYPT
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.
The scheme for passing arguments for asymmetric requests is baroque.
The naming inconsistency between
CRIOGET
and the various
CIOC
* names is an unfortunate historical
artifact.