CRYPTO(4)

✨ CRYPTO(4) ✨

okay bestie, this one's from the Kernel Interfaces Manual and it's lowkey iconic, so let's get into it 💖

---

🎀 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 💅

So the crypto driver is literally the plug that lets user-mode applications get at hardware-accelerated cryptographic transforms, exactly as they're implemented by the crypto(9) in-kernel interface. slay.

The /dev/crypto special device is the one serving up an ioctl(2) based interface. Your user-mode app opens the special device, and then just... issues ioctl(2) calls on the descriptor. that's the vibe. User-mode access to /dev/crypto is controlled by two sysctl(8) variables: kern.userasymcrypto and kern.cryptodevallowsoft. 🎀

Not me having to tell you the crypto device has two distinct modes of operation:

• one mode for symmetric-keyed cryptographic requests and digests 🧚
• a second mode for both asymmetric-key (public-key/private-key) requests and modular arithmetic (that's for Diffie-Hellman key exchange and other cryptographic protocols) 👑

Both modes get described separately below, don't worry.

---

🌈 THEORY OF OPERATION 🌈

Regardless of whether you're doing symmetric-key or asymmetric-key operations, using the device requires a basic series of steps. periodt:

1. Open the /dev/crypto device.
2. Create a new cryptography file descriptor via CRIOGET to use for all subsequent ioctl(2) commands.
3. Close the /dev/crypto device.
4. If any symmetric-keyed cryptographic or digest operations will be performed, create a session with 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.
5. Submit requests, synchronously with CIOCCRYPT (symmetric), CIOCCRYPTAEAD (symmetric), or CIOCKEY (asymmetric).
6. Optionally destroy a session with CIOCFSESSION.
7. Close the cryptography file descriptor with close(2). This will automatically close any remaining sessions associated with the file descriptor. 🫶

---

🔥 SYMMETRIC-KEY OPERATION 🔥

The symmetric-key operation mode gives you 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. it's giving efficiency 💅

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 💖

• CRIOGET int *fd — Clone the fd argument to ioctl(2), yielding a new file descriptor for the creation of sessions.
• CIOCFINDDEV struct crypt_find_op *fop — here's the struct, bestie:

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 — the moment you've all been waiting for:

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 */
    const void *key;
    int mackeylen;      /* mac key */
    const 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.

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 — round two, babe:

struct session2_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 */
    const void *key;
    int mackeylen;      /* mac key */
    const void *mackey;

    u_int32_t ses;      /* returns: ses # */
    int crid;           /* driver id + flags (rw) */
    int pad[4];         /* for future expansion */
};

This request is similar to CIOGSESSION except that sessp->crid requests either a specific crypto device or a class of devices (software vs hardware). The sessp->pad field must be initialized to zero. no cap.

• CIOCCRYPT struct crypt_op *cr_op — the main character:

struct 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;
};

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 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_aead — the aead edition:

struct 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;
};

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. bye bestie 👋

---

👑 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. iykyk 💅
• CIOCKEY struct crypt_kop *kop — the big one:

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. 🙈 mystery behaviour fr fr, good luck bestie ✨

✨ SEE ALSO ✨

ok so if you wanna go down the rabbit hole (and bestie, you know you do 🐇💖), here's the whole squad:

• aesni(4) — the AES-NI glow-up
• hifn(4) — Hifn crypto accelerator
• ipsec(4) — IPsec, the classic
• padlock(4) — VIA PadLock, we love her
• safe(4) — SafeNet crypto accelerator
• ubsec(4) — Broadcom uBsec crypto accelerator
• crypto(7) — the crypto subsystem overview, different vibe, same family 🫶
• geli(8) — disk encryption, main character energy fr
• crypto(9) — the kernel-side API, this is where the real lore lives

---

🌈 HISTORY 🌈

so the crypto driver first appeared in OpenBSD 3.0. iconic. 💅 then it got imported to FreeBSD 5.0. it's giving cross-platform royalty, no cap 👑

---

💀 BUGS 💀

bestie. sit down. we need to talk. 🙈

• Error checking and reporting is weak. that's it, that's the bug. it's giving "we'll handle it later" and later never came 😭
• The values you specify for symmetric-key key sizes to CIOCGSESSION must exactly match the values expected by opencrypto(9). not "close enough", not "vibes-based", exactly. if it doesn't match, it's not gonna slay, it's gonna flop 💀
• The output buffer and MAC buffers supplied to CIOCCRYPT must follow whether privacy or integrity algorithms were specified for the session: if you request a non-NULL algorithm, you must supply a suitably-sized buffer. tl;dr — you asked for it, you gotta bring the space for it 🎒✨
• The scheme for passing arguments for asymmetric requests is baroque. yes, baroque. like, ornate. like, unnecessarily decorated. like someone was feeling artsy that day and we all pay for it now 🎻😭
• CRIOGET should not exist. it should be possible to use the CIOC* commands directly on a /dev/crypto file descriptor. periodt. the extra step is giving "extra credit assignment nobody asked for" 🙄

fr fr, if you're out here debugging crypto sessions and nothing makes sense, it's probably one of these. it's not you, bestie. it's the API 💜

---

and that's the whole page, babe 🎀 this one's from the Debian folks and it's dated December 17, 2019 — so yeah, it's been sitting in the group chat for a minute, but the tea is still hot ☕✨ now go forth and encrypt responsibly, you gorgeous nerd 🦋💖