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

FreeBSD Manual Pages

  
 
  

home | help
CRYPTO_SESSION(9)      FreeBSD Kernel Developer's Manual     CRYPTO_SESSION(9)

NAME
     crypto_session -- state used for symmetric	cryptographic services

SYNOPSIS
     #include <opencrypto/cryptodev.h>

     struct auth_hash *
     crypto_auth_hash(const struct crypto_session_params *csp);

     struct enc_xform *
     crypto_cipher(const struct	crypto_session_params *csp);

     const struct crypto_session_params	*
     crypto_get_params(crypto_session_t	cses);

     int
     crypto_newsession(crypto_session_t	*cses,
	 const struct crypto_session_params *csp, int crid);

     int
     crypto_freesession(crypto_session_t cses);

DESCRIPTION
     Symmetric cryptographic operations	in the kernel are associated with
     cryptographic sessions.  Sessions hold state shared across	multiple re-
     quests.  Active sessions are associated with a single cryptographic
     driver.

     The crypto_session_t type represents an opaque reference to an active
     session.  Session objects are allocated and managed by the	cryptographic
     framework.

     New sessions are created by crypto_newsession().  csp describes various
     parameters	associated with	the new	session	such as	the algorithms to use
     and any session-wide keys.	 crid can be used to request either a specific
     cryptographic driver or classes of	drivers.  For the latter case, crid
     should be set to a	mask of	the following values:

     CRYPTOCAP_F_HARDWARE  Request hardware drivers.  Hardware drivers do not
			   use the host	CPU to perform operations.  Typically,
			   a separate co-processor performs the	operations
			   asynchronously.

     CRYPTOCAP_F_SOFTWARE  Request software drivers.  Software drivers use the
			   host	CPU to perform operations.  The	kernel in-
			   cludes a simple, yet	portable implementation	of
			   each	supported algorithm in the cryptosoft(4)
			   driver.  Additional software	drivers	may also be
			   available on	architectures which provide instruc-
			   tions designed to accelerate	cryptographic opera-
			   tions.

     If	both hardware and software drivers are requested, hardware drivers are
     preferred over software drivers.  Accelerated software drivers are	pre-
     ferred over the baseline software driver.	If multiple hardware drivers
     are available, the	framework will distribute sessions across these	driv-
     ers in a round-robin fashion.

     On	success, crypto_newsession() saves a reference to the newly created
     session in	cses.

     crypto_freesession() is used to free the resources	associated with	the
     session cses.

     crypto_auth_hash()	returns	a structure describing the baseline software
     implementation of an authentication algorithm requested by	csp.  If csp
     does not specify an authentication	algorithm, or requests an invalid al-
     gorithm, NULL is returned.

     crypto_cipher() returns a structure describing the	baseline software im-
     plementation of an	encryption algorithm requested by csp.	If csp does
     not specify an encryption algorithm, or requests an invalid algorithm,
     NULL is returned.

     crypto_get_params() returns a pointer to the session parameters used by
     cses.

   Session Parameters
     Session parameters	are used to describe the cryptographic operations per-
     formed by cryptographic requests.	Parameters are stored in an instance
     of	struct crypto_session_params.  When initializing parameters to pass to
     crypto_newsession(), the entire structure should first be zeroed.	Needed
     fields should then	be set leaving unused fields as	zero.  This structure
     contains the following fields:

     csp_mode	      Type of operation	to perform.  This field	must be	set to
		      one of the following:

		      CSP_MODE_COMPRESS	 Compress or decompress	request	pay-
					 load.

					 The compression algorithm is speci-
					 fied in csp_cipher_alg.

		      CSP_MODE_CIPHER	 Encrypt or decrypt request payload.

					 The encryption	algorithm is specified
					 in csp_cipher_alg.

		      CSP_MODE_DIGEST	 Compute or verify a digest, or	hash,
					 of request payload.

					 The authentication algorithm is spec-
					 ified in csp_auth_alg.

		      CSP_MODE_AEAD	 Authenticated encryption with addi-
					 tional	data.  Decryption operations
					 require the digest, or	tag, and fail
					 if it does not	match.

					 The AEAD algorithm is specified in
					 csp_cipher_alg.

		      CSP_MODE_ETA	 Encrypt-then-Authenticate.  In	this
					 mode, encryption operations encrypt
					 the payload and then compute an au-
					 thentication digest over the request
					 additional authentication data	fol-
					 lowed by the encrypted	payload.  De-
					 cryption operations fail without de-
					 crypting the data if the provided di-
					 gest does not match.

					 The encryption	algorithm is specified
					 in csp_cipher_alg and the authentica-
					 tion algorithm	is specified in
					 csp_auth_alg.

     csp_flags	      A	mask of	optional driver	features.  Drivers will	only
		      attach to	a session if they support all of the requested
		      features.

		      CSP_F_SEPARATE_OUTPUT  Support requests that use sepa-
					     rate input	and output buffers.
					     Sessions with this	flag set per-
					     mit requests with either a	single
					     buffer that is modified in-place,
					     or	requests with separate input
					     and output	buffers.  Sessions
					     without this flag only permit re-
					     quests with a single buffer that
					     is	modified in-place.

		      CSP_F_SEPARATE_AAD     Support requests that use a sepa-
					     rate buffer for AAD rather	than
					     providing AAD as a	region in the
					     input buffer.  Sessions with this
					     flag set permit requests with AAD
					     passed in either in a region of
					     the input buffer or in a single,
					     virtually-contiguous buffer.
					     Sessions without this flag	only
					     permit requests with AAD passed
					     in	as a region in the input buf-
					     fer.

		      CSP_F_ESN		     Support requests that use a sepa-
					     rate buffer for IPsec ESN (Ex-
					     tended Sequence Numbers).

					     Sessions with this	flag set per-
					     mit requests with IPsec ESN
					     passed in special buffer.	It is
					     required for IPsec	ESN support of
					     encrypt and authenticate mode
					     where the high-order 32 bits of
					     the sequence number are appended
					     after the Next Header (RFC	4303).

     csp_ivlen	      If either	the cipher or authentication algorithms	re-
		      quire an explicit	initialization vector (IV) or nonce,
		      this specifies the length	in bytes.  All requests	for a
		      session use the same IV length.

     csp_cipher_alg   Encryption or compression	algorithm.

     csp_cipher_klen  Length of	encryption or decryption key in	bytes.	All
		      requests for a session use the same key length.

     csp_cipher_key   Pointer to encryption or decryption key.	If all re-
		      quests for a session use request-specific	keys, this
		      field should be left as NULL.  This pointer and associ-
		      ated key must remain valid for the duration of the
		      crypto session.

     csp_auth_alg     Authentication algorithm.

     csp_auth_klen    Length of	authentication key in bytes.  If the authenti-
		      cation algorithm does not	use a key, this	field should
		      be left as zero.

     csp_auth_key     Pointer to the authentication key.  If all requests for
		      a	session	use request-specific keys, this	field should
		      be left as NULL.	This pointer and associated key	must
		      remain valid for the duration of the crypto session.

     csp_auth_mlen    The length in bytes of the digest.  If zero, the full
		      length of	the digest is used.  If	non-zero, the first
		      csp_auth_mlen bytes of the digest	are used.

RETURN VALUES
     crypto_newsession() returns a non-zero value if an	error occurs or	zero
     on	success.

     crypto_auth_hash()	and crypto_cipher() return NULL	if the request is
     valid or a	pointer	to a structure on success.

SEE ALSO
     crypto(7),	crypto(9), crypto_request(9)

BUGS
     The current implementation	of crypto_freesession does not provide a way
     for the caller to know that there are no other references to the keys
     stored in the session's associated	parameters.  This function should
     probably sleep until any in-flight	cryptographic operations associated
     with the session are completed.

FreeBSD	13.0			 June 22, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO | BUGS

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

home | help