Crate fn_dsa_vrfy

FN-DSA signature verification

This crate implements signature verification for FN-DSA. A VerifyingKey instance is created by decoding a verifying key (from its encoded format). Signatures can be verified with the verify() method on the VerifyingKey instance. verify() uses stack allocation for its internal buffers (which are not large). The same VerifyingKey can be used for verifying several signatures.

The signature process uses a domain-separation context, which is an arbitrary binary strings (up to 255 bytes in length). If no such context is required in an application, use DOMAIN_NONE (the empty context).

The message is supposed to be pre-hashed by the caller: the caller provides the hashed value, along with an identifier of the used hash function. The HASH_ID_RAW identifier can be used if the message is not actually pre-hashed, but is provided directly instead of a hash value.

FN-DSA is parameterized by a degree, which is a power of two. Standard versions use degree 512 (“level I security”) or 1024 (“level V security”); smaller degrees are deemed too weak for production use and meant only for research and testing. The degree is represented logarithmically as the logn value, such that the degree is n = 2^logn (thus, degrees 512 and 1024 correspond to logn values 9 and 10, respectively). The signature size is fixed for a given degree (see signature_size()).

WARNING

The FN-DSA standard is currently being drafted, but no version has been published yet. When published, it may differ from the exact scheme implemented in this crate, in particular with regard to key encodings, message pre-hashing, and domain separation. Key pairs generated with this crate MAY fail to be interoperable with the final FN-DSA standard. This implementation is expected to be adjusted to the FN-DSA standard when published (before the 1.0 version release).

Example usage

use fn_dsa_vrfy::{
    vrfy_key_size, signature_size, FN_DSA_LOGN_512,
    VerifyingKey, VerifyingKeyStandard,
    DOMAIN_NONE, HASH_ID_RAW
};
 
match VerifyingKeyStandard::decode(encoded_verifying_key) {
    Some(vk) => {
        if vk.verify(sig, &DOMAIN_NONE, &HASH_ID_RAW, b"message") {
            // signature is valid
        } else {
            // signature is not valid
        }
    }
    _ => {
        // could not decode verifying key
    }
}

Structs

DomainContext

When a message is signed or verified, it is accompanied with a domain separation context, which is an arbitrary sequence of bytes of length at most 255. Such a context is wrapped in a DomainContext structure.

HashIdentifier

The message for which a signature is to be generated or verified is pre-hashed by the caller and provided as a hash value along with an identifier of the used hash function. The identifier is normally an encoded ASN.1 OID. A special identifier is used for “raw” messages (i.e. not pre-hashed at all); it uses a single byte of value 0x00.

VerifyingKey512

Signature verifier for degrees (logn) 9 to 9 only.

VerifyingKey1024

Signature verifier for degrees (logn) 10 to 10 only.

VerifyingKeyStandard

Signature verifier for degrees (logn) 9 to 10 only.

VerifyingKeyWeak

Signature verifier for degrees (logn) 2 to 8 only.

Constants

DOMAIN_NONE

Empty domain separation context.

FN_DSA_LOGN_512

Symbolic constant for FN-DSA with degree 512 (logn = 9).

FN_DSA_LOGN_1024

Symbolic constant for FN-DSA with degree 1024 (logn = 10).

HASH_ID_ORIGINAL_FALCON

Hash function identifier: original Falcon design.

HASH_ID_RAW

Hash function identifier: none.

HASH_ID_SHA3_256

Hash function identifier: SHA3-256

HASH_ID_SHA3_384

Hash function identifier: SHA3-384

HASH_ID_SHA3_512

Hash function identifier: SHA3-512

HASH_ID_SHA256

Hash function identifier: SHA-256

HASH_ID_SHA384

Hash function identifier: SHA-384

HASH_ID_SHA512

Hash function identifier: SHA-512

HASH_ID_SHA512_256

Hash function identifier: SHA-512-256

HASH_ID_SHAKE128

Hash function identifier: SHAKE128

HASH_ID_SHAKE256

Hash function identifier: SHAKE256

Traits

VerifyingKey

Verifying key handler.

Functions

signature_size

Get the size (in bytes) of a signature for the provided degree (degree is n = 2^logn, with 2 <= logn <= 10).

vrfy_key_size

Get the size (in bytes) of a verifying key for the provided degree (degree is n = 2^logn, with 2 <= logn <= 10).