You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This directory contains minimal examples demonstrating how you can use mldsa-native.
6
+
7
+
## Basic
8
+
9
+
See [basic](basic) for a basic example of how to build a single instance of mldsa-native.
10
+
11
+
## Basic_deterministic
12
+
13
+
See [basic_deterministic](basic_deterministic) for a basic example of how to build a single instance of mldsa-native without `randombytes()` implementation. This allows users to build mldsa-native using only the deterministic API when randomized functions are not required.
14
+
## Multi-level build (C only)
15
+
16
+
See [multilevel_build](multilevel_build) for an example of how to build one instance of mldsa-native per security level,
17
+
in such a way that level-independent code is shared.
18
+
19
+
## Multi-level build (with native code)
20
+
21
+
See [multilevel_build_native](multilevel_build_native) for an example of how to build one instance of mldsa-native per
22
+
security level, in such a way that level-independent code is shared, and leveraging the native backends.
23
+
24
+
## Custom FIPS202 implementation
25
+
26
+
See [bring_your_own_fips202](bring_your_own_fips202) for an example of how to use mldsa-native with your own FIPS-202
27
+
implementation.
28
+
29
+
## Custom FIPS202 implementation (static state variant)
30
+
31
+
See [bring_your_own_fips202_static](bring_your_own_fips202_static) for an example of how to use mldsa-native with a
32
+
custom FIPS-202 implementation using a static state. This variant demonstrates the serial-only FIPS-202 configuration
33
+
(`MLD_CONFIG_SERIAL_FIPS202_ONLY`).
34
+
35
+
## Custom config + custom FIPS-202 backend
36
+
37
+
See [custom_backend](custom_backend) for an example of how to use mldsa-native with a custom configuration file and a
38
+
custom FIPS-202 backend.
39
+
40
+
## Monobuild (C only)
41
+
42
+
See [monolithic_build](monolithic_build) for an example of how to build mldsa-native (with C backend) from a single
43
+
auto-generated compilation unit.
44
+
45
+
## Multi-level monobuild (C only)
46
+
47
+
See [monolithic_build_multilevel](monolithic_build_multilevel) for an example of how to build all security levels of
48
+
mldsa-native (with C backend) inside a single compilation unit, sharing the level-independent code.
49
+
50
+
## Multi-level monobuild (with native code)
51
+
52
+
See [monolithic_build_multilevel_native](monolithic_build_multilevel_native) for an example of how to build all security
53
+
levels of mldsa-native inside a single compilation unit, sharing the level-independent code, while also linking in assembly
This directory contains a minimal example for how to build mldsa-native.
5
+
This directory contains a minimal example for how to build mldsa-native for a single security level.
6
6
7
-
## Components
8
-
9
-
An application using mldsa-native as-is needs to include the following components:
10
-
11
-
1. mldsa-native source tree, including [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202).
12
-
2. A secure pseudo random number generator, implementing [`randombytes.h`](../../mldsa/src/randombytes.h).
13
-
3. The application source code
7
+
## Use Case
14
8
15
-
**WARNING:** The `randombytes()` implementation used here is for TESTING ONLY. You MUST NOT use this implementation
16
-
outside of testing.
9
+
Use this approach when:
10
+
- You need only one ML-DSA parameter set (44, 65, or 87)
11
+
- You want to build the mldsa-native C files separately, not as a single compilation unit.
12
+
- You're using C only, no native backends.
17
13
18
-
## Usage
14
+
## Components
19
15
20
-
Build this example with `make build`, run with `make run`.
16
+
1. mldsa-native source tree: [`mldsa/src/`](../../mldsa/src) and [`mldsa/src/fips202/`](../../mldsa/src/fips202)
17
+
2. A secure random number generator implementing [`randombytes.h`](../../mldsa/src/randombytes.h)
18
+
3. Your application source code
21
19
22
-
## What this example demonstrates
20
+
## Configuration
23
21
24
-
This basic example shows how to use the ML-DSA (Module-Lattice-Based Digital Signature Algorithm) for:
22
+
The configuration file [mldsa_native_config.h](mldsa_native/mldsa_native_config.h) sets:
23
+
-`MLD_CONFIG_PARAMETER_SET`: Security level (44, 65, or 87). Default is 65.
24
+
-`MLD_CONFIG_NAMESPACE_PREFIX`: Symbol prefix for the API. Set to `mldsa` in this example.
25
25
26
-
1.**Key Generation**: Generate a public/private key pair
27
-
2.**Signing**: Sign a message with a private key and optional context
28
-
3.**Signature Verification**: Verify a signature using the public key
29
-
4.**Signed Messages**: Create and open signed messages (signature + message combined)
26
+
To change the security level, modify `MLD_CONFIG_PARAMETER_SET` in the config file or pass it via CFLAGS.
30
27
31
-
The example demonstrates both the detached signature API (`crypto_sign_signature`/`crypto_sign_verify`) and the combined signature API (`crypto_sign`/`crypto_sign_open`).
28
+
## Usage
32
29
33
-
## Parameter Sets
30
+
```bash
31
+
make build # Build the example
32
+
make run # Run the example
33
+
```
34
34
35
-
ML-DSA supports three parameter sets:
36
-
-**ML-DSA-44**
37
-
-**ML-DSA-65**
38
-
-**ML-DSA-87**
35
+
## Warning
39
36
40
-
The example builds and runs all three parameter sets to demonstrate the different security levels and their corresponding key/signature sizes.
37
+
The `randombytes()` implementation in `test_only_rng/` is for TESTING ONLY.
38
+
You MUST provide a cryptographically secure RNG for production use.
0 commit comments