Crate hbs_lms

This library implements the Leighton-Micali-Signature scheme, as defined in the RFC 8554.

It is a post-quantum secure algorithm that can be used to generate digital signatures. NIST has published recommendations for this algorithm in: NIST Recommendations for Stateful Hash-Based Signatures

This crate can be used together with the signature::SignerMut and signature::Verifier traits.

Example

use rand::{rngs::OsRng, RngCore};
use tinyvec::ArrayVec;
use hbs_lms::{keygen, HssParameter, LmotsAlgorithm, LmsAlgorithm,
    Signature, signature::{SignerMut, Verifier},
    Sha256_256, HashChain, Seed,
};

let message: [u8; 7] = [42, 84, 34, 12, 64, 34, 32];

// Generate keys for a 2-level HSS system (RootTree W1/H5, ChildTree W2/H5)
let hss_parameter = [
        HssParameter::<Sha256_256>::new(LmotsAlgorithm::LmotsW1, LmsAlgorithm::LmsH5),
        HssParameter::<Sha256_256>::new(LmotsAlgorithm::LmotsW2, LmsAlgorithm::LmsH5),
];

let mut seed = Seed::default();
OsRng.fill_bytes(seed.as_mut_slice());
let aux_data = None;

let (mut signing_key, verifying_key) =
    hbs_lms::keygen::<Sha256_256>(&hss_parameter, &seed, aux_data).unwrap();

let signature = signing_key.try_sign(&message).unwrap();

let valid_signature = verifying_key.verify(&message, &signature);

assert_eq!(valid_signature.is_ok(), true);

Environment Variables

To adapt the internals of the crate, the user can set the following environment variables:

Adapting the crate in general

These three environment variables listed below, adapt the internals of the crate and can be used to reduce the required stack size. The values are used to set the maximum size of the arrays used for computation and storing intermediate values.

Any change limits the functionality of this crate, as no longer all possible parameters are supported! (For example setting HBS_LMS_MAX_ALLOWED_HSS_LEVELS to 1 allows only for a single tree.)

The length of the tree height and the winternitz parameter arrays must match the value of the HSS levels.

Name	Default	Range of Values	Description
HBS_LMS_MAX_ALLOWED_HSS_LEVELS	8	1..8	Max. tree count for HSS
HBS_LMS_TREE_HEIGHTS	[25; 8]	LmsAlgorithm	Max. Tree Height for each tree
HBS_LMS_WINTERNITZ_PARAMETERS	[1; 8]	LmotsAlgorithm	Min. Winternitz Parameter for each tree

Reducing the HSS levels or the values of the tree heights lead to a reduced stack usage. For the values of the Winternitz parameter the inverse must be applied, as higher Winternitz parameters reduce the stack usage.

Adapting wrt the ‘fast_verify’ feature

The ‘fast_verify’ features enables this crate to sign fast verifiable signatures. The drawback is more computative effort on the side of the signer. With the these two environment variables listed below, the user can adapt effect.

Name	Default	Description
HBS_LMS_MAX_HASH_OPTIMIZATIONS	10_000	Try count to optimize the hash
HBS_LMS_THREADS	1	Thread count to split the effort

If the crate is compiled with the std library, the effort of the generation of fast verifiable signatures can be split to multiple threads using the HBS_LMS_THREADS.

Re-exports

• pub use signature;

Structs

• HashChainData
• HssParameter
  Specify Winternitz Parameter (LmotsAlgorithm) and Tree Height (LmsAlgorithm) for one HSS Level. An array is passed to the crate::keygen function describing each HSS Level respectively.
• Sha256_128
  Extension of sha2::Sha256, which can be passed into the library, as it implements the HashChain trait.
• Sha256_192
  Extension of sha2::Sha256, which can be passed into the library, as it implements the HashChain trait.
• Sha256_256
  Extension of sha2::Sha256, which can be passed into the library, as it implements the HashChain trait.
• Shake256_128
  Extension of sha3::Shake256, which can be passed into the library, as it implements the HashChain trait.
• Shake256_192
  Extension of sha3::Shake256, which can be passed into the library, as it implements the HashChain trait.
• Shake256_256
  Extension of sha3::Shake256, which can be passed into the library, as it implements the HashChain trait.
• Signature
  Implementation of signature::Signature.
• SigningKey
  Implementation of SignerMut using Signature.
• VerifierSignature
  No-copy friendly alternative to Signature by using a reference to a slice of bytes (for verification only!).
• VerifyingKey
  Implementation of Verifier using Signature or VerifierSignature.

Enums

• LmotsAlgorithm
  Specifies the used Winternitz parameter.
• LmsAlgorithm
  Specifies the used Tree height.

Traits

• HashChain
  This trait is used inside the library to generate hashes. Default implementations are available with [sha256::Sha256] and [shake256::Shake256]. It can be used to outsource calculations to hardware accelerators.

Functions

• keygen
  Generate SigningKey and VerifyingKey.
• sign
  Generate a Signature.
• verify
  Verify a signature (Signature or VerifierSignature).