home | help 
CRYPTO_SESSION(9)	    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 cryp-
     tographic sessions.  Sessions hold state shared across  multiple  requests.
     Active sessions are associated with a single cryptographic driver.

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

     New sessions are created by crypto_newsession().  csp describes various pa-
     rameters  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 cryp-
     tographic 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  asyn-
			   chronously.

     CRYPTOCAP_F_SOFTWARE  Request  software  drivers.	Software drivers use the
			   host CPU to perform operations.  The kernel	includes
			   a  simple,  yet  portable implementation of each sup-
			   ported algorithm in the cryptosoft(4) driver.   Addi-
			   tional  software drivers may also be available on ar-
			   chitectures which provide  instructions  designed  to
			   accelerate cryptographic operations.

     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 drivers in a
     round-robin fashion.

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

     crypto_freesession() is used to free the resources associated with the ses-
     sion cses.

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

     crypto_cipher() returns a structure describing the baseline software imple-
     mentation	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 payload.

					 The compression algorithm is  specified
					 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  speci-
					 fied in csp_auth_alg.

		      CSP_MODE_AEAD	 Authenticated	 encryption  with  addi-
					 tional data.  Decryption operations re-
					 quire 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 authentica-
					 tion digest over the request additional
					 authentication data followed by the en-
					 crypted payload.  Decryption operations
					 fail without decrypting the data if the
					 provided digest 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 at-
		      tach to a session if they support  all  of  the  requested
		      features.

		      CSP_F_SEPARATE_OUTPUT  Support  requests that use separate
					     input and output buffers.	Sessions
					     with this flag set permit	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   requests	 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, virtu-
					     ally-contiguous  buffer.	Sessions
					     without this flag only  permit  re-
					     quests  with AAD passed in as a re-
					     gion in the input buffer.

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

					     Sessions  with this flag set permit
					     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 num-
					     ber are  appended	after  the  Next
					     Header (RFC 4303).

     csp_ivlen	      If  either the cipher or authentication algorithms require
		      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 re-
		      quests for a session use the same key length.

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

     csp_auth_alg     Authentication algorithm.

     csp_auth_klen    Length of authentication key in bytes.  If the authentica-
		      tion  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 15.1			  June 22, 2020 	       CRYPTO_SESSION(9)
home | help