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

FreeBSD Manual Pages

  
 
  

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

NAME
     crypto_driver -- interface	for symmetric cryptographic drivers

SYNOPSIS
     #include <opencrypto/cryptodev.h>

     void
     crypto_copyback(struct cryptop *crp, int off, int size, const void	*src);

     void
     crypto_copydata(struct cryptop *crp, int off, int size, void *dst);

     void
     crypto_done(struct	cryptop	*crp);

     int32_t
     crypto_get_driverid(device_t dev, size_t session_size, int	flags);

     void *
     crypto_get_driver_session(crypto_session_t	crypto_session);

     void
     crypto_read_iv(struct cryptop *crp, void *iv);

     int
     crypto_unblock(uint32_t driverid, int what);

     int
     crypto_unregister_all(uint32_t driverid);

     int
     CRYPTODEV_FREESESSION(device_t dev, crypto_session_t crypto_session);

     int
     CRYPTODEV_NEWSESSION(device_t dev,	crypto_session_t crypto_session,
	 const struct crypto_session_params *csp);

     int
     CRYPTODEV_PROBESESSION(device_t dev,
	 const struct crypto_session_params *csp);

     int
     CRYPTODEV_PROCESS(device_t	dev, struct cryptop *crp, int flags);

     void
     hmac_init_ipad(struct auth_hash *axf, const char *key, int	klen,
	 void *auth_ctx);

     void
     hmac_init_opad(struct auth_hash *axf, const char *key, int	klen,
	 void *auth_ctx);

