Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.


CRYPTO(4)                    Device Drivers 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-
     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.  User-mode access to /dev/crypto is
     generally controlled by three sysctl(8) variables, kern.usercrypto,
     kern.userasymcrypto, and kern.cryptodevallowsoft.  See sysctl(7) for
     additional details.

     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.

THEORY OF OPERATION
     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, or multiple sessions, with CIOCNGSESSION.  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
          (asymmetric) or asynchronously with CIOCNCRYPTM (symmetric) or
          CIOCNFKEYM (asymmetric).  The asynchronous interface allows multiple
          requests to be submitted in one call if the user so desires.

     4.   If the asynchronous interface is used, wait for results with
          select(2) or poll(2), then collect them with CIOCNCRYPTRET (a
          particular request) or CIOCNCRYPTRETM (multiple requests).

     5.   Destroy one session with CIOCFSESSION or many at once with
          CIOCNFSESSION.

     6.   Close the device with close(2).

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_256_HMAC
           CRYPTO_SHA2_384_HMAC
           CRYPTO_SHA2_512_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
              This operation is deprecated and will be removed after
              NetBSD 5.0.  It clones the fd argument to ioctl(2), yielding a
              new file descriptor for the creation of sessions.  Because the
              device now clones on open, this operation is unnecessary.

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

              This implementation will never return a session ID of 0 for a
              successful creation of a session, which is a NetBSD extension.

              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.

     CIOCNGSESSION struct crypt_sgop *sgop

              struct crypt_sgop {
                  size_t      count;                  /* how many */
                  struct session_n_op * sessions; /* where to get them */
              };

              struct session_n_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;
                  u_int32_t mackeylen;        /* mac key */
                  void * mackey;

                  u_int32_t ses;              /* returns: session # */
                  int status;
              };

              Create one or more sessions.  Takes a counted array of
              session_n_op structures in sgop.  For each requested session
              (array element n), the session number is returned in
              sgop->sessions[n].ses and the status for that session creation
              in sgop->sessions[n].status.

     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;
                  void * src, *dst;
                  void * mac;         /* must be large enough for result */
                  void * 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.

     CIOCNCRYPTM struct crypt_mop *cr_mop

              struct crypt_mop {
                  size_t count;               /* how many */
                  struct crypt_n_op * reqs;   /* where to get them */
              };

              struct crypt_n_op {
                  u_int32_t ses;
                  u_int16_t op;               /* e.g. COP_ENCRYPT */
                  u_int16_t flags;
                  u_int len;

                  u_int32_t reqid;            /* request id */
                  int status;                 /* accepted or not */

                  void *opaque;               /* opaque pointer ret to user */
                  u_int32_t keylen;           /* cipher key - optional */
                  void * key;
                  u_int32_t mackeylen;        /* mac key - optional */
                  void * mackey;

                  void * src, * dst;
                  void * mac;
                  void * iv;
              };

              This is the asynchronous version of CIOCCRYPT, which allows
              multiple symmetric-key (or hash) operations to be started (see
              CIOCRYPT above for the details for each operation).

              The cr_mop->count field specifies the number of operations
              provided in the cr_mop->reqs array.

              Each operation is assigned a unique request id returned in the
              cr_mop->reqs[n].reqid field.

              Each operation can accept an opaque value from the user to be
              passed back to the user when the operation completes (e.g., to
              track context for the request).  The opaque field is
              cr_mop->reqs[n].opaque.

              If a problem occurs with starting any of the operations then
              that operation's cr_mop->reqs[n].status field is filled with the
              error code.  The failure of an operation does not prevent the
              other operations from being started.

              The select(2) or poll(2) functions must be used on the device
              file descriptor to detect that some operation has completed;
              results are then retrieved with CIOCNCRYPTRETM.

              The key and mackey fields of the operation structure are
              currently unused.  They are intended for use to immediately
              rekey an existing session before processing a new request.

     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 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_MOD_ADD           3                  1
           CRK_MOD_ADDINV        2                  1
           CRK_MOD_SUB           3                  1
           CRK_MOD_MULT          3                  1
           CRK_MOD_MULTINV       2                  1
           CRK_MOD               2                  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.

     CIOCNFKEYM struct crypt_mkop *mkop

              struct crypt_mkop {
                  size_t count;               /* how many */
                  struct crypt_n_op * reqs;   /* where to get them */
              };

              struct crypt_n_kop {
                  u_int crk_op;               /* e.g. CRK_MOD_EXP */
                  u_int crk_status;           /* accepted or not */
                  u_short crk_iparams;        /* # of input params */
                  u_short crk_oparams;        /* # of output params */
                  u_int32_t crk_reqid;        /* request id */
                  struct crparam crk_param[CRK_MAXPARAM];
                  void *crk_opaque;           /* opaque pointer ret to user */
              };

              This is the asynchronous version of CIOCKEY, which starts one or
              more key operations.  See CIOCNCRYPTM above and CIOCNCRYPTRETM
              below for descriptions of the mkop>count, mkop>reqs,
              mkop>reqs[n].crk_reqid, mkop>reqs[n].crk_status, and
              mkop>reqs[n].crk_opaque fields of the argument structure, and
              result retrieval.

   Asynchronous status commands
     When requests are submitted with the CIOCNCRYPTM or CIOCNFKEYM commands,
     result retrieval is asynchronous (the submit ioctls return immediately).
     Use the select(2) or poll(2) functions to determine when the file
     descriptor has completed operations ready to be retrieved.

     CIOCNCRYPTRET struct crypt_result *cres

              struct crypt_result {
                  u_int32_t reqid;    /* request ID */
                  u_int32_t status;   /* 0 if successful */
                  void * opaque;      /* pointer from user */
              };

              Check for the status of the request specified by cres->reqid.
              This requires a linear search through all completed requests and
              should be used with extreme care if the number of requests
              pending on this file descriptor may be large.

              The cres->status field is set as follows:

              0            The request has completed, and its results have
                           been copied out to the original crypt_n_op or
                           crypt_n_kop structure used to start the request.
                           The copyout occurs during this ioctl, so the
                           calling process must be the process that started
                           the request.

              EINPROGRESS  The request has not yet completed.

              EINVAL       The request was not found.

              Other values indicate a problem during the processing of the
              request.

     CIOCNCRYPTRETM struct cryptret_t *cret

              struct cryptret {
                  size_t count;                       /* space for how many */
                  struct crypt_result * results;      /* where to put them */
              };

              Retrieve a number of completed requests.  This ioctl accepts a
              count and an array (each array element is a crypt_result_t
              structure as used by CIOCNCRYPTRET above) and fills the array
              with up to cret->count results of completed requests.

              This ioctl fills in the cret->results[n].reqid field, so that
              the request which has completed may be identified by the
              application.  Note that the results may include requests
              submitted both as symmetric and asymmetric operations.

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.

     The "new API" for asynchronous operation with multiple basic operations
     per system call (the "N" ioctl variants) was contributed by Coyote Point
     Systems, Inc. and first appeared in NetBSD 5.0.

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.

NetBSD 10.99                   January 27, 2014                   NetBSD 10.99