crypto(4) - NetBSD Manual Pages

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