DESCRIPTION
     Symmetric cryptographic drivers process cryptographic requests submitted
     to	sessions associated with the driver.

     Cryptographic drivers call	crypto_get_driverid() to register with the
     cryptographic framework.  dev is the device used to service requests.
     The CRYPTODEV() methods are defined in the	method table for the device
     driver attached to	dev.  session_size specifies the size of a driver-spe-
     cific per-session structure allocated by the cryptographic	framework.
     flags is a	bitmask	of properties about the	driver.	 Exactly one of
     CRYPTOCAP_F_SOFTWARE or CRYPTOCAP_F_HARDWARE must be specified.
     CRYPTOCAP_F_SOFTWARE should be used for drivers which process requests
     using host	CPUs.  CRYPTOCAP_F_HARDWARE should be used for drivers which
     process requests on separate co-processors.  CRYPTOCAP_F_SYNC should be
     set for drivers which process requests synchronously in
     CRYPTODEV_PROCESS().  CRYPTOCAP_F_ACCEL_SOFTWARE should be	set for	soft-
     ware drivers which	use accelerated	CPU instructions.
     crypto_get_driverid() returns an opaque driver id.

     crypto_unregister_all() unregisters a driver from the cryptographic
     framework.	 If there are any pending operations or	open sessions, this
     function will sleep.  driverid is the value returned by an	earlier	call
     to	crypto_get_driverid().

     When a new	session	is created by crypto_newsession(),
     CRYPTODEV_PROBESESSION() is invoked by the	cryptographic framework	on
     each active driver	to determine the best driver to	use for	the session.
     This method should	inspect	the session parameters in csp.	If a driver
     does not support requests described by csp, this method should return an
     error value.  If the driver does support requests described by csp, it
     should return a negative value.  The framework prefers drivers with the
     largest negative value, similar to	DEVICE_PROBE(9).  The following	values
     are defined for non-error return values from this method:

     CRYPTODEV_PROBE_HARDWARE	     The driver	processes requests via a co-
				     processor.

     CRYPTODEV_PROBE_ACCEL_SOFTWARE  The driver	processes requests on the host
				     CPU using optimized instructions such as
				     AES-NI.

     CRYPTODEV_PROBE_SOFTWARE	     The driver	processes requests on the host
				     CPU.

     This method should	not sleep.

     Once the framework	has chosen a driver for	a session, the framework in-
     vokes the CRYPTODEV_NEWSESSION() method to	initialize driver-specific
     session state.  Prior to calling this method, the framework allocates a
     per-session driver-specific data structure.  This structure is initial-
     ized with zeroes, and its size is set by the session_size passed to
     crypto_get_driverid().  This method can retrieve a	pointer	to this	data
     structure by passing crypto_session to crypto_get_driver_session().  Ses-
     sion parameters are described in csp.

     This method should	not sleep.

     CRYPTODEV_FREESESSION() is	invoked	to release any driver-specific state
     when a session is destroyed.  The per-session driver-specific data	struc-
     ture is explicitly	zeroed and freed by the	framework after	this method
     returns.  If a driver requires no additional tear-down steps, it can
     leave this	method undefined.

     This method should	not sleep.

     CRYPTODEV_PROCESS() is invoked for	each request submitted to an active
     session.  This method can either complete a request synchronously or
     schedule it to be completed asynchronously, but it	must not sleep.

     If	this method is not able	to complete a request due to insufficient re-
     sources such as a full command queue, it can defer	the request by return-
     ing ERESTART.  The	request	will be	queued by the framework	and retried
     once the driver releases pending requests via crypto_unblock().  Any re-
     quests submitted to sessions belonging to the driver will also be queued
     until crypto_unblock() is called.

     If	a driver encounters errors while processing a request, it should re-
     port them via the crp_etype field of crp rather than returning an error
     directly.

     flags may be set to CRYPTO_HINT_MORE if there are additional requests
     queued for	this driver.  The driver can use this as a hint	to batch com-
     pletion interrupts.  Note that these additional requests may be from dif-
     ferent sessions.

     crypto_get_driver_session() returns a pointer to the driver-specific per-
     session data structure for	the session crypto_session.  This function can
     be	used in	the CRYPTODEV_NEWSESSION(), CRYPTODEV_PROCESS(), and
     CRYPTODEV_FREESESSION() callbacks.

     crypto_copydata() copies size bytes out of	the input buffer for crp into
     a local buffer pointed to by dst.	The bytes are read starting at an off-
     set of off	bytes in the request's input buffer.

     crypto_copyback() copies size bytes from the local	buffer pointed to by
     src into the output buffer	for crp.  The bytes are	written	starting at an
     offset of off bytes in the	request's output buffer.

     crypto_read_iv() copies the IV or nonce for crp into the local buffer
     pointed to	by iv.

     A driver calls crypto_done() to mark the request crp as completed.	 Any
     errors should be set in crp_etype prior to	calling	this function.

     If	a driver defers	a request by returning ERESTART	from CRYPTO_PROCESS,
     the framework will	queue all requests for the driver until	the driver
     calls crypto_unblock() to indicate	that the temporary resource shortage
     has been relieved.	 For example, if a driver returns ERESTART due to a
     full command ring,	it would invoke	crypto_unblock() from a	command	com-
     pletion interrupt that makes a command ring entry available.  driverid is
     the value returned	by crypto_get_driverid().  what	indicates which	types
     of	requests the driver is able to handle again:

     CRYPTO_SYMQ   indicates that the driver is	able to	handle symmetric re-
		   quests passed to CRYPTODEV_PROCESS().

     CRYPTO_ASYMQ  indicates that the driver is	able to	handle asymmetric re-
		   quests passed to CRYPTODEV_KPROCESS().

     hmac_init_ipad() prepares an authentication context to generate the inner
     hash of an	HMAC.  axf is a	software implementation	of an authentication
     algorithm such as the value returned by crypto_auth_hash().  key is a
     pointer to	a HMAC key of klen bytes.  auth_ctx points to a	valid authen-
     tication context for the desired algorithm.  The function initializes the
     context with the supplied key.

     hmac_init_opad() is similar to hmac_init_ipad() except that it prepares
     an	authentication context to generate the outer hash of an	HMAC.

RETURN VALUES
     crypto_apply() returns the	return value from the caller-supplied callback
     function.

     crypto_contiguous_subsegment() returns a pointer to a contiguous segment
     or	NULL.

     crypto_get_driverid() returns a driver identifier on success or -1	on er-
     ror.

     crypto_unblock(), crypto_unregister_all(),	CRYPTODEV_FREESESSION(),
     CRYPTODEV_NEWSESSION(), and CRYPTODEV_PROCESS() return zero on success or
     an	error on failure.

     CRYPTODEV_PROBESESSION() returns a	negative value on success or an	error
     on	failure.

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

FreeBSD	13.0			 June 9, 2020			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | SEE ALSO

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

home | help