CRYPTO_SESSION(9)

📦 version 15.1, in freebsd 14.5, freebsd 15.1

💖 NAME 💖

Okay so bestie, welcome to CRYPTO_SESSION(9) from the Kernel Developer’s Manual — this page is about crypto_session, aka the state used for symmetric cryptographic services. It’s giving kernel crypto lore, and honestly? Kind of iconic. ✨

✨ SYNOPSIS ✨

#include <opencrypto/cryptodev.h>

struct auth_hash *
crypto_auth_hash(const struct crypto_session_params *csp);

struct enc_xform *
crypto_cipher(const struct crypto_session_params *csp);

const struct crypto_session_params *
crypto_get_params(crypto_session_t cses);

int
crypto_newsession(crypto_session_t *cses,
    const struct crypto_session_params *csp, int crid);

int
crypto_freesession(crypto_session_t cses);

🌸 DESCRIPTION 🌸

So, symmetric cryptographic operations in the kernel are associated with cryptographic sessions. Sessions hold state that’s shared across multiple requests, and active sessions are associated with a single cryptographic driver. Very “one driver at a time” of them. 💅

The crypto_session_t type represents an opaque reference to an active session. Session objects are allocated and managed by the cryptographic framework — not you, bestie, the framework has it.

New sessions are created by crypto_newsession(). The csp argument describes various parameters associated with the new session, like the algorithms to use and any session-wide keys. The crid argument can be used to request either a specific cryptographic driver or classes of drivers. For the classes-of-drivers case, crid should be set to a mask of these values:

  • CRYPTOCAP_F_HARDWARE — Request hardware drivers. Hardware drivers do not use the host CPU to perform operations. Typically, a separate co-processor performs the operations asynchronously.
  • CRYPTOCAP_F_SOFTWARE — Request software drivers. Software drivers use the host CPU to perform operations. The kernel includes a simple, yet portable implementation of each supported algorithm in the cryptosoft(4) driver. Additional software drivers may also be available on architectures which provide instructions designed to accelerate cryptographic operations.

If both hardware and software drivers are requested, hardware drivers are preferred over software drivers. Accelerated software drivers are preferred over the baseline software driver. If multiple hardware drivers are available, the framework will distribute sessions across these drivers in a round-robin fashion. Cute little crypto round-robin, no cap. 🌀

On success, crypto_newsession() saves a reference to the newly created session in cses.

crypto_freesession() is used to free the resources associated with the session cses.

crypto_auth_hash() returns a structure describing the baseline software implementation of an authentication algorithm requested by csp. If csp does not specify an authentication algorithm, or requests an invalid algorithm, NULL is returned.

crypto_cipher() returns a structure describing the baseline software implementation of an encryption algorithm requested by csp. If csp does not specify an encryption algorithm, or requests an invalid algorithm, NULL is returned.

crypto_get_params() returns a pointer to the session parameters used by cses.

🎀 Session Parameters 🎀

Session parameters are used to describe the cryptographic operations performed by cryptographic requests. Parameters are stored in an instance of struct crypto_session_params.

When initializing parameters to pass to crypto_newsession(), the entire structure should first be zeroed. Needed fields should then be set, leaving unused fields as zero. Zero it first, bestie — the whole thing. 🫶

This structure contains the following fields:

  • csp_mode — Type of operation to perform. This field must be set to one of the following:
    • CSP_MODE_COMPRESS — Compress or decompress request payload. The compression algorithm is specified in csp_cipher_alg.
    • CSP_MODE_CIPHER — Encrypt or decrypt request payload. The encryption algorithm is specified in csp_cipher_alg.
    • CSP_MODE_DIGEST — Compute or verify a digest, or hash, of request payload. The authentication algorithm is specified in csp_auth_alg.
    • CSP_MODE_AEAD — Authenticated encryption with additional data. Decryption operations require the digest, or tag, and fail if it does not match. The AEAD algorithm is specified in csp_cipher_alg.
    • CSP_MODE_ETA — Encrypt-then-Authenticate. In this mode, encryption operations encrypt the payload and then compute an authentication digest over the request additional authentication data followed by the encrypted payload. Decryption operations fail without decrypting the data if the provided digest does not match. The encryption algorithm is specified in csp_cipher_alg and the authentication algorithm is specified in csp_auth_alg.
  • csp_flags — A mask of optional driver features. Drivers will only attach to a session if they support all of the requested features.
    • CSP_F_SEPARATE_OUTPUT — Support requests that use separate input and output buffers. Sessions with this flag set permit requests with either a single buffer that is modified in-place, or requests with separate input and output buffers. Sessions without this flag only permit requests with a single buffer that is modified in-place.
    • CSP_F_SEPARATE_AAD — Support requests that use a separate buffer for AAD rather than providing AAD as a region in the input buffer. Sessions with this flag set permit requests with AAD passed in either in a region of the input buffer or in a single, virtually-contiguous buffer. Sessions without this flag only permit requests with AAD passed in as a region in the input buffer.
    • CSP_F_ESN — Support requests that use a separate buffer for IPsec ESN (Extended Sequence Numbers). Sessions with this flag set permit requests with IPsec ESN passed in special buffer. It is required for IPsec ESN support of encrypt and authenticate mode where the high-order 32 bits of the sequence number are appended after the Next Header (RFC 4303).
  • csp_ivlen — If either the cipher or authentication algorithms require an explicit initialization vector (IV) or nonce, this specifies the length in bytes. All requests for a session use the same IV length.
  • csp_cipher_alg — Encryption or compression algorithm.
  • csp_cipher_klen — Length of encryption or decryption key in bytes. All requests for a session use the same key length.
  • csp_cipher_key — Pointer to encryption or decryption key. If all requests for a session use request-specific keys, this field should be left as NULL. This pointer and associated key must remain valid for the duration of the crypto session.
  • csp_auth_alg — Authentication algorithm.
  • csp_auth_klen — Length of authentication key in bytes. If the authentication algorithm does not use a key, this field should be left as zero.
  • csp_auth_key — Pointer to the authentication key. If all requests for a session use request-specific keys, this field should be left as NULL. This pointer and associated key must remain valid for the duration of the crypto session.
  • csp_auth_mlen — The length in bytes of the digest. If zero, the full length of the digest is used. If non-zero, the first csp_auth_mlen bytes of the digest are used.

🫶 RETURN VALUES 🫶

crypto_newsession() returns a non-zero value if an error occurs or zero on success.

crypto_auth_hash() and crypto_cipher() return NULL if the request is valid or a pointer to a structure on success. Yes, that is literally what the page says, bestie — I’m not editing the lore. 😭

🌈 SEE ALSO 🌈

💀 BUGS 💀

The current implementation of crypto_freesession does not provide a way for the caller to know that there are no other references to the keys stored in the session’s associated parameters. This function should probably sleep until any in-flight cryptographic operations associated with the session are completed. So yeah — it’s giving “should probably nap until the crypto ops are done,” and that’s the bug note, periodt. 💀

Source/version vibe: this one came from Debian, dated June 22, 2020, and the manual name is CRYPTO_SESSION(9) — mwah, bye bestie! 🎀💖✨

📦 where this page comes from