14 releases
0.1.0-alpha.13 | Oct 12, 2024 |
---|---|
0.1.0-alpha.12 | Oct 10, 2024 |
0.1.0-alpha.8 | Sep 23, 2024 |
#604 in Cryptography
1,204 downloads per month
48MB
1M
SLoC
Table of Contents
wolf-crypto
- Testing
- Goals and Approach
- Ongoing Testing Priorities
- Current Priorities
- License
- Roadmap
[2/6]
WARNING - THIS LIBRARY IS IN ITS EARLY STAGES, IT IS NOT READY FOR PRODUCTION USE, USE AT YOUR OWN RISK.
wolf-crypto
wolf-crypto
is a Rust library that provides a safe, zero-cost abstraction over wolfcrypt
,
the cryptographic library by wolfSSL. Designed to offer memory-safe, type-safe cryptographic
operations, wolf-crypto
focuses on performance, security, and adherence to FIPS 140-3 standards.
Currently in alpha, the library is undergoing active development and should not be considered stable for production use. The API is subject to change as we incorporate feedback and continue to refine the design. However, once the library reaches its first minor release, the API will be locked in and guaranteed stable*, with no breaking changes*.
wolf-crypto
leverages Rust’s safety guarantees, preventing common vulnerabilities such as memory
leaks, buffer overflows, and other issues prevalent in C-based cryptographic libraries. While still
in alpha, the library has undergone extensive testing and is designed to become an ideal choice
for secure cryptographic operations once it achieves stability.
We encourage feedback from the community as we work toward stabilizing the API, ensuring that
wolf-crypto
is ready for production use while maintaining FIPS 140-3 compliance, formal
verification, and rigorous testing.
Testing
Given the critical nature of cryptographic libraries, comprehensive testing is fundamental to ensuring
the reliability, security, and correctness of the wolf-crypto
library. While cryptographic implementations
are inherently sensitive, the library's interaction with foreign function interfaces (FFI) and unsafe Rust
code necessitates rigorous testing across all areas.
Every component of this library is now fully tested to provide maximum confidence in its functionality. Our approach emphasizes property-based testing, supported by unit testing, formal verification using Kani (for pure-Rust components), and validation through the NIST CAVP program. Constant-time behavior is verified, ensuring that operations are secure and timing attacks are mitigated.
Current Test Suite
Property Tests
Property-based testing is the backbone of our testing framework, ensuring the expected properties of cryptographic algorithms are upheld across a wide range of inputs.
- Validate encryption bijectivity: encryption followed by decryption always returns the original plaintext.
- Verify documented cryptographic properties, such as associativity, commutativity, and other expected behaviors.
- Stress testing with random and large datasets to uncover edge cases.
- Cross-verify with other cryptographic libraries for functional equivalence and correctness.
Unit Tests
Unit tests complement the property tests by covering specific edge cases and known boundaries.
- Edge case testing, including null inputs, minimum-length inputs, and maximum-length outputs.
- Ensure behavior equivalent to robust implementations (e.g.,
rust-crypto
) under these conditions.
Constant-Time Verification
Cryptographic functions are tested for constant-time behavior with respect to their content, ensuring that no exploitable timing variations exist based on the values being compared.
- Automated verification using Haybale Pitchfork from UCSD PLSysSec to confirm that
ct_eq
and similar functions behave consistently relative to input content. - Manual code audits are performed to ensure no branches or loops could introduce variable timing based on input data.
NIST CSRC CAVP Tests
For NIST-recommended algorithms, we conduct thorough testing based on the Cryptographic Algorithm Validation Program (CAVP) to ensure compliance with industry standards.
- Monte Carlo tests stress the algorithms using randomized data over thousands of iterations to verify their resilience.
- Known Answer Tests (KATs) are conducted with short and long datasets to ensure cryptographic correctness and reproducibility.
Official Known Answer Tests (KATs)
For non-NIST algorithms, such as BLAKE2, we perform official Known Answer Tests to ensure the algorithms conform to standard implementations.
- Short and long input dataset coverage to ensure consistency across data sizes.
- Cross-validation with independent implementations and specifications.
Formal Verification
For parts of the library that are pure Rust and do not cross FFI boundaries, formal verification with Kani is used (carefully to ensure completeness) to provide additional assurance of correctness. This is especially important for components such as hex encoding, constant-time equality checks, and other key transformations.
Goals and Approach
Our testing approach is focused on ensuring that the library is production-ready, highly secure, and meets FIPS 140-3 compliance standards.
- Secure design: Enforcing best practices like zeroing secrets from memory after use to prevent unintended data exposure.
- Compile-time FIPS compliance: Using Rust’s type system to enforce FIPS restrictions at compile time and ensure correct usage.
- Continuous testing: As the library evolves, new algorithms undergo rigorous testing to guarantee their security and correctness.
Ongoing Testing Priorities
Our testing framework is continuously evolving, with ongoing efforts focused on:
- Strengthening FIPS 140-3 enforcement, ensuring that algorithms in FIPS scope are properly handled at compile time.
- Expanding performance and scalability testing, ensuring that the library operates efficiently under high-load scenarios.
- Adding new algorithms and immediately subjecting them to the full suite of tests to ensure their robustness and correctness.
Current Priorities
- Focus on implementing and stabilizing the core FIPS 140-3 compatible algorithms.
- Create a clear boundary between algorithms in FIPS scope, without the
allow-non-fips
feature enabled attempt to enforce FIPS requirements in usage at compilation time. - Continual improvements in testing and documentation.
- Expose more algorithms offered by wolfSSL's
wolfcrypt
.
License
This library is under GPLv2 licensing unless you purchased a commercial license from wolfSSL.
Roadmap [2/6]
-
Hashing
[6/6]
- SHA2
[6/6]
- SHA-224
- SHA-256
- SHA-384
- SHA-512
- SHA-512/224
- SHA-512/256
- SHA3
[5/5]
- SHA3-224
- SHA3-256
- SHA3-384
- SHA3-512
- SHAKE
[2/2]
- SHAKE128
- SHAKE256
- SHA
- RIPEMD-160
- MD
[2/2]
- MD5
- MD4
- BLAKE2
[2/2]
- BLAKE2b
- BLAKE2s
- SHA2
-
AEAD
[2/5]
- AES-GCM
[3/3]
- 256
- 192
- 128
- ChaCha20-Poly1305
[2/2]
- 256
- 128
- AES-CCM
[0/3]
- 256
- 192
- 128
- AES-EAX
[0/3]
- 256
- 192
- 128
- AES-SIV
[0/3]
- 256
- 192
- 128
- AES-GCM
-
Symmetric Encryption
[1/3]
- AES
[1/4]
- CTR
[3/3]
- 256
- 192
- 128
- CBC
[0/3]
- 256
- 192
- 128
- XTS
[0/2]
- 256
- 128
- CFB
[0/3]
- 256
- 192
- 128
- CTR
- ChaCha20
[2/2]
- 256
- 128
- 3DES
[0/1]
- 168
- AES
-
MAC
[2/2]
- HMAC
[9/9]
- SHA-256
- SHA-384
- SHA-512
- SHA3-224
- SHA3-256
- SHA3-384
- SHA3-512
- SHA
- MD5
- Poly1305
- HMAC
-
KDF
[3/4]
- HKDF
- PBKDF1
- PBKDF2
- PKCS12 PBKDF
-
Writing the Remaining Sections (asymmetric, password, padding, etc)