Crate fn_dsa_sign

FN-DSA signature generation

This crate implements signature generation for FN-DSA. A SigningKey instance is created by decoding a signing key (from its encoded format). Signatures can be generated with the sign() method on the SigningKey instance. sign() uses the instance mutably because the process uses relatively large RAM buffers which are part of the instance (to avoid oversized stack allocation on embedded systems). The same SigningKey can be used for generating several signatures; this even allows CPU savings since some computations depend only on the key and can be reused for 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 rand_core::OsRng;
use fn_dsa_sign::{
    sign_key_size, signature_size, FN_DSA_LOGN_512,
    SigningKey, SigningKeyStandard,
    DOMAIN_NONE, HASH_ID_RAW,
};
 
let mut sk = SigningKeyStandard::decode(encoded_signing_key)?;
let mut sig = vec![0u8; signature_size(sk.get_logn())];
sk.sign(&mut OsRng, &DOMAIN_NONE, &HASH_ID_RAW, b"message", &mut sig);

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.

RngError

Error type of random number generators

SigningKey512

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

SigningKey1024

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

SigningKeyStandard

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

SigningKeyWeak

Signature generator 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

CryptoRng

A marker trait used to indicate that an RngCore or BlockRngCore implementation is supposed to be cryptographically secure.

RngCore

The core of a random number generator.

SigningKey

Signing key handler and temporary buffers.

Functions

sign_key_size

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

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).