v0.18.0: Implementation of generic newtypes

.github/workflows/test.yml

@@ -27,7 +27,7 @@ jobs:
           - stable
           - beta
           - nightly
-          - 1.86.0 # MSRV
+          - 1.87.0 # MSRV
         os:
           - ubuntu-latest
           - macos-latest

CHANGELOG.md

@@ -1,3 +1,28 @@
+### 0.18.0
+
+**Data:** TBD.
+
+**Changelog:**
+- [Breaking change] Rust Edition moved from `2021` to `2024`.
+- [Breaking change] `auth::SecretKey` has been changed to reference directly the hazardous type instead: `crate::hazardous::mac::blake2b::SecretKey`.
+- [Breaking change] `T::generate() -> Self` -> `T::generate() -> Result<T, UnknownCryptoError>` where this was not already the case. All `T::generate()` calls are now fallible and return `UnknownCryptoError` so all OS-related errors can be handled.
+- [Breaking change] `T::from_slice()` is no longer provided. Instead, all types provide: `TryFrom<&[u8]>`, `TryFrom<&Vec<u8>>` and `TryFrom<&[u8; N]>` + `From<[N]>` where applicable.
+- [Breaking change] `T::unprotected_as_bytes()` -> `T::unprotected_as_ref()`. 
+- [Breaking change] High-level types used in non-`hazardous` API no longer implement `Default` with a panicking CSPRNG call. Instead `generate() -> Result<Self, UnknownCryptoError>` is provided exclusively.
+- [Breaking change] High-level types used in non-`hazardous` API no longer implement `T::generate(length: usize)`.
+- [Breaking change] ML-KEM and X-Wing API have undergone large re-design:
+	- [Breaking change] `mlkem*:MlKem*` struct no longer exists, and all functionality has been moved to the respective `KeyPair`, `EncapsulationKey` and `DecapsulationKey` types.
+	- [Breaking change] ML-KEM `DecapsulatoinKeys` no longer themself perform key-caching. This has been moved to `KeyPair`. `KeyPair` therefor offers important performance benefits when decapsulating with the same secret more than once.
+	- [Breaking change] Constants previously associated with the zero-sized structs are now in `mlkem*::` modules.
+	- [Breaking change] `ML-KEM` `DecapuslationKey`s can now return the raw, encoded bytes.
+- [Breaking change] `orion::kdf::Password` and `orion::pwhash::Password`  no longer has `generate()` since it is meant to represent a user-supplied password (one of the many drawbacks of the older macro-based approach).
+- [Breaking change] Types that previously implemented `Copy` do not anymore. `Copy` in all cases requires copying a lot of bytes and could hide a performance penalty, so now only `Clone` is available for `Public<T>`. 
+- [Breaking change] `orion::hazardous::ecc::x25519::PublicKey` no longer stores the u-coordinate in masked form, but original byte slice. The `PartialEq` still respects (applies masking) the u-coordinate condition. Masking is applied before Montgomery ladder.
+- [Breaking change] `orion::hazardous::ecc::x25519::SecretKey` no longer stores the clamped scalar, but the original byte slice. This changes the inherited `PartialEq`, which now operates on the original bytes, not the clamped. Clamping is applied before Montgomery ladder.
+- [Breaking change] `orion::hazardous::ecc::x25519::SharedSecret` now  respects (applies masking) the u-coordinate condition for `PartialEq`.
+
+- MSRV bumped to `1.87`
+
 ### 0.17.14
 
 **Date:** April 25, 2026.

Cargo.toml

@@ -1,12 +1,12 @@
 [package]
 name = "orion"
-version = "0.17.14"
+version = "0.18.0"
 authors = ["brycx <brycx@protonmail.com>"]
 description = "Usable, easy and safe pure-Rust crypto"
 keywords = ["cryptography", "crypto", "aead", "pqc", "kem"]
 categories = ["cryptography", "no-std"]
-edition = "2021"
-rust-version = "1.86"                                       # Update CI (MSRV) test + README along with this.
+edition = "2024"
+rust-version = "1.87"                                       # Update CI (MSRV) test + README along with this.
 readme = "README.md"
 repository = "https://github.com/orion-rs/orion"
 documentation = "https://docs.rs/orion"

README.md

@@ -1,5 +1,5 @@
 # orion
