CRYPTO(4) FreeBSD Kernel Interfaces Manual CRYPTO(4)
NAME
crypto, cryptodev - user-mode access to hardware-accelerated cryptography
SYNOPSIS
device crypto
device cryptodev
#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 crypto(9) in-
kernel interface.
The /dev/crypto special device provides an ioctl(2) based interface.
User-mode applications open the special device and then issue ioctl(2)
calls on the descriptor. User-mode access to /dev/crypto is controlled
by two 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 digests, and a second mode for
both asymmetric-key (public-key/private-key) requests and modular
arithmetic (for Diffie-Hellman key exchange and other cryptographic
protocols). The two modes are described separately below.
DEPRECATION NOTICE
The asymmetric-key operations supported by this interface will not be
present in FreeBSD 14.0 and later.
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:
1. Open the /dev/crypto device.
2. If any symmetric-keyed cryptographic or digest operations will be
performed, create a session with CIOCGSESSION or CIOCGSESSION2.
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.
3. Submit requests, synchronously with CIOCCRYPT (symmetric),
CIOCCRYPTAEAD (symmetric), or CIOCKEY (asymmetric).
4. Optionally destroy a session with CIOCFSESSION.
5. Close the /dev/crypto device. This will automatically close any
remaining sessions associated with the file desriptor.
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 encrypt-then-authenticate 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.
Algorithms
For a list of supported algorithms, see crypto(7) and crypto(9).
IOCTL Request Descriptions
CIOCFINDDEV struct crypt_find_op *fop
struct crypt_find_op {
int crid; /* driver id + flags */
char name[32]; /* device/driver name */
};
If crid is -1, then find the driver named name and return
the id in crid. If crid is not -1, return the name of the
driver with crid in name. In either case, if the driver is
not found, ENOENT is returned.
CIOCGSESSION struct session_op *sessp
struct session_op {
uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
uint32_t keylen; /* cipher key */
const void *key;
int mackeylen; /* mac key */
const void *mackey;
uint32_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.
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.
CIOCGSESSION2 struct session2_op *sessp
struct session2_op {
uint32_t cipher; /* e.g. CRYPTO_AES_CBC */
uint32_t mac; /* e.g. CRYPTO_SHA2_256_HMAC */
uint32_t keylen; /* cipher key */
const void *key;
int mackeylen; /* mac key */
const void *mackey;
uint32_t ses; /* returns: ses # */
int crid; /* driver id + flags (rw) */
int ivlen; /* length of nonce/IV */
int maclen; /* length of MAC/tag */
int pad[2]; /* for future expansion */
};
This request is similar to CIOGSESSION but adds additional
fields.
sessp->crid requests either a specific crypto device or a
class of devices (software vs hardware).
sessp->ivlen specifies the length of the IV or nonce
supplied with each request. If this field is set to zero,
the default IV or nonce length is used.
sessp->maclen specifies the length of the MAC or
authentication tag supplied or computed by each request.
If this field is set to zero, the full MAC is used.
The sessp->pad field must be initialized to zero.
CIOCCRYPT struct crypt_op *cr_op
struct crypt_op {
uint32_t ses;
uint16_t op; /* e.g. COP_ENCRYPT */
uint16_t flags;
u_int len;
const void *src;
void *dst;
void *mac; /* must be large enough for result */
const void *iv;
};
Request a symmetric-key (or hash) operation. 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.
If a session is using either fused encrypt-then-
authenticate or an AEAD algorithm, decryption operations
require the associated hash as an input. If the hash is
incorrect, the operation will fail with EBADMSG and the
output buffer will remain unchanged.
CIOCCRYPTAEAD struct crypt_aead *cr_aead
struct crypt_aead {
uint32_t ses;
uint16_t op; /* e.g. COP_ENCRYPT */
uint16_t flags;
u_int len;
u_int aadlen;
u_int ivlen;
const void *src;
void *dst;
const void *aad; /* additional authenticated data */
void *tag; /* must fit for chosen TAG length */
const void *iv;
};
The 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_id
Destroys the session identified by ses_id.
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_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.
SEE ALSO
aesni(4), hifn(4), ipsec(4), padlock(4), safe(4), crypto(7), geli(8),
crypto(9)
HISTORY
The crypto driver first appeared in OpenBSD 3.0. The crypto driver was
imported to FreeBSD 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.
FreeBSD 13.1-RELEASE-p6 October 6, 2021 FreeBSD 13.1-RELEASE-p6
man2web Home...