10.3 Extendable-output functions (XOF)¶

An eXtendable-Output Function (XOF) is similar to a cryptographic hash, transforming an arbitrary amount of input data into pseudorandom output. Unlike hash algorithms, an XOF can produce an arbitrary amount of output.

XOF algorithms are often used as a building block in other algorithms, as they are suitable for use in hashing, key-derivation, and as a pseudorandom function (PRF).

In the Crypto API, support for XOF algorithms is provided by the psa_xof_operation_t multi-part operation, and XOF algorithm identifiers. A multi-part XOF operation is used as follows:

Initialize the psa_xof_operation_t object to zero, or by assigning the value of the associated macro PSA_XOF_OPERATION_INIT.
Call psa_xof_setup() to specify the required XOF algorithm.
If the algorithm has a context, call psa_xof_set_context() to provide the context value.
Call the psa_xof_update() function on successive chunks of the input data.
After input is complete, call psa_xof_output() one or more times to extract successive chunks of output.
When output is complete, call psa_xof_abort() to end the operation.

To abort the operation or recover from an error, call psa_xof_abort().

Note

For an XOF algorithm:

The result does not depend on how the overall input is fragmented. For example, calling psa_xof_update() twice with input \(i_1\) and \(i_2\) has the same effect as calling psa_xof_update() once with the concatenation \(i_1\ ||\ i_2\).
The overall output does not depend on how the output is fragmented. If the output is considered as a stream of bytes, psa_xof_output() is an operation that reads bytes in sequence from the stream of data.

10.3.1 XOF algorithms¶

`PSA_ALG_SHAKE128` (macro)¶

The SHAKE128 XOF algorithm.

Added in version 1.4.

#define PSA_ALG_SHAKE128 ((psa_algorithm_t)0x0D000100)

SHAKE128 is one of the KECCAK family of algorithms.

SHAKE128 is defined in FIPS Publication 202: SHA-3 Standard: Permutation-Based Hash and Extendable-Output Functions [FIPS202].

Some fixed output-length hash algorithms based on SHAKE128 are also provided in the Crypto API:

PSA_ALG_SHAKE128_256 — defined in PSA Certified Crypto API 1.4 PQC Extension [PSA-PQC]

`PSA_ALG_SHAKE256` (macro)¶

The SHAKE256 XOF algorithm.

Added in version 1.4.

#define PSA_ALG_SHAKE256 ((psa_algorithm_t)0x0D000200)

SHAKE256 is one of the KECCAK family of algorithms.

SHAKE256 is defined in [FIPS202].

Some fixed output-length hash algorithms based on SHAKE256 are also provided in the Crypto API:

PSA_ALG_SHAKE256_192 — defined in [PSA-PQC]
PSA_ALG_SHAKE256_256 — defined in [PSA-PQC]
PSA_ALG_SHAKE256_512

`PSA_ALG_ASCON_XOF128` (macro)¶

The Ascon-XOF128 XOF algorithm.

Added in version 1.4.

#define PSA_ALG_ASCON_XOF128 ((psa_algorithm_t)0x0D000300)

Ascon-XOF128 is defined in NIST Special Publication 800-232: Ascon-Based Lightweight Cryptography Standards for Constrained Devices [SP800-232] §5.2.

Note

To use the Ascon-Hash256 hash algorithm, see PSA_ALG_ASCON_HASH256.

`PSA_ALG_ASCON_CXOF128` (macro)¶

The Ascon-CXOF128 XOF algorithm, with context.

Added in version 1.4.

#define PSA_ALG_ASCON_CXOF128 ((psa_algorithm_t)0x0D008300)

Ascon-CXOF128 is defined in NIST Special Publication 800-232: Ascon-Based Lightweight Cryptography Standards for Constrained Devices [SP800-232] §5.3.

The context value must be provided by calling psa_xof_set_context() on the XOF mluti-part operation, before providing any input data.

10.3.2 Multi-part XOF operations¶

`psa_xof_operation_t` (typedef)¶

The type of the state object for multi-part XOF operations.

Added in version 1.4.

typedef /* implementation-defined type */ psa_xof_operation_t;

Before calling any function on an XOF operation object, the application must initialize it by any of the following means:

