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.

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.	  Create a new cryptography file descriptor via	CRIOGET	to use for all
	  subsequent ioctl(2) commands.

     3.	  Close	the /dev/crypto	device.

     4.	  If any symmetric-keyed cryptographic or digest operations will be
	  performed, create a 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.

     5.	  Submit requests, synchronously with CIOCCRYPT	(symmetric),
	  CIOCCRYPTAEAD	(symmetric), or	CIOCKEY	(asymmetric).

     6.	  Optionally destroy a session with CIOCFSESSION.

     7.	  Close	the cryptography file descriptor with close(2).	 This will au-
	  tomatically close any	remaining 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 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.

   Algorithms
     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 */
		       const void *key;
		       int mackeylen;	   /* mac key */
		       const 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-
		   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 {
		       u_int32_t cipher;   /* e.g. CRYPTO_DES_CBC */
		       u_int32_t mac;	   /* e.g. CRYPTO_MD5_HMAC */

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

		       u_int32_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 {
		       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.	 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	both a privacy
		   algorithm and a hash	algorithm, the request will generate a
		   hash	of the input buffer before generating the output buf-
		   fer 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 algo-
		   rithm.

     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	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), ubsec(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.

     CRIOGET should not	exist.	It should be possible to use the CIOC* com-
     mands directly on a /dev/crypto file descriptor.

FreeBSD	13.0		       December	17, 2019		  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | 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=crypto&sektion=4&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help