Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
CRYPTO(4)              FreeBSD Kernel Interfaces Manual              CRYPTO(4)

     crypto, cryptodev - user-mode access to hardware-accelerated cryptography

     device crypto
     device cryptodev

     #include <sys/ioctl.h>
     #include <sys/time.h>
     #include <crypto/cryptodev.h>

     The crypto driver gives user-mode applications access to hardware-
     accelerated cryptographic transforms, as implemented by the crypto(9) in-
     kernel interface.

     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.  User-mode access to /dev/crypto is
     controlled by three sysctl(8) variables, kern.userasymcrypto and

     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
     arithmetic (for Diffie-Hellman key exchange and other cryptographic
     protocols).  The two modes are described separately below.

     Regardless of whether symmetric-key or asymmetric-key operations are to
     be performed, use of the device requires a basic series of steps:

     1.   Open a file descriptor for the device.  See open(2).

     2.   If any symmetric operation will be performed, create one session,
          with CIOCGSESSION.  Most applications will require at least one
          symmetric session.  Since cipher and MAC keys are tied to sessions,
          many applications will require more.  Asymmetric operations do not
          use sessions.

     3.   Submit requests, synchronously with CIOCCRYPT (symmetric) or CIOCKEY

     4.   Destroy one session with CIOCFSESSION.

     5.   Close the device with close(2).

     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.

     For a list of supported algorithms, see crypto(7) and crypto(9).

   IOCTL Request Descriptions
     CRIOGET int *fd
                   Clone the fd argument to ioctl(2), yielding a new file
                   descriptor for the creation of sessions.

     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 {
                       u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
                       u_int32_t mac;      /* e.g. CRYPTO_MD5_HMAC */

                       u_int32_t keylen;   /* cipher key */
                       void * key;
                       int mackeylen;      /* mac key */
                       void * mackey;

                       u_int32_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

                   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

                   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

     CIOCCRYPT struct crypt_op *cr_op

                   struct crypt_op {
                       u_int32_t ses;
                       u_int16_t op;       /* e.g. COP_ENCRYPT */
                       u_int16_t flags;
                       u_int len;
                       caddr_t src, dst;
                       caddr_t mac;                /* must be large enough for result */
                       caddr_t iv;

                   Request a symmetric-key (or hash) operation.  The file
                   descriptor argument to ioctl(2) 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.

     CIOCCRYPTAEAD struct crypt_aead *cr_aead

                   struct crypt_aead {
                       u_int32_t ses;
                       u_int16_t op;       /* e.g. COP_ENCRYPT */
                       u_int16_t flags;
                       u_int len;
                       u_int aadlen;
                       u_int ivlen;
                       caddr_t src, dst;
                       caddr_t aad;
                       caddr_t tag;                /* must be large enough for result */
                       caddr_t 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 /dev/crypto session associated with the file-
                   descriptor argument.

     CIOCNFSESSION struct crypt_sfop *sfop;

                   struct crypt_sfop {
                       size_t count;
                       u_int32_t *sesid;

                   Destroys the sfop-_count sessions specified by the sfop
                   array of session identifiers.

   Asymmetric-key algorithms
     Contingent upon hardware support, the following asymmetric (public-
     key/private-key; or key-exchange subroutine) operations may also be

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

     aesni(4), hifn(4), ipsec(4), padlock(4), safe(4), ubsec(4), crypto(7),
     geli(8), crypto(9)

     The crypto driver first appeared in OpenBSD 3.0.  The crypto driver was
     imported to FreeBSD 5.0.

     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.

FreeBSD 11.0-PRERELEASE        December 15, 2015       FreeBSD 11.0-PRERELEASE


Want to link to this manual page? Use this URL:

home | help