Expanded Rust API for wolfSSL

Rust is a modern programming language known for its focus on memory safety and performance, making it a powerful choice for systems programming, including security-sensitive applications. To bridge the gap between Rust’s strong guarantees and the mature, high-performance cryptography provided by the wolfSSL library, we have developed and are continuing to improve a comprehensive set of Rust wrappers. These wrappers enable developers to leverage wolfSSL’s FIPS-validated, optimized, and portable cryptography directly within their Rust projects.

Download wolfSSL →

Why Use the wolfSSL Rust Wrappers?

Integrating the wolfSSL C library into a Rust project through FFI (Foreign Function Interface) can be complex and error-prone, especially when dealing with memory management and object lifetimes—areas where Rust excels. Our official Rust wrappers solve this by providing a high-level, idiomatic Rust interface to the underlying C implementation of wolfSSL.

Key benefits of using the Rust wrappers include:

• Safety and Idiomatic Design: The wrappers expose APIs that align with Rust’s conventions, such as using Result for error handling and managing resources using Rust’s ownership and lifetime system, preventing common security bugs like double-free or use-after-free errors.
• Performance: By utilizing the highly optimized wolfSSL C library, Rust applications gain access to efficient cryptographic primitives (e.g., optimized AES, SHA, RSA, ECC, Ed25519, etc…) that ensure high throughput and low latency.
• Portability and Certification: wolfSSL is known for its small size and broad platform support, from embedded systems to major operating systems. The Rust wrappers inherit this portability. Furthermore, they allow Rust projects to easily utilize FIPS 140-2 validated cryptography provided by the underlying C library.

Available Functionality

The wolfSSL Rust wrappers offer access to a wide range of cryptographic functionality from the wolfCrypt and wolfSSL layers. Recent updates to the repository have expanded this functionality and focused on usability and portability across various library configurations.

Expanded wolfCrypt Bindings

The wolfssl crate provides both low-level and high-level interfaces to the wolfssl C library including wolfCrypt modules which contain the core cryptographic algorithms.

Feature	Description
Hashing	The wolfssl Rust API supports SHA-1, SHA-224, SHA-256, SHA-384, SHA-512, SHA3-224, SHA3-256, SHA3-384, SHA3-256, SHAKE128, and SHAKE256.
Symmetric Ciphers	The wolfssl Rust API supports AES (including CBC, CCM, CFB, CTR, EAX, ECB, GCM, OFB, and XTS cipher modes) with 128-, 192-, or 256-bit keys.
Asymmetric Ciphers	The wolfssl Rust API supports the ability to generate and manage keys using RSA, ECC, Ed448, and Ed25519 algorithms.
Key Exchange	The wolfssl Rust API supports Diffie-Hellman (DH) and ECDH protocols.
Message Authentication Codes	The wolfssl Rust API supports CMAC and HMAC message authentication code algorithms.
Key Derivation Functions	The wolfssl Rust API supports HKDF, PBKDF2, TLS v1.3 KDF, SSH KDF, PKCS #12 KDF, and SRTP/SRTCP KDF algorithms.
Random Number Generation	The wolfssl Rust API supports a FIPS 140-2 validated random number generator (RNG). It also supports a pseudo-random function (PRF) for MD5, SHA-1, SHA-256, SHA-384, or SHA-512.

Recent commits have focused on ensuring a complete and accurate mapping of the wolfCrypt API, making more of the C library’s features directly accessible to Rust developers. Rust’s cfg system for conditional compilation has been leveraged to allow building the Rust wrappers in various configurations according to the end user’s desired functionality.

Getting Started

To begin using the wolfSSL Rust wrappers, you typically start by including the wolfssl crate in your Cargo.toml file.

You must first ensure that the wolfSSL C library is installed and configured on your system, or you can use the build features to allow the Rust build process to handle the C library compilation for you.

Example Usage

Here’s a sneak peek at how easy it is to use the new wrappers (specific API details can be found in the repository).

RNG

use wolfssl::wolfcrypt::random::RNG;

fn main() {
    // Create a RNG instance.
    let mut rng = RNG::new().expect("Failed to create RNG");

    // Generate a single random byte value.
    let byte = rng.generate_byte().expect("Failed to generate a single byte");

    // Generate a random block.
    let mut buffer = [0u32; 8];
    rng.generate_block(&mut buffer).expect("Failed to generate a block");
}

SHA-256

use wolfssl::wolfcrypt::sha::SHA256;

fn main() {
    // Create a SHA256 instance.
    let mut sha = SHA256::new().expect("Error with new()");

    // Feed input data (can be called multiple times).
    sha.update(b"input").expect("Error with update()");

    // Retrieve the final SHA-256 hash.
    let mut hash = [0u8; SHA256::DIGEST_SIZE];
    sha.finalize(&mut hash).expect("Error with finalize()");
}

ECC

use wolfssl::wolfcrypt::random::RNG;
use wolfssl::wolfcrypt::ecc::ECC;

fn main () {
    let mut rng = RNG::new().expect("Failed to create RNG");

    // Generate a new ECC key.
    let mut ecc = ECC::generate(32, &mut rng).expect("Error with generate()");
    let hash = [0x42u8; 32];
    let mut signature = [0u8; 128];

    // Sign a hash with the ECC key.
    let signature_length = ecc.sign_hash(&hash, &mut signature, &mut rng).expect("Error with sign_hash()");
    let signature = &signature[0..signature_length];
}

For detailed documentation, examples, and the source code, please refer to our official repository and the crate documentation.

Resource:

• GitHub Repository
• Rust wrapper directory

We encourage you to explore the safety and efficiency that the wolfSSL Rust wrappers bring to your next security-focused Rust project!

If you have questions about any of the above, please contact us at facts@wolfssl.com or call us at +1 425 245 8247.

Download wolfSSL Now