mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-07-06 10:50:50 +02:00
Josh Holtrop
125 lines
3.4 KiB
Markdown
125 lines
3.4 KiB
Markdown
# wolfssl-wolfcrypt crate
|
|
|
|
The `wolfssl-wolfcrypt` crate is a Rust wrapper for the wolfCrypt cryptographic
|
|
algorithms portion of the wolfSSL C library.
|
|
|
|
This crate requires wolfSSL version 5.9.0 or newer.
|
|
|
|
The crate uses `no_std` so that no Rust standard library is required.
|
|
This makes it well-suited for embedded/bare-metal environments.
|
|
|
|
There is an optional `alloc` feature that enables APIs which require heap
|
|
allocation.
|
|
|
|
## Installation
|
|
|
|
The `wolfssl` C library must be installed to be used by the Rust crate.
|
|
|
|
The `wolfssl-wolfcrypt` crate can be used by including it as a dependency in
|
|
your project's `Cargo.toml` file.
|
|
|
|
For example:
|
|
|
|
```
|
|
[dependencies]
|
|
wolfssl-wolfcrypt = "2.0"
|
|
```
|
|
|
|
## API Coverage
|
|
|
|
This crate provides a wrapper API for the following wolfCrypt C library
|
|
functionality:
|
|
|
|
* AES
|
|
* CBC, CCM, CFB, CTR, EAX, ECB, GCM, OFB, XTS
|
|
* BLAKE2
|
|
* CMAC
|
|
* ChaCha20-Poly1305
|
|
* Curve25519
|
|
* DH
|
|
* ECC
|
|
* Ed25519
|
|
* Ed448
|
|
* HKDF
|
|
* HMAC
|
|
* LMS
|
|
* ML-DSA
|
|
* ML-KEM
|
|
* PBKDF2
|
|
* PKCS #12 PBKDF
|
|
* PRF
|
|
* RNG
|
|
* RSA
|
|
* scrypt
|
|
* SHA
|
|
* SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384,
|
|
SHA3-512, SHAKE128, SHAKE256
|
|
* SRTP/SRTCP KDF
|
|
* SSH KDF
|
|
* TLSv1.3 HKDF
|
|
|
|
## RustCrypto Trait Support
|
|
|
|
In addition to its native API, this crate can implement the common
|
|
[RustCrypto](https://github.com/RustCrypto) traits for wolfCrypt-backed types.
|
|
Each set of trait implementations is gated behind a Cargo feature so that
|
|
projects only pull in the dependencies they need. All features are off by
|
|
default.
|
|
|
|
| Feature | RustCrypto crate | wolfCrypt types |
|
|
| --------------- | ---------------- | ------------------------------------- |
|
|
| `digest` | `digest` | SHA (sha_digest), BLAKE2 (blake2_digest) |
|
|
| `mac` | `digest` (mac) | HMAC (hmac_mac), CMAC (cmac_mac), BLAKE2 (blake2_mac) |
|
|
| `signature` | `signature` | ECDSA (ecdsa), RSA PKCS#1 v1.5 (rsa_pkcs1v15) |
|
|
| `cipher` | `cipher` | AES (aes) |
|
|
| `aead` | `aead` | AES-GCM/CCM/EAX (aes), ChaCha20-Poly1305 |
|
|
| `rand_core` | `rand_core` | RNG (random) |
|
|
| `kem` | `kem` | ML-KEM (mlkem_kem) |
|
|
| `password-hash` | `password-hash` | PBKDF2 (pbkdf2_password_hash), scrypt (scrypt_password_hash) |
|
|
|
|
The BLAKE2, CMAC, and HMAC trait modules additionally require the corresponding
|
|
algorithm support to be enabled in the wolfSSL C library.
|
|
|
|
Enable features in your `Cargo.toml`, for example:
|
|
|
|
```
|
|
[dependencies]
|
|
wolfssl-wolfcrypt = { version = "2.0", features = ["digest", "signature"] }
|
|
```
|
|
|
|
## Build Notes
|
|
|
|
### WOLFSSL_PREFIX
|
|
|
|
If the wolfSSL C library is not installed in a default location, you can
|
|
specify the installation prefix with the `WOLFSSL_PREFIX` environment variable
|
|
when building the `wolfssl-wolfcrypt` crate.
|
|
|
|
For example:
|
|
|
|
```
|
|
WOLFSSL_PREFIX=/opt/my-wolfssl-build cargo build
|
|
```
|
|
|
|
### Cross-Compiling
|
|
|
|
Ensure that the target you want to build for is installed for Rust.
|
|
For example:
|
|
|
|
```
|
|
rustup target add riscv64imac-unknown-none-elf
|
|
```
|
|
|
|
Build with the `--target` option if building manually:
|
|
|
|
```
|
|
export WOLFSSL_PREFIX=/opt/wolfssl-riscv64
|
|
cargo build --target riscv64imac-unknown-none-elf
|
|
```
|
|
|
|
To specify the linker for the target:
|
|
|
|
```
|
|
export CARGO_TARGET_RISCV64IMAC_UNKNOWN_NONE_ELF_LINKER=riscv64-elf-gcc
|
|
```
|