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

FreeBSD Manual Pages

  
 
  

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

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

SYNOPSIS
     device crypto
     device cryptodev

     #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 crypto(9) in-kernel
     interface.

     The /dev/crypto special device provides an	ioctl(2) based interface.
     User-mode applications open the special device and	then issue ioctl(2)
     calls on the descriptor.  User-mode access	to /dev/crypto is controlled
     by	two sysctl(8) variables: kern.userasymcrypto and
     kern.cryptodevallowsoft.

     The crypto	device provides	two distinct modes of operation: one mode for
     symmetric-keyed cryptographic requests and	digests, and a second mode for
     both asymmetric-key (public-key/private-key) requests and modular arith-
     metic (for	Diffie-Hellman key exchange and	other cryptographic proto-
     cols).  The two modes are described separately below.

DEPRECATION NOTICE
     The asymmetric-key	operations supported by	this interface will not	be
     present in	FreeBSD	14.0 and later.

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 the /dev/crypto device.

     2.	  If any symmetric-keyed cryptographic or digest operations will be
	  performed, create a session with CIOCGSESSION	or CIOCGSESSION2.
	  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),
	  CIOCCRYPTAEAD	(symmetric), or	CIOCKEY	(asymmetric).

     4.	  Optionally destroy a session with CIOCFSESSION.

     5.	  Close	the /dev/crypto	device.	 This will automatically close any re-
	  maining sessions associated with the file desriptor.

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 encrypt-then-authenticate fused operation, where the hard-
     ware performs both	a privacy algorithm and	an integrity-check algorithm
     in	a single pass over the data: either a fused encrypt/HMAC-generate op-
     eration, 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.

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

   IOCTL Request Descriptions
     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 {
		       uint32_t	cipher;	   /* e.g. CRYPTO_AES_CBC */
		       uint32_t	mac;	   /* e.g. CRYPTO_SHA2_256_HMAC	*/

		       uint32_t	keylen;	   /* cipher key */
		       const void *key;
		       int mackeylen;	   /* mac key */
		       const void *mackey;

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

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

		   Support for a specific combination of fused privacy and in-
		   tegrity-check algorithms depends on whether the underlying
		   hardware supports that combination.	Not all	combinations
		   are supported by all	hardware, even if the hardware sup-
		   ports each operation	as a stand-alone non-fused operation.

     CIOCGSESSION2 struct session2_op *sessp

		   struct session2_op {
		       uint32_t	cipher;	   /* e.g. CRYPTO_AES_CBC */
		       uint32_t	mac;	   /* e.g. CRYPTO_SHA2_256_HMAC	*/

		       uint32_t	keylen;	   /* cipher key */
		       const void *key;
		       int mackeylen;	   /* mac key */
		       const void *mackey;

		       uint32_t	ses;	   /* returns: ses # */
		       int crid;	   /* driver id	+ flags	(rw) */
		       int pad[4];	   /* for future expansion */
		   };

		   This	request	is similar to CIOGSESSION except that
		   sessp-_crid requests	either a specific crypto device	or a
		   class of devices (software vs hardware).  The sessp-_pad
		   field must be initialized to	zero.

     CIOCCRYPT struct crypt_op *cr_op

		   struct crypt_op {
		       uint32_t	ses;
		       uint16_t	op;	   /* e.g. COP_ENCRYPT */
		       uint16_t	flags;
		       u_int len;
		       const void *src;
		       void *dst;
		       void *mac;	   /* must be large enough for result */
		       const void *iv;
		   };

		   Request a symmetric-key (or hash) operation.	 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	session	is using either	fused encrypt-then-authenti-
		   cate	or an AEAD algorithm, decryption operations require
		   the associated hash as an input.  If	the hash is incorrect,
		   the operation will fail with	EBADMSG	and the	output buffer
		   will	remain unchanged.

     CIOCCRYPTAEAD struct crypt_aead *cr_aead

		   struct crypt_aead {
		       uint32_t	ses;
		       uint16_t	op;	   /* e.g. COP_ENCRYPT */
		       uint16_t	flags;
		       u_int len;
		       u_int aadlen;
		       u_int ivlen;
		       const void *src;
		       void *dst;
		       const void *aad;	   /* additional authenticated data */
		       void *tag;	   /* must fit for chosen TAG length */
		       const void *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	session	identified by ses_id.

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

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

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

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

FreeBSD	13.0		       November	24, 2020		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | DEPRECATION NOTICE | THEORY OF OPERATION | SYMMETRIC-KEY OPERATION | ASYMMETRIC-KEY OPERATION | SEE ALSO | HISTORY | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=cryptodev&sektion=4&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help