pseudo-device crypto pseudo-device swcrypto
/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.
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
CIOCFKEY
(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.
CRIOGET
int
*fd
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(4)
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
void
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.
Algorithm Input parameter | Output parameter
| Count | Count
|
CRK_MOD_EXP |
See below for discussion of the input and output parameter counts.
CIOCASSYMFEAT
int
*feature_mask
CRK_MOD_EXP
is available if and only if the bit
(1 <<
CRK_MOD_EX
)
is set.
CIOCFKEY
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
CIOCFKEY,
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
*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:
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.
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.
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 NetBSD5.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.