Algorithms

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 algorithms

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.