Crate mldsa_native_rs 

mldsa-native-rs

This crate is EXPERIMENTAL. Use at your own peril. (i.e., DON’T!)

FFI bindings and an optional Rust wrapper for the mldsa-native library.

Repository

The git repository for this project uses git submodules.

When cloning, we recommend to use:

git clone --recursive

Alternatively, you might need to run

git submodule update --init --recursive

to ensure submodules are fetched and updated before being able to build from source.

Features flags

• wrapper: include a wrapper module that provides Rust types, traits, and wrapper functions around the FFI items.
• rand: include keygen and signing functions in the wrapper that generate their own random data using the rand crate.
• extern-C-randombytes: (disabled by default) if enabled exports a default implementation of the randombytes function required by the backend implementation.
• native (opt-in): builds the optimized backend from mldsa-native instead of its portable implementation. When enabled, this crate’s build.rs autodetects the target’s capabilities and passes a corresponding set of defines to mldsa-native, which is compiled as part of the build. What those defines compile to on a given target is determined by mldsa-native, not by this crate. For many targets this produces an optimized build; for some, the detected define combination may fall back to the portable implementation or fail to compile. This crate makes no guarantees beyond those of mldsa-native. If the build fails, disable this feature to use the portable implementation.
• built_info: (opt-in) include a built_info module exposing build-time metadata via the [built][crate:built] crate. Provides a BuiltInfo struct with the package name and version, target/host triples, build profile, rustc version, enabled features, and git metadata (commit hash, HEAD ref, and dirty state) when built from a git repository. When the native feature is also enabled, BuiltInfo additionally reports the detected runtime CPU capabilities.

About randombytes

Consumers of this crate must provide a randombytes function whose exported symbol matches the value of crate::randombytes::RANDOMBYTES_INTERNAL_NAME. The crate::randombytes module provides helpers and further details.

This function is at the FFI boundary with the backend C implementation, and must adhere to the expected C ABI and semantics.

Consumers who do not wish to provide their own implementation may enable both the rand and extern-C-randombytes Cargo features. This makes the crate self-contained by exporting a default implementation backed by rand::fill.

Security

The randombytes function is a critical cryptographic dependency. It must produce fresh, unpredictable bytes from a cryptographically secure random number generator (CSPRNG).

Any weakness in the provided randomness source directly compromises the security of all non-deterministic operations performed by mldsa-native.

Re-exports

pub use signature;

Modules

ffi

Bindings to the underlying functions and constants from mldsa-native.

parameter_sets

Parameter sets and related constants.

randombytes

FFI bridge for the randombytes symbol expected by mldsa-native.

transcoding

Utilities for transcoding between types and byte slices.

Structs

FFIError

Error returned by the backend implementation.

Signature

Represents a signature using the specified parameter set.

SigningKey

Secret key for signature generation.

TranscodingError

Error type for transcoding operations.

VerifyingKey

Public key for signature verification.

Traits

AsBytes

Trait for types that can be represented as a byte slice.

ContextSigner

Sign the given message, using the provided context string.

FromBytes

Fallible parse from a byte slice.

ParameterSet

Trait implemented by each ML-DSA parameter set.

SeedLen

Trait for types that provide the length of the seed.

SeededContextSigner

Sign the given message, using the provided context string and the provided seed for the signing process.

SeededSigner

Sign the given message, using the provided seed for the signing process.

SignatureEncoding

Support for decoding/encoding signatures as bytes.

SignatureLen

Trait for types that provide the length of the signature.

Signer

Sign the provided message bytestring using Self (e.g. a cryptographic key or connection to an HSM), returning a digital signature.

SigningKeyLen

Trait for types that provide the length of the secret (signing) key.

Verifier

Verify the provided message bytestring using Self (e.g. a public key).

VerifyingKeyLen

Trait for types that provide the length of the public (verifying) key.

Functions

keygen

Generate a keypair.

keygen_from_seed

Generate a keypair from the given seed.

Type Aliases

MlDsaSeed

A seed for a ML-DSA signing key.

PublicKey

SecretKey