# 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`][repo:mldsa-native] library.

## Repository

The git repository for this project uses git submodules.

When cloning, we recommend to use:

```sh
git clone --recursive
```

Alternatively, you might need to run

```sh
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`][repo: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.

[repo:mldsa-native]: https://github.com/pq-code-package/mldsa-native