Set the object to all-bits-zero, for example:

psa_xof_operation_t operation;
memset(&operation, 0, sizeof(operation));

Initialize the object to logical zero values by declaring the object as static or global without an explicit initializer, for example:
```
static psa_xof_operation_t operation;
```
Initialize the object to the initializer PSA_XOF_OPERATION_INIT, for example:
```
psa_xof_operation_t operation = PSA_XOF_OPERATION_INIT;
```
Assign the result of the function psa_xof_operation_init() to the object, for example:
```
psa_xof_operation_t operation;
operation = psa_xof_operation_init();
```

This is an implementation-defined type. Applications that make assumptions about the content of this object will result in implementation-specific behavior, and are non-portable.

`PSA_XOF_OPERATION_INIT` (macro)¶

This macro returns a suitable initializer for an XOF operation object of type psa_xof_operation_t.

Added in version 1.4.

#define PSA_XOF_OPERATION_INIT /* implementation-defined value */

`psa_xof_operation_init` (function)¶

Return an initial value for an XOF operation object.

Added in version 1.4.

psa_xof_operation_t psa_xof_operation_init(void);

Returns: psa_xof_operation_t

`psa_xof_setup` (function)¶

Set up an XOF operation.

Added in version 1.4.

psa_status_t psa_xof_setup(psa_xof_operation_t * operation,
                           psa_algorithm_t alg);

Parameters

operation: The operation object to set up. It must have been initialized as per the documentation for psa_xof_operation_t and not yet in use.
alg: The XOF algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_XOF(alg) is true.

Returns: psa_status_t

PSA_SUCCESS

Success. The operation is now active.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

alg is not an XOF algorithm.

PSA_ERROR_NOT_SUPPORTED

alg is not supported or is not an XOF algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The sequence of operations to generate XOF output is as follows:

Allocate an XOF operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_xof_operation_t, e.g. PSA_XOF_OPERATION_INIT.
Call psa_xof_setup() to specify the algorithm.
For an XOF algorithm that has a context, call psa_xof_set_context() to provide the context.
Call psa_xof_update() zero, one, or more times, passing a fragment of the input each time.
To extract XOF output data, call psa_xof_output() one or more times.

After a successful call to psa_xof_setup(), the operation is active, and the application must eventually terminate the operation with a call to psa_xof_abort().

If psa_xof_setup() returns an error, the operation object is unchanged. If a subsequent function call with an active operation returns an error, the operation enters an error state.

To abandon an active operation, or reset an operation in an error state, call psa_xof_abort().

See Multi-part operations.

`psa_xof_set_context` (function)¶

Provide a context for a multi-part XOF operation.

Added in version 1.4.

psa_status_t psa_xof_set_context(psa_xof_operation_t * operation,
                                 const uint8_t * context,
                                 size_t context_length);

Parameters

operation: Active XOF operation.
context: Buffer containing the input fragment.
context_length: Size of the context buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active, and no call to psa_xof_set_context(), psa_xof_output(), or psa_xof_output() has been made.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The following conditions can result in this error:

The algorithm does not support a context value. See PSA_ALG_XOF_HAS_CONTEXT().
The context value is not valid for the XOF algorithm.

PSA_ERROR_NOT_SUPPORTED

The context value is not supported by this implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

This function sets the context value in a multi-part XOF operation, when using an XOF algorithm that has a context parameter.

The application must call psa_xof_setup() before calling this function. For an XOF algorithm with a context parameter, this function must be called immediately after psa_xof_setup(), before calling any other function on the XOF operation.

This function must not be called if the XOF algorithm does not have a context parameter. The macro PSA_ALG_XOF_HAS_CONTEXT() can be used to determine if a context value is required for the XOF algorithm.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_xof_abort().

`psa_xof_update` (function)¶

Add input to a multi-part XOF operation.

Added in version 1.4.

psa_status_t psa_xof_update(psa_xof_operation_t * operation,
                            const uint8_t * input,
                            size_t input_length);

Parameters

operation: Active XOF operation.
input: Buffer containing the input fragment.
input_length: Size of the input buffer in bytes.

Returns: psa_status_t

PSA_SUCCESS

