CRYPTO(4) | Device Drivers Manual | CRYPTO(4) |
crypto
, cryptodev
— user-mode access to hardware-accelerated
cryptography
device crypto
device cryptodev
#include <sys/ioctl.h>
#include <sys/time.h>
#include
<crypto/cryptodev.h>
The crypto
driver gives user-mode
applications access to hardware-accelerated cryptographic transforms, as
implemented by the crypto(9) in-kernel interface.
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
controlled by three sysctl(8) variables,
kern.userasymcrypto
and
kern.cryptodevallowsoft
.
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.
Regardless of whether symmetric-key or asymmetric-key operations are to be performed, use of the device requires a basic series of steps:
CIOCGSESSION
. 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), CIOCCRYPTAEAD
(symmetric), or
CIOCKEY
(asymmetric).CIOCFSESSION
.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.
For a list of supported algorithms, see crypto(7) and crypto(9).
CRIOGET
int *fdCIOCFINDDEV
struct crypt_find_op *fopstruct crypt_find_op { int crid; /* driver id + flags */ char name[32]; /* device/driver name */ };
ENOENT
is returned.CIOCGSESSION
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.
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.
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; caddr_t src, dst; caddr_t mac; /* must be large enough for result */ caddr_t 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. If a session is using both a privacy algorithm and a hash
algorithm, the request will generate a hash of the input buffer before
generating the output buffer by default. If the
COP_F_CIPHER_FIRST
flag is included in the
cr_op->flags field, then the request will
generate a hash of the output buffer after executing the privacy
algorithm.CIOCCRYPTAEAD
struct crypt_aead *cr_aeadstruct crypt_aead { u_int32_t ses; u_int16_t op; /* e.g. COP_ENCRYPT */ u_int16_t flags; u_int len; u_int aadlen; u_int ivlen; caddr_t src, dst; caddr_t aad; caddr_t tag; /* must be large enough for result */ caddr_t iv; };
CIOCCRYPTAEAD
is similar to the
CIOCCRYPT
but provides additional data in
cr_aead->aad to include in the authentication
mode.CIOCFSESSION
u_int32_t ses_idCIOCNFSESSION
struct crypt_sfop *sfop;struct crypt_sfop { size_t count; u_int32_t *sesid; };
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_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.
aesni(4), hifn(4), ipsec(4), padlock(4), safe(4), ubsec(4), crypto(7), geli(8), crypto(9)
The crypto
driver first appeared in
OpenBSD 3.0. The crypto
driver was imported to FreeBSD 5.0.
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.
September 21, 2017 | Debian |