Size of the result of the transformation. A buffer of this size
must be available to the final and finup calls, so they can
store the resulting hash into it. For various predefined sizes,
search include/crypto/ using
git grep _DIGEST_SIZE include/crypto.

statesize

Size of the block for partial state of the transformation. A
buffer of this size must be passed to the export function as it
will save the partial state of the transformation into it. On the
other side, the import function will load the state from a
buffer of this size as well.

base

Start of data structure of cipher algorithm. The common data
structure of crypto_alg contains information common to all ciphers.
The hash_alg_common data structure now adds the hash-specific
information.

Initialize the transformation context. Intended only to initialize the
state of the HASH transformation at the beginning. This shall fill in
the internal structures used during the entire duration of the whole
transformation. No data processing happens at this point.

update

Push a chunk of data into the driver for transformation. This
function actually pushes blocks of data from upper layers into the
driver, which then passes those to the hardware as seen fit. This
function must not finalize the HASH transformation by calculating the
final message digest as this only adds more data into the
transformation. This function shall not modify the transformation
context, as this function may be called in parallel with the same
transformation object. Data processing can happen synchronously
[SHASH] or asynchronously [AHASH] at this point.

final

Retrieve result from the driver. This function finalizes the
transformation and retrieves the resulting hash from the driver and
pushes it back to upper layers. No data processing happens at this
point.

finup

Combination of update and final. This function is effectively a
combination of update and final calls issued in sequence. As some
hardware cannot do update and final separately, this callback was
added to allow such hardware to be used at least by IPsec. Data
processing can happen synchronously [SHASH] or asynchronously [AHASH]
at this point.

digest

Combination of init and update and final. This function
effectively behaves as the entire chain of operations, init,
update and final issued in sequence. Just like finup, this was
added for hardware which cannot do even the finup, but can only do
the whole transformation in one run. Data processing can happen
synchronously [SHASH] or asynchronously [AHASH] at this point.

export

Export partial state of the transformation. This function dumps the
entire state of the ongoing transformation into a provided block of
data so it can be import ‘ed back later on. This is useful in case
you want to save partial result of the transformation after
processing certain amount of data and reload this partial result
multiple times later on for multiple re-use. No data processing
happens at this point.

import

Import partial state of the transformation. This function loads the
entire state of the ongoing transformation from a provided block of
data so the transformation can continue from this point onward. No
data processing happens at this point.

setkey

Set optional key used by the hashing algorithm. Intended to push
optional key used by the hashing algorithm from upper layers into
the driver. This function can store the key in the transformation
context or can outright program it into the hardware. In the former
case, one must be careful to program the key into the hardware at
appropriate time and one must be careful that .:c:func:setkey() can be
called multiple times during the existence of the transformation
object. Not all hashing algorithms do implement this function as it
is only needed for keyed message digests. SHAx/MDx/CRCx do NOT
implement this function. HMAC(MDx)/HMAC(SHAx)/CMAC(AES) do implement
this function. This function must be called before any other of the
init, update, final, finup, digest is called. No data
processing happens at this point.

reference to the ahash_request handle that holds all information
needed to perform the cipher operation

Description

Finalize the message digest operation and create the message digest
based on all data added to the cipher handle. The message digest is placed
into the output buffer registered with the ahash_request handle.

reference to the ahash_request handle that holds all information
needed to perform the cipher operation

Description

This function is a “short-hand” for the function calls of crypto_ahash_init,
crypto_ahash_update and crypto_ahash_final. The parameters have the same
meaning as discussed for those separate three functions.

The ahash_request data structure contains all pointers to data
required for the asynchronous cipher operation. This includes the cipher
handle (which can be used by multiple ahash_request instances), pointer
to plaintext and the message digest output buffer, asynchronous callback
function, etc. It acts as a handle to the ahash_request_* API calls in a
similar way as ahash handle to the crypto_ahash_* API calls.

specify zero or an ORing of the flags
CRYPTO_TFM_REQ_MAY_BACKLOG the request queue may back log and
increase the wait queue beyond the initial maximum size;
CRYPTO_TFM_REQ_MAY_SLEEP the request processing may sleep

crypto_completion_tcompl

callback function pointer to be registered with the request handle

void*data

The data pointer refers to memory that is not used by the kernel
crypto API, but provided to the callback function for it to use. Here,
the caller can provide a reference to memory the callback function can
operate on. As the callback function is invoked asynchronously to the
related functionality, it may need to access data structures of the
related functionality which can be referenced using this pointer. The
callback function can access the memory via the “data” field in the
crypto_async_request data structure provided to the callback function.

Description

This function allows setting the callback function that is triggered once
the cipher operation completes.

The callback function is registered with the ahash_request handle and
must comply with the following template:

The size of the operational state the cipher needs during operation is
returned for the hash referenced with the cipher handle. This size is
required to calculate the memory requirements to allow the caller allocating
sufficient memory for operational state.

The operational state is defined with struct shash_desc where the size of
that data structure is to be calculated as
sizeof(struct shash_desc) + crypto_shash_descsize(alg)

This function is a “short-hand” for the function calls of crypto_shash_init,
crypto_shash_update and crypto_shash_final. The parameters have the same
meaning as discussed for those separate three functions.

Finalize the message digest operation and create the message digest
based on all data added to the cipher handle. The message digest is placed
into the output buffer. The caller must ensure that the output buffer is
large enough by using crypto_shash_digestsize.