-[![Daily tests](https://github.com/orion-rs/orion/actions/workflows/daily_tests.yml/badge.svg)](https://github.com/orion-rs/orion/actions/workflows/daily_tests.yml) [![dudect](https://github.com/orion-rs/orion-dudect/actions/workflows/weekly.yml/badge.svg)](https://github.com/orion-rs/orion-dudect/actions/workflows/weekly.yml) [![Audit](https://github.com/orion-rs/orion/actions/workflows/audit_check.yml/badge.svg)](https://github.com/orion-rs/orion/actions/workflows/audit_check.yml) [![codecov](https://codecov.io/gh/orion-rs/orion/branch/master/graph/badge.svg)](https://codecov.io/gh/orion-rs/orion) [![Documentation](https://docs.rs/orion/badge.svg)](https://docs.rs/orion/) [![Crates.io](https://img.shields.io/crates/v/orion.svg)](https://crates.io/crates/orion) [![Safety Dance](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/) [![MSRV](https://img.shields.io/badge/MSRV-1.86-informational.svg)](https://img.shields.io/badge/MSRV-1.86-informational) [![Matrix](https://img.shields.io/matrix/orion-rs:matrix.org.svg?logo=matrix)](https://matrix.to/#/#orion-rs:matrix.org)
+[![Daily tests](https://github.com/orion-rs/orion/actions/workflows/daily_tests.yml/badge.svg)](https://github.com/orion-rs/orion/actions/workflows/daily_tests.yml) [![dudect](https://github.com/orion-rs/orion-dudect/actions/workflows/weekly.yml/badge.svg)](https://github.com/orion-rs/orion-dudect/actions/workflows/weekly.yml) [![Audit](https://github.com/orion-rs/orion/actions/workflows/audit_check.yml/badge.svg)](https://github.com/orion-rs/orion/actions/workflows/audit_check.yml) [![codecov](https://codecov.io/gh/orion-rs/orion/branch/master/graph/badge.svg)](https://codecov.io/gh/orion-rs/orion) [![Documentation](https://docs.rs/orion/badge.svg)](https://docs.rs/orion/) [![Crates.io](https://img.shields.io/crates/v/orion.svg)](https://crates.io/crates/orion) [![Safety Dance](https://img.shields.io/badge/unsafe-forbidden-success.svg)](https://github.com/rust-secure-code/safety-dance/) [![MSRV](https://img.shields.io/badge/MSRV-1.87-informational.svg)](https://img.shields.io/badge/MSRV-1.87-informational) [![Matrix](https://img.shields.io/matrix/orion-rs:matrix.org.svg?logo=matrix)](https://matrix.to/#/#orion-rs:matrix.org)
 
 ### About
 Orion is a cryptography library written in pure Rust. It aims to provide easy and usable crypto while trying to minimize the use of unsafe code. You can read more about Orion in the [wiki](https://github.com/orion-rs/orion/wiki).
@@ -27,7 +27,7 @@ Orion uses formally verified arithmetic, generated by Fiat Crypto, for the X2551
 See the [SECURITY.md](https://github.com/orion-rs/orion/blob/master/SECURITY.md) regarding recommendations on correct use, reporting security issues and more. Additional information about security regarding Orion is available in the [wiki](https://github.com/orion-rs/orion/wiki/Security).
 
 ### Minimum Supported Rust Version
-Rust 1.86 or later is supported however, the majority of testing happens with latest stable Rust.
+Rust 1.87 or later is supported however, the majority of testing happens with latest stable Rust.
 
 MSRV may be changed at any point and will not be considered a SemVer breaking change.
 

benches/bench.rs

@@ -25,6 +25,7 @@ extern crate orion;
 
 use criterion::*;
 
+use orion::KP;
 use orion::hazardous::{
     aead::{chacha20poly1305, xchacha20poly1305},
     hash::*,
@@ -40,7 +41,7 @@ mod mac {
 
     pub fn bench_poly1305(c: &mut Criterion) {
         let mut group = c.benchmark_group("Poly1305");
-        let key = poly1305::OneTimeKey::generate();
+        let key = poly1305::OneTimeKey::generate().unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -60,7 +61,7 @@ mod mac {
         let mut group = c.benchmark_group("HMAC-SHA256");
         // NOTE: Setting the key like this will pad it for HMAC.
         // Padding is therefore not included in benchmarks.
-        let key = hmac::sha256::SecretKey::generate();
+        let key = hmac::sha256::SecretKey::generate().unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -80,7 +81,7 @@ mod mac {
         let mut group = c.benchmark_group("HMAC-SHA512");
         // NOTE: Setting the key like this will pad it for HMAC.
         // Padding is therefore not included in benchmarks.
-        let key = hmac::sha512::SecretKey::generate();
+        let key = hmac::sha512::SecretKey::generate().unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -111,8 +112,8 @@ mod aead {
 
     pub fn bench_chacha20poly1305(c: &mut Criterion) {
         let mut group = c.benchmark_group("ChaCha20-Poly1305");
-        let key = chacha20poly1305::SecretKey::generate();
-        let nonce = chacha20poly1305::Nonce::from_slice(&[0u8; 12]).unwrap();
+        let key = chacha20poly1305::SecretKey::generate().unwrap();
+        let nonce = chacha20poly1305::Nonce::try_from(&[0u8; 12]).unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -134,8 +135,8 @@ mod aead {
 
     pub fn bench_xchacha20poly1305(c: &mut Criterion) {
         let mut group = c.benchmark_group("XChaCha20-Poly1305");
-        let key = xchacha20poly1305::SecretKey::generate();
-        let nonce = xchacha20poly1305::Nonce::generate();
+        let key = xchacha20poly1305::SecretKey::generate().unwrap();
+        let nonce = xchacha20poly1305::Nonce::generate().unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -249,7 +250,7 @@ mod stream {
 
     pub fn bench_chacha20(c: &mut Criterion) {
         let mut group = c.benchmark_group("ChaCha20");
-        let key = chacha20poly1305::SecretKey::generate();
+        let key = chacha20poly1305::SecretKey::generate().unwrap();
         let nonce = chacha20poly1305::Nonce::from([0u8; 12]);
 
         for size in INPUT_SIZES.iter() {
@@ -269,8 +270,8 @@ mod stream {
 
     pub fn bench_xchacha20(c: &mut Criterion) {
         let mut group = c.benchmark_group("XChaCha20");
-        let key = xchacha20::SecretKey::generate();
-        let nonce = xchacha20::Nonce::generate();
+        let key = xchacha20::SecretKey::generate().unwrap();
+        let nonce = xchacha20::Nonce::generate().unwrap();
 
         for size in INPUT_SIZES.iter() {
             let input = vec![0u8; *size];
@@ -368,7 +369,7 @@ mod kdf {
                 |b, iter_count| {
                     b.iter(|| {
                         pbkdf2::sha256::derive_key(
-                            &pbkdf2::sha256::Password::from_slice(&salt).unwrap(),
+                            &pbkdf2::sha256::Password::try_from(&salt).unwrap(),
                             &ikm,
                             **iter_count,
                             &mut dk_out,
@@ -400,7 +401,7 @@ mod kdf {
                 |b, iter_count| {
                     b.iter(|| {
                         pbkdf2::sha512::derive_key(
-                            &pbkdf2::sha512::Password::from_slice(&salt).unwrap(),
+                            &pbkdf2::sha512::Password::try_from(&salt).unwrap(),
                             &ikm,
                             **iter_count,
                             &mut dk_out,
@@ -458,13 +459,13 @@ mod ecc {
     pub fn bench_x25519(c: &mut Criterion) {
         let mut group = c.benchmark_group("X25519");
 
-        let alice_sk = x25519::PrivateKey::generate();
+        let alice_sk = x25519::PrivateKey::generate().unwrap();
         let alice_pk = x25519::PublicKey::try_from(&alice_sk).unwrap();
 
         group.sample_size(100);
         group.bench_function("key_agreement", move |b| {
             b.iter_with_setup(
-                || x25519::PrivateKey::generate(),
+                || x25519::PrivateKey::generate().unwrap(),
                 |bob_sk| x25519::key_agreement(&bob_sk, &alice_pk).unwrap(),
             )
         });
@@ -480,7 +481,7 @@ mod ecc {
 
 mod kem {
     use super::*;
-    use orion::hazardous::kem::{mlkem1024, mlkem512, mlkem768};
+    use orion::hazardous::kem::{mlkem512, mlkem768, mlkem1024};
 
     pub fn bench_mlkem512(c: &mut Criterion) {
         let mut group = c.benchmark_group("ML-KEM-512");