Manual Pages  — CRYPTO_DRIVER

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 invokes 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 initialized 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(). Session 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 structure 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 resources such as a full command queue, it can defer the request by returning ERESTART. The request will be queued by the framework and retried once the driver releases pending requests via crypto_unblock(). Any requests 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 report 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 completion interrupts. Note that these additional requests may be from different 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 offset 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 completion 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 requests passed to CRYPTODEV_PROCESS().
CRYPTO_ASYMQ
	indicates that the driver is able to handle asymmetric requests 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 authentication 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.