verification.h File Reference

Public API for the XMSS verification library. More...

#include "opaque_structures.h"
#include "structures.h"
#include "types.h"

Include dependency graph for verification.h:

Go to the source code of this file.

Macros
#define	XMSS_VERIFICATION_H_INCLUDED
	Include guard.

Functions
XmssError	xmss_verification_init (XmssVerificationContext *context, const XmssPublicKey *public_key, const XmssSignature *signature, size_t signature_length)
	Initialize a context for signature verification. More...
XmssError	xmss_verification_update (XmssVerificationContext *context, const uint8_t *part, size_t part_length, const uint8_t *volatile *part_verify)
	Update the verification context with the next chunk of the message. More...
XmssError	xmss_verification_check (XmssVerificationContext *context, const XmssPublicKey *public_key)
	Perform a single validation of the message signature. More...

Detailed Description

Public API for the XMSS verification library.

Function Documentation

xmss_verification_check()

XmssError xmss_verification_check	(	XmssVerificationContext *	context,
		const XmssPublicKey *	public_key
	)

Perform a single validation of the message signature.

When all message parts have been processed with xmss_verification_update(), this function performs a single (non-redundant) validation of the signature. This function may be called multiple times to provide fault injection tolerance.

Provide the same pointer to the public key that was also provided to xmss_verification_init(). This function will verify that the two copies of the pointer value match, such that a single pointer manipulation cannot be used by an attacker to spoof the public key.

Parameters

[out]	context	The context for the signature verification.
[in]	public_key	The public key to verify the signature against. This is used to mitigate fault injection.

Return values

XMSS_OKAY	The signature is valid.
XMSS_ERR_NULL_POINTER	A NULL pointer was passed.
XMSS_ERR_BAD_CONTEXT	context was not initialized correctly.
XMSS_ERR_INVALID_SIGNATURE	The signature did not pass the verification.
XMSS_ERR_FAULT_DETECTED	A bit error was detected, or public_key does not match the public key provided to xmss_verification_init(). (Note that bit errors can also cause different errors or segfaults.)

xmss_verification_init()

XmssError xmss_verification_init	(	XmssVerificationContext *	context,
		const XmssPublicKey *	public_key,
		const XmssSignature *	signature,
		size_t	signature_length
	)

Initialize a context for signature verification.

The context stores the pointers to the public key and the signature. It is the caller's responsibility to keep the pointed-to objects available and constant for every call that uses the context. To reduce memory usage, the objects themselves are not copied into the context.

Parameters

[out]	context	The context for the signature verification.
[in]	public_key	The public key to verify signature against.
[in]	signature	The signature over the message that needs to be verified.
[in]	signature_length	The length of signature in bytes.

Return values

XMSS_OKAY	context was initialized successfully.
XMSS_ERR_NULL_POINTER	A NULL pointer was passed.
XMSS_ERR_INVALID_ARGUMENT	The parameter set of public_key is not supported.
XMSS_ERR_INVALID_SIGNATURE	signature cannot be valid, either because the parameter set of signature does not match public_key, or signature_length is incorrect.

xmss_verification_update()

XmssError xmss_verification_update	(	XmssVerificationContext *	context,
		const uint8_t *	part,
		size_t	part_length,
		const uint8_t *volatile *	part_verify
	)

Update the verification context with the next chunk of the message.

When it isn't practical to hold the entire message in memory, this function can be used to process the message in chunks.

When fault injection tolerance is required, provide a non-NULL part_verify parameter. After this function completes successfully, compare the value returned in *part_verify with the original message part pointer.

Parameters

[in,out]	context	The context for the verification.
[in]	part	The next part of the message. May be NULL if part_length is 0.
[in]	part_length	The length of part in bytes. For optimal performance, this should be a multiple of the hash function's block size (64 bytes for SHA256, 136 for SHAKE256_256) if possible, but this is not required.
[out]	part_verify	(optional, may be NULL) Outputs a copy of part to verify the correct message was processed. This can be used to mitigate fault injections.

Return values

XMSS_OKAY	context was updated successfully.
XMSS_ERR_NULL_POINTER	A NULL pointer was passed.
XMSS_ERR_BAD_CONTEXT	Either context was not initialized correctly, or xmss_verification_check() was already called.
XMSS_ERR_FAULT_DETECTED	A bit error was detected. (Note that bit errors can also cause different errors or segfaults.)