| CRYPTO(4) | Device Drivers Manual | CRYPTO(4) | 
crypto, swcrypto —
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>
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.
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.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.CIOCNCRYPTRET (a particular request) or
      CIOCNCRYPTRETM (multiple requests).CIOCFSESSION or many at
      once with CIOCNFSESSION.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.
The CRYPTO_MD5 and CRYPTO_SHA1 algorithms are actually unkeyed, but should be requested as symmetric-key hash algorithms with a zero-length key.
CRIOGET
    int *fdCIOCGSESSION
    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 # */
};
    
    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;
};
    
    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;
};
    
    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;
};
    
    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_idCIOCNFSESSION
    struct crypt_sfop *sfop
struct crypt_sfop {
    size_t count;
    u_int32_t *sesid;
};
    
    | 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.
CIOCASYMFEAT
    int *feature_maskCRK_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;
};
    
    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 */
};
    
    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.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 */
};
    
    The cres->status field is set as follows:
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 */
};
    
    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.
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.
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.
| January 27, 2014 | NetBSD 10.1 |