CRYPTO(4) NetBSD Kernel Interfaces Manual 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-accel- erated 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 spe- cial 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 tradi- tional 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 reg- istering 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 descrip- tor 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 opera- tion 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 symmet- ric-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 speci- fied 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. NetBSD 4.0 September 23, 2006 NetBSD 4.0
Powered by man-cgi (2024-08-26). Maintained for NetBSD by Kimmo Suominen. Based on man-cgi by Panagiotis Christias.