CRYPTO(4)

NAME
crypto, swcrypto - user-mode access to hardware-accelerated cryptography

SYNOPSIS
hifn* at pci? dev ? function ?
ubsec* at pci? dev ? function ?

pseudo-device crypto
pseudo-device swcrypto

#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 opencrypto(9) in-kernel interface. The swcrypto driver is a software-only implementation of the opencrypto(9) interface, and must be included to use the interface without hardware acceleration. 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. 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 exponentiation (for Diffie-Hellman key exchange). The two modes are described separately below.

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 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.

  Symmetric-key privacy algorithms
Contingent upon device drivers for installed cryptographic hardware registering with opencrypto(9), as providers of a given algorithm, some or all of the following symmetric-key privacy algorithms may be available:
CRYPTO_DES_CBC
CRYPTO_3DES_CBC
CRYPTO_BLF_CBC
CRYPTO_CAST_CBC
CRYPTO_SKIPJACK_CBC
CRYPTO_AES_CBC
CRYPTO_ARC4

  Integrity-check operations
Contingent upon hardware support, some or all of the following keyed one-way hash algorithms may be available:
CRYPTO_RIPEMD160_HMAC
CRYPTO_MD5_KPDK
CRYPTO_SHA1_KPDK
CRYPTO_MD5_HMAC
CRYPTO_SHA1_HMAC
CRYPTO_SHA2_HMAC
CRYPTO_MD5
CRYPTO_SHA1
The CRYPTO_MD5 and CRYPTO_SHA1 algorithms are actually unkeyed, but should be requested as symmetric-key hash algorithms with a zero-length key.

  IOCTL Request Descriptions

CRIOGET int *fd
    Clone the fd argument to ioctl(4), yielding a new file descriptor which can be used to create crypto sessions and request crypto operations.

CIOCGSESSION struct session_op *sessp
    Persistently bind a file descriptor returned by a previous CRIOGET to a session: that is, 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.

    For non-zero symmetric-key privacy algorithms, the privacy algorithm must be specified in sess-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_op
    Request a symmetric-key (or unkeyed hash) operation. The file descriptor argument to ioctl(4) must have been bound to a valid session. 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.

CIOCFSESSION void
    Destroys the /dev/crypto session associated with the file-descriptor argument.

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

CIOCASSYMFEAT 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_EX) is set.

CIOCFKEY struct crypt_kop *kop
    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
hifn(4), ubsec(4), opencrypto(9)

HISTORY
The crypto driver is derived from a version which appeared in FreeBSD 4.8, which in turn is based on code which appeared in OpenBSD 3.2.

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.

The naming inconsistency between CRIOGET and the various CIOC* names is an unfortunate historical artifact.