CRYPTO(4) | Device Drivers Manual | CRYPTO(4) |
crypto
, swcrypto
—
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>
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.
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.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.CIOCNCRYPTRET
(a particular request) or
CIOCNCRYPTRETM
(multiple requests).CIOCFSESSION
or many at
once with CIOCNFSESSION
.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.
The CRYPTO_MD5 and CRYPTO_SHA1 algorithms are actually unkeyed, but should be requested as symmetric-key hash algorithms with a zero-length key.
CRIOGET
int *fdCIOCGSESSION
struct session_op *sesspstruct 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 # */ };
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 *sgopstruct 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; };
CIOCCRYPT
struct crypt_op *cr_opstruct 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; };
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_mopstruct 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; };
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_idCIOCNFSESSION
struct crypt_sfop *sfopstruct crypt_sfop { size_t count; u_int32_t *sesid; };
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.
CIOCASYMFEAT
int *feature_maskCRK_MOD_EXP
is available if and only if the bit (1
<< CRK_MOD_EXP
) is set.CIOCKEY
struct crypt_kop *kopstruct 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; };
The semantics of these arguments are currently undocumented.
CIOCNFKEYM
struct crypt_mkop *mkopstruct 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 */ };
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.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 *cresstruct crypt_result { u_int32_t reqid; /* request ID */ u_int32_t status; /* 0 if successful */ void * opaque; /* pointer from user */ };
The cres->status field is set as follows:
Other values indicate a problem during the processing of the request.
CIOCNCRYPTRETM
struct cryptret_t *cretstruct cryptret { size_t count; /* space for how many */ struct crypt_result * results; /* where to put them */ };
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.
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.
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.
January 27, 2014 | NetBSD 9.4 |