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

FreeBSD Manual Pages


home | help
CRYPTO(4)	       FreeBSD Kernel Interfaces Manual		     CRYPTO(4)

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

     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-accel-
     erated cryptographic transforms, as implemented by	the crypto(9) in-ker-
     nel 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	asym-
     metric-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 sym-
	  metric 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),
	  CIOCCRYPTAEAD	(symmetric), or	CIOCKEY	(asymmetric).

     4.	  Destroy one session with CIOCFSESSION.

     5.	  Close	the device with	close(2).

     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 al-
     gorithm(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 de-
		   scriptor 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 op-
		   eration (privacy or integrity) is not desired for this ses-

		   Multiple sessions may be bound to a single file descriptor.
		   The session ID returned in sessp-_ses is supplied as	a re-
		   quired 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 underly-
		   ing hardware	supports that combination.  Not	all combina-
		   tions are supported by all hardware,	even if	the hardware
		   supports each operation as a	stand-alone non-fused opera-

     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 de-
		   scriptor 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.  If a	ses-
		   sion	is using both a	privacy	algorithm and a	hash algo-
		   rithm, the request will generate a hash of the input	buffer
		   before generating the output	buffer by default.  If the
		   COP_F_CIPHER_FIRST flag is included in the cr_op-_flags
		   field, then the request will	generate a hash	of the output
		   buffer after	executing the privacy algorithm.

     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 authenti-
		   cation 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 ar-
		   ray 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 in-
	      put 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 ex-
     actly match the values expected by	opencrypto(9).	The output buffer and
     MAC buffers supplied to CIOCCRYPT must follow whether privacy or integ-
     rity algorithms were specified for	session: if you	request	a non-NULL al-
     gorithm, 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	13.0		      September	21, 2017		  FreeBSD 13.0


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

home | help