Success.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active, and no call to psa_xof_output() has been made.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT

The total input for the operation is too large for the XOF algorithm.

PSA_ERROR_NOT_SUPPORTED

The total input for the operation is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

The application must call psa_xof_setup() before calling this function.

This function can be called zero, one, or more times to provide input for the XOF. The input to the XOF is only finalized on the first call to psa_xof_output().

psa_xof_update() cannot be called on an XOF operation once psa_xof_output() has been called on the operation.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_xof_abort().

`psa_xof_output` (function)¶

Extract data from an XOF operation.

Added in version 1.4.

psa_status_t psa_xof_output(psa_xof_operation_t * operation,
                            uint8_t * output,
                            size_t output_length);

Parameters

operation: Active XOF operation.
output: Buffer where the output will be written.
output_length: Number of bytes to output.

Returns: psa_status_t

PSA_SUCCESS

Success. The first output_length bytes of output contain the data.

PSA_ERROR_BAD_STATE

The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

Description

This function calculates output bytes from the XOF algorithm and returns those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller.

The application must call psa_xof_setup() and supply all input data, using calls to psa_xof_update(), before calling this function. The input to the XOF is finalized on the first call to psa_xof_output() before data is extracted from the XOF.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_xof_abort().

`psa_xof_abort` (function)¶

Abort an XOF operation.

Added in version 1.4.

psa_status_t psa_xof_abort(psa_xof_operation_t * operation);

Parameters

operation: Initialized XOF operation.

Returns: psa_status_t

PSA_SUCCESS: Success. The operation object can now be discarded or reused.
PSA_ERROR_BAD_STATE: The library requires initializing by a call to psa_crypto_init().
PSA_ERROR_COMMUNICATION_FAILURE
PSA_ERROR_CORRUPTION_DETECTED

Description

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_xof_setup() again.

This function can be called any time after the operation object has been initialized by one of the methods described in psa_xof_operation_t.

In particular, calling psa_xof_abort() after the operation has been terminated by a call to psa_xof_abort() is safe and has no effect.

10.3.3 Support macros¶

`PSA_ALG_XOF_HAS_CONTEXT` (macro)¶

Whether the specified XOF algorithm has a context parameter.

Added in version 1.4.

#define PSA_ALG_XOF_HAS_CONTEXT(alg) /* specification-defined value */

Parameters

alg: An XOF algorithm identifier: a value of type psa_algorithm_t such that PSA_ALG_IS_XOF(alg) is true.

Returns

1 if alg is an XOF algorithm that has a context parameter. 0 if alg is an XOF algorithm that does not have a context parameter. This macro can return either 0 or 1 if alg is not a supported XOF algorithm identifier.

10.3 Extendable-output functions (XOF)¶

10.3.1 XOF algorithms¶

PSA_ALG_SHAKE128 (macro)¶

PSA_ALG_SHAKE256 (macro)¶

PSA_ALG_ASCON_XOF128 (macro)¶

PSA_ALG_ASCON_CXOF128 (macro)¶

10.3.2 Multi-part XOF operations¶

psa_xof_operation_t (typedef)¶

PSA_XOF_OPERATION_INIT (macro)¶

psa_xof_operation_init (function)¶

psa_xof_setup (function)¶

psa_xof_set_context (function)¶

psa_xof_update (function)¶

psa_xof_output (function)¶

psa_xof_abort (function)¶

10.3.3 Support macros¶

PSA_ALG_XOF_HAS_CONTEXT (macro)¶

`PSA_ALG_SHAKE128` (macro)¶

`PSA_ALG_SHAKE256` (macro)¶

`PSA_ALG_ASCON_XOF128` (macro)¶

`PSA_ALG_ASCON_CXOF128` (macro)¶

`psa_xof_operation_t` (typedef)¶

`PSA_XOF_OPERATION_INIT` (macro)¶

`psa_xof_operation_init` (function)¶

`psa_xof_setup` (function)¶

`psa_xof_set_context` (function)¶

`psa_xof_update` (function)¶

`psa_xof_output` (function)¶

`psa_xof_abort` (function)¶

`PSA_ALG_XOF_HAS_CONTEXT` (macro)¶