slhdsa

Experimental module of NIST FIPS-205 Stateless Hash-Based Digital Signature Standard (SLH-DSA) in V

About

SLH-DSA was a quantum resistent cryptographic digital signature standard that was approved and publicly published by NIST at August, 2024. Its availables on NIST FIPS 205.
SLH-DSA allow builds relatively big signaturue size with small key (16 - 32 bytes key). The signatures range from ±8K - ±50K depending on the type chosen.

[!NOTE] > This module wraps and written on top of SLH-DSA functionality availables on latest release > of recent OpenSSL library. Based on the history, this functionality was added in OpenSSL 3.5. > So, make sure, you have required version of OpenSSL library installed. For simple guides how > to build and install latest OpenSSL library on unix-like box, > see install-latest-ssl.md

Basic

SLH-DSA signature scheme is constructed using other hash-based signature schemes as components. SLH-DSA was comes with set of predefined parameter that describes security categories, ie:

• What is underlying hash algorithm used in the mean of process.
  The standard defines two's hash algorithm family availables, sha2 family and shake family- Security bits number of parameter set
• Whether the parameter set was designed to create relatively small signatures ('s') or to haverelatively fast signature generation ('f').
  See Table. 2 SLH-DSA parameter sets in the standard document.
  

This parameter set represented by this opaque on this module:

pub enum Kind {
    // SHA2-based family
    sha2_128s = C.NID_SLH_DSA_SHA2_128s
    sha2_128f = C.NID_SLH_DSA_SHA2_128f
    sha2_192s = C.NID_SLH_DSA_SHA2_192s
    sha2_192f = C.NID_SLH_DSA_SHA2_192f
    sha2_256s = C.NID_SLH_DSA_SHA2_256s
    sha2_256f = C.NID_SLH_DSA_SHA2_256f
    // SHAKE-based family
    shake_128s = C.NID_SLH_DSA_SHAKE_128s
    shake_128f = C.NID_SLH_DSA_SHAKE_128f
    shake_192s = C.NID_SLH_DSA_SHAKE_192s
    shake_192f = C.NID_SLH_DSA_SHAKE_192f
    shake_256s = C.NID_SLH_DSA_SHAKE_256s
    shake_256f = C.NID_SLH_DSA_SHAKE_256f
}

Example

import x.crypto.slhdsa

fn main() {
    // you can choose and pass the kind of the SLH-DSA parameter to the constructor
    opt := slhdsa.KeyOpts{
        kind: .sha2_128s
        // other options was availables
    }
    mut pv := slhdsa.PrivateKey.new(opt)!

    // Example message
    msg := 'SLH-DSA example message'.bytes()

    // Sign a message using constructed key
    sig := pv.sign(msg)!

    // Then the public key part can verify this signature
    mut pb := pv.public_key()!
    verified := pb.verify(sig, msg)!
    assert verified // true

    // release the resource
    pv.free()
    pb.free()
}

fn PrivateKey.new(opt KeyOpts) !PrivateKey

new creates a new SLH-DSA PrivateKey based on the supplied options. By default, it will create a SLH-DSA-SHA2-128s key with random generator. See enum Kind for all of availables choice's type (kind) of key. Its also support to generate keys based on the seed or private bytes through provided options. See available options in KeyOpts.

PrivateKey.new()!
PrivateKey.new(kind: .sha2_128s)

fn PublicKey.from_bytes(bytes []u8, kind Kind) !PublicKey

from_bytes creates a new PublicKey with type of supported key and bytes array. If you dont provide the bytes, ie, supplied with zero-length bytes, it will be generated with random bytes for you.

enum Kind {
	// SHA2-based family
	sha2_128s = C.NID_SLH_DSA_SHA2_128s
	sha2_128f = C.NID_SLH_DSA_SHA2_128f
	sha2_192s = C.NID_SLH_DSA_SHA2_192s
	sha2_192f = C.NID_SLH_DSA_SHA2_192f
	sha2_256s = C.NID_SLH_DSA_SHA2_256s
	sha2_256f = C.NID_SLH_DSA_SHA2_256f
	// SHAKE-based family
	shake_128s = C.NID_SLH_DSA_SHAKE_128s
	shake_128f = C.NID_SLH_DSA_SHAKE_128f
	shake_192s = C.NID_SLH_DSA_SHAKE_192s
	shake_192f = C.NID_SLH_DSA_SHAKE_192f
	shake_256s = C.NID_SLH_DSA_SHAKE_256s
	shake_256f = C.NID_SLH_DSA_SHAKE_256f
}

The enumeration of NID of SLHDSA parameters set.
See Table 2. SLH-DSA parameter sets of the Chapter 11. Parameter Sets
Each sets name indicates:

• the hash function family (SHA2 or SHAKE) that is used to instantiate the hash functions.
• the length in bits of the security parameter, in the 128, 192, and 256 respectives number.
• the mnemonic name indicates parameter to create relatively small signatures (s)or to have relatively fast signature generation (f).

struct KeyOpts {
pub mut:
	// An opaque represents the kind of SLH-DSA keys want to built.
	// See `enum Kind` for available options.
	kind Kind = .sha2_128s

	// flag, 0=random (default), 1= use seed bytes, 2 = use priv bytes, otherwise error
	flag int
	// when you set flag=1, builder will use seed bytes as a params,
	// so, make sure to pass seed bytes length != 0
	seed []u8
	// when flag=2, you should ensure private bytes length != 0
	priv []u8

	// This option below was not supported yet.
	//
	// Sets properties to be used when fetching algorithm implementations
	// used for SLH-DSA hashing operations.
	propq string
}

Configuration options used in SLH-DSA key generation.

struct PrivateKey {
	key &C.EVP_PKEY
}

PrivateKey represents SLH-DSA keypair.

fn (pv PrivateKey) sign(msg []u8, opt SignerOpts) ![]u8

sign signs the message using this key under desired options in opt.

fn (pv PrivateKey) verify(sig []u8, msg []u8, opt SignerOpts) !bool

verify verifies signature for the message msg under provided options. Its possible because of under the hood, private key is a key pair.

fn (pv PrivateKey) dump_key() !string

dump_key represents PrivateKey in human readable string.

fn (pv PrivateKey) public_key() !PublicKey

public_key gets the the public part of this private key as a PublicKey.

fn (mut pv PrivateKey) free()

free releases memory occupied by this key.

struct PublicKey {
	key &C.EVP_PKEY
}

PublicKey represents public key part from the key.

fn (pb PublicKey) verify(sig []u8, msg []u8, opt SignerOpts) !bool

verify verifies signature sig for messages msg under options provided.

fn (pb PublicKey) dump_key() !string

dump_key dumps this public key as a human readable string.

fn (mut pb PublicKey) free()

free releases memory occupied by this public key

struct SignerOpts {
pub mut:
	// optional context string up to 255 length, used in signing (verifying)
	context string

	// "message-encoding"
	// The default value of 1 uses 'Pure SLH-DSA Signature Generation'.
	// Setting it to 0 does not encode the message, which is used for testing,
	// but can also be used for 'Pre Hash SLH-DSA Signature Generation'.
	// If you set encoding to 0, you should provide the entropy.
	encoding int = 1

	// "test-entropy" used for testing to pass a optional random value.
	entropy []u8 // octet-string

	// "deterministic" integer option.
	// The default value of 0 generates a random value (using a DRBG) this is used when
	// processing the message. Setting this to 1 causes the private key seed to be used instead.
	// This value is ignored if "test-entropy" is set.
	deterministic int
}

Configurations parameters used for signing (and or verifying)