gitea-mirror/rosenpass
1
0
Fork 0
mirror of https://github.com/rosenpass/rosenpass.git synced 2026-02-28 06:23:08 -08:00
Code Issues Packages Projects Releases Wiki Activity

Fix examples in Doc-Comments

Browse Source
This commit is contained in:
Jan Winkelmann (keks)
2025-03-03 11:31:34 +01:00
parent 2dba9205e7
commit 38f371e3d7
7 changed files with 53 additions and 71 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
cipher-traits/src/algorithms.rs
View File

@@ -40,10 +40,10 @@ pub mod keyed_hash_shake256 {
/// The key length used in [`KeyedHashShake256`]. /// The key length used in [`KeyedHashShake256`].
pub const KEY_LEN: usize = 32; pub const KEY_LEN: usize = 32;
/// The hash length used in [`KeyedHashShake256`]. /// The hash length used in [`KeyedHashShake256`].
pub const OUT_LEN: usize = 32; pub const HASH_LEN: usize = 32;
/// A [`KeyedHash`] that is SHAKE256. /// A [`KeyedHash`] that is SHAKE256.
pub trait KeyedHashShake256: KeyedHash<KEY_LEN, OUT_LEN> {} pub trait KeyedHashShake256: KeyedHash<KEY_LEN, HASH_LEN> {}
} }
/// Constants and trait for the ChaCha20Poly1305 AEAD /// Constants and trait for the ChaCha20Poly1305 AEAD

74
cipher-traits/src/primitives/kem.rs
View File

@@ -17,7 +17,7 @@
//! In the example, we are using Kyber512, but any KEM that correctly implements the [Kem] //! In the example, we are using Kyber512, but any KEM that correctly implements the [Kem]
//! trait could be used as well. //! trait could be used as well.
//!```rust //!```rust
//! use rosenpass_cipher_traits::Kem; //! use rosenpass_cipher_traits::primitives::Kem;
//! use rosenpass_oqs::Kyber512; //! use rosenpass_oqs::Kyber512;
//! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret}; //! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret};
//! //!
@@ -25,14 +25,14 @@
//! secret_policy_use_only_malloc_secrets(); //! secret_policy_use_only_malloc_secrets();
//! let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero(); //! let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero();
//! let mut alice_pk: [u8; MyKem::PK_LEN] = [0; MyKem::PK_LEN]; //! let mut alice_pk: [u8; MyKem::PK_LEN] = [0; MyKem::PK_LEN];
//! MyKem::keygen(alice_sk.secret_mut(), &mut alice_pk)?; //! MyKem::default().keygen(alice_sk.secret_mut(), &mut alice_pk)?;
//! //!
//! let mut bob_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero(); //! let mut bob_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero();
//! let mut bob_ct: [u8; MyKem::CT_LEN] = [0; MyKem::CT_LEN]; //! let mut bob_ct: [u8; MyKem::CT_LEN] = [0; MyKem::CT_LEN];
//! MyKem::encaps(bob_shk.secret_mut(), &mut bob_ct, &mut alice_pk)?; //! MyKem::default().encaps(bob_shk.secret_mut(), &mut bob_ct, &mut alice_pk)?;
//! //!
//! let mut alice_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero(); //! let mut alice_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero();
//! MyKem::decaps(alice_shk.secret_mut(), alice_sk.secret_mut(), &mut bob_ct)?; //! MyKem::default().decaps(alice_shk.secret_mut(), alice_sk.secret_mut(), &mut bob_ct)?;
//! //!
//! # assert_eq!(alice_shk.secret(), bob_shk.secret()); //! # assert_eq!(alice_shk.secret(), bob_shk.secret());
//! # Ok::<(), anyhow::Error>(()) //! # Ok::<(), anyhow::Error>(())
@@ -43,13 +43,10 @@
//! be implemented using a **HORRIBLY INSECURE** DummyKem that only uses static values for keys //! be implemented using a **HORRIBLY INSECURE** DummyKem that only uses static values for keys
//! and ciphertexts as an example. //! and ciphertexts as an example.
//!```rust //!```rust
//!# use rosenpass_cipher_traits::Kem; //!# use rosenpass_cipher_traits::primitives::{Kem, KemError as Error};
//! //!
//! struct DummyKem {} //! struct DummyKem {}
//! impl Kem for DummyKem { //! impl Kem<1,1,1,1> for DummyKem {
//!
//! // For this DummyKem, using String for errors is sufficient.
//! type Error = String;
//! //!
//! // For this DummyKem, we will use a single `u8` for everything //! // For this DummyKem, we will use a single `u8` for everything
//! const SK_LEN: usize = 1; //! const SK_LEN: usize = 1;
@@ -57,74 +54,56 @@
//! const CT_LEN: usize = 1; //! const CT_LEN: usize = 1;
//! const SHK_LEN: usize = 1; //! const SHK_LEN: usize = 1;
//! //!
//! fn keygen(sk: &mut [u8], pk: &mut [u8]) -> Result<(), Self::Error> { //! fn keygen(&self, sk: &mut [u8;1], pk: &mut [u8;1]) -> Result<(), Error> {
//! if sk.len() != Self::SK_LEN {
//! return Err("sk does not have the correct length!".to_string());
//! }
//! if pk.len() != Self::PK_LEN {
//! return Err("pk does not have the correct length!".to_string());
//! }
//! sk[0] = 42; //! sk[0] = 42;
//! pk[0] = 21; //! pk[0] = 21;
//! Ok(()) //! Ok(())
//! } //! }
//! //!
//! fn encaps(shk: &mut [u8], ct: &mut [u8], pk: &[u8]) -> Result<(), Self::Error> { //! fn encaps(&self, shk: &mut [u8;1], ct: &mut [u8;1], pk: &[u8;1]) -> Result<(), Error> {
//! if pk.len() != Self::PK_LEN {
//! return Err("pk does not have the correct length!".to_string());
//! }
//! if ct.len() != Self::CT_LEN {
//! return Err("ct does not have the correct length!".to_string());
//! }
//! if shk.len() != Self::SHK_LEN {
//! return Err("shk does not have the correct length!".to_string());
//! }
//! if pk[0] != 21 { //! if pk[0] != 21 {
//! return Err("Invalid public key!".to_string()); //! return Err(Error::InvalidArgument);
//! } //! }
//! ct[0] = 7; //! ct[0] = 7;
//! shk[0] = 17; //! shk[0] = 17;
//! Ok(()) //! Ok(())
//! } //! }
//! //!
//! fn decaps(shk: &mut [u8], sk: &[u8], ct: &[u8]) -> Result<(), Self::Error> { //! fn decaps(&self, shk: &mut [u8;1 ], sk: &[u8;1], ct: &[u8;1]) -> Result<(), Error> {
//! if sk.len() != Self::SK_LEN {
//! return Err("sk does not have the correct length!".to_string());
//! }
//! if ct.len() != Self::CT_LEN {
//! return Err("ct does not have the correct length!".to_string());
//! }
//! if shk.len() != Self::SHK_LEN {
//! return Err("shk does not have the correct length!".to_string());
//! }
//! if sk[0] != 42 { //! if sk[0] != 42 {
//! return Err("Invalid public key!".to_string()); //! return Err(Error::InvalidArgument);
//! } //! }
//! if ct[0] != 7 { //! if ct[0] != 7 {
//! return Err("Invalid ciphertext!".to_string()); //! return Err(Error::InvalidArgument);
//! } //! }
//! shk[0] = 17; //! shk[0] = 17;
//! Ok(()) //! Ok(())
//! } //! }
//! } //! }
//!
//! impl Default for DummyKem {
//! fn default() -> Self {
//! Self{}
//! }
//! }
//! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret}; //! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret};
//! # //! #
//! # type MyKem = DummyKem; //! # type MyKem = DummyKem;
//! # secret_policy_use_only_malloc_secrets(); //! # secret_policy_use_only_malloc_secrets();
//! # let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero(); //! # let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero();
//! # let mut alice_pk: [u8; MyKem::PK_LEN] = [0; MyKem::PK_LEN]; //! # let mut alice_pk: [u8; MyKem::PK_LEN] = [0; MyKem::PK_LEN];
//! # MyKem::keygen(alice_sk.secret_mut(), &mut alice_pk)?; //! # MyKem::default().keygen(alice_sk.secret_mut(), &mut alice_pk)?;
//! //!
//! # let mut bob_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero(); //! # let mut bob_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero();
//! # let mut bob_ct: [u8; MyKem::CT_LEN] = [0; MyKem::CT_LEN]; //! # let mut bob_ct: [u8; MyKem::CT_LEN] = [0; MyKem::CT_LEN];
//! # MyKem::encaps(bob_shk.secret_mut(), &mut bob_ct, &mut alice_pk)?; //! # MyKem::default().encaps(bob_shk.secret_mut(), &mut bob_ct, &mut alice_pk)?;
//! # //! #
//! # let mut alice_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero(); //! # let mut alice_shk: Secret<{ MyKem::SHK_LEN }> = Secret::zero();
//! # MyKem::decaps(alice_shk.secret_mut(), alice_sk.secret_mut(), &mut bob_ct)?; //! # MyKem::default().decaps(alice_shk.secret_mut(), alice_sk.secret_mut(), &mut bob_ct)?;
//! # //! #
//! # assert_eq!(alice_shk.secret(), bob_shk.secret()); //! # assert_eq!(alice_shk.secret(), bob_shk.secret());
//! # //! #
//! # Ok::<(), String>(()) //! # Ok::<(), Error>(())
//!``` //!```
//! //!
@@ -154,9 +133,9 @@ use thiserror::Error;
/// ///
/// fn encaps_given_a_kem<KemImpl>( /// fn encaps_given_a_kem<KemImpl>(
/// kem: &KemImpl, /// kem: &KemImpl,
/// pk: &[u8l PK_LEN], /// pk: &[u8; PK_LEN],
/// ct: &mut [u8; CT_LEN] /// ct: &mut [u8; CT_LEN]
/// ) where KemImpl: Kem<SK_LEN, PK_LEN, CT_LEN, SHK_LEN> -> [u8; SHK_LEN]{ /// ) -> [u8; SHK_LEN] where KemImpl: Kem<SK_LEN, PK_LEN, CT_LEN, SHK_LEN>{
/// let mut shk = [0u8; SHK_LEN]; /// let mut shk = [0u8; SHK_LEN];
/// kem.encaps(&mut shk, ct, pk).unwrap(); /// kem.encaps(&mut shk, ct, pk).unwrap();
/// shk /// shk
@@ -174,9 +153,10 @@ use thiserror::Error;
/// const SHK_LEN: usize = 32; /// const SHK_LEN: usize = 32;
/// ///
/// fn encaps_without_kem<KemImpl>( /// fn encaps_without_kem<KemImpl>(
/// pk: &[u8l PK_LEN], /// pk: &[u8; PK_LEN],
/// ct: &mut [u8; CT_LEN] /// ct: &mut [u8; CT_LEN]
/// ) where KemImpl: Default + Kem<SK_LEN, PK_LEN, CT_LEN, SHK_LEN> -> [u8; SHK_LEN]{ /// ) -> [u8; SHK_LEN]
/// where KemImpl: Default + Kem<SK_LEN, PK_LEN, CT_LEN, SHK_LEN> {
/// let mut shk = [0u8; SHK_LEN]; /// let mut shk = [0u8; SHK_LEN];
/// KemImpl::default().encaps(&mut shk, ct, pk).unwrap(); /// KemImpl::default().encaps(&mut shk, ct, pk).unwrap();
/// shk /// shk

3
ciphers/src/subtle/rust_crypto/blake2b.rs
View File

@@ -8,8 +8,7 @@ use blake2::Blake2bMac;
use rosenpass_cipher_traits::primitives::KeyedHash; use rosenpass_cipher_traits::primitives::KeyedHash;
use rosenpass_to::{ops::copy_slice, To}; use rosenpass_to::{ops::copy_slice, To};
pub use rosenpass_cipher_traits::algorithms::keyed_hash_blake2b::HASH_LEN; pub use rosenpass_cipher_traits::algorithms::keyed_hash_blake2b::{HASH_LEN, KEY_LEN};
pub use rosenpass_cipher_traits::algorithms::keyed_hash_blake2b::KEY_LEN;
/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b /// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b
/// with output and key length of 32 bytes (see [Blake2bMac]). /// with output and key length of 32 bytes (see [Blake2bMac]).

2
ciphers/src/subtle/rust_crypto/keyed_shake256.rs
View File

@@ -3,6 +3,8 @@ use rosenpass_cipher_traits::primitives::{InferKeyedHash, KeyedHash};
use sha3::digest::{ExtendableOutput, Update, XofReader}; use sha3::digest::{ExtendableOutput, Update, XofReader};
use sha3::Shake256; use sha3::Shake256;
pub use rosenpass_cipher_traits::algorithms::keyed_hash_shake256::{HASH_LEN, KEY_LEN};
/// An implementation of the [`KeyedHash`] trait backed by the RustCrypto implementation of SHAKE256. /// An implementation of the [`KeyedHash`] trait backed by the RustCrypto implementation of SHAKE256.
#[derive(Clone, Debug, PartialEq, Eq)] #[derive(Clone, Debug, PartialEq, Eq)]
pub struct SHAKE256Core<const KEY_LEN: usize, const HASH_LEN: usize>; pub struct SHAKE256Core<const KEY_LEN: usize, const HASH_LEN: usize>;

7
ciphers/src/subtle/rust_crypto/xchacha20poly1305_ietf.rs
View File

@@ -1,15 +1,16 @@
use rosenpass_to::ops::copy_slice; use rosenpass_to::ops::copy_slice;
use rosenpass_to::To; use rosenpass_to::To;
use rosenpass_cipher_traits::algorithms::aead_xchacha20poly1305::{ use rosenpass_cipher_traits::algorithms::aead_xchacha20poly1305::AeadXChaCha20Poly1305;
AeadXChaCha20Poly1305, KEY_LEN, NONCE_LEN, TAG_LEN,
};
use rosenpass_cipher_traits::primitives::{Aead, AeadError, AeadWithNonceInCiphertext}; use rosenpass_cipher_traits::primitives::{Aead, AeadError, AeadWithNonceInCiphertext};
use chacha20poly1305::aead::generic_array::GenericArray; use chacha20poly1305::aead::generic_array::GenericArray;
use chacha20poly1305::XChaCha20Poly1305 as AeadImpl; use chacha20poly1305::XChaCha20Poly1305 as AeadImpl;
use chacha20poly1305::{AeadInPlace, KeyInit}; use chacha20poly1305::{AeadInPlace, KeyInit};
pub use rosenpass_cipher_traits::algorithms::aead_xchacha20poly1305::{
KEY_LEN, NONCE_LEN, TAG_LEN,
};
/// Implements the [`Aead`] and [`AeadXChaCha20Poly1305`] traits backed by the RustCrypto /// Implements the [`Aead`] and [`AeadXChaCha20Poly1305`] traits backed by the RustCrypto
/// implementation. /// implementation.
pub struct XChaCha20Poly1305; pub struct XChaCha20Poly1305;

8
rosenpass/src/protocol/mod.rs
View File

@@ -25,8 +25,8 @@
//! ``` //! ```
//! use std::ops::DerefMut; //! use std::ops::DerefMut;
//! use rosenpass_secret_memory::policy::*; //! use rosenpass_secret_memory::policy::*;
//! use rosenpass_cipher_traits::Kem; //! use rosenpass_cipher_traits::primitives::Kem;
//! use rosenpass_ciphers::kem::StaticKem; //! use rosenpass_ciphers::StaticKem;
//! use rosenpass::{ //! use rosenpass::{
//! protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey}, //! protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey},
//! }; //! };
@@ -38,11 +38,11 @@
//! //!
//! // initialize secret and public key for peer a ... //! // initialize secret and public key for peer a ...
//! let (mut peer_a_sk, mut peer_a_pk) = (SSk::zero(), SPk::zero()); //! let (mut peer_a_sk, mut peer_a_pk) = (SSk::zero(), SPk::zero());
//! StaticKem::keygen(peer_a_sk.secret_mut(), peer_a_pk.deref_mut())?; //! StaticKem.keygen(peer_a_sk.secret_mut(), peer_a_pk.deref_mut())?;
//! //!
//! // ... and for peer b //! // ... and for peer b
//! let (mut peer_b_sk, mut peer_b_pk) = (SSk::zero(), SPk::zero()); //! let (mut peer_b_sk, mut peer_b_pk) = (SSk::zero(), SPk::zero());
//! StaticKem::keygen(peer_b_sk.secret_mut(), peer_b_pk.deref_mut())?; //! StaticKem.keygen(peer_b_sk.secret_mut(), peer_b_pk.deref_mut())?;
//! //!
//! // initialize server and a pre-shared key //! // initialize server and a pre-shared key
//! let psk = SymKey::random(); //! let psk = SymKey::random();

26
rosenpass/src/protocol/protocol.rs
View File

@@ -398,16 +398,16 @@ impl From<crate::config::ProtocolVersion> for ProtocolVersion {
/// ``` /// ```
/// use std::ops::DerefMut; /// use std::ops::DerefMut;
/// use rosenpass::protocol::{SSk, SPk, SymKey, Peer, ProtocolVersion}; /// use rosenpass::protocol::{SSk, SPk, SymKey, Peer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem; /// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::Kem; /// use rosenpass_cipher_traits::primitives::Kem;
/// ///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets(); /// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
/// ///
/// let (mut sskt, mut spkt) = (SSk::zero(), SPk::zero()); /// let (mut sskt, mut spkt) = (SSk::zero(), SPk::zero());
/// StaticKem::keygen(sskt.secret_mut(), spkt.deref_mut())?; /// StaticKem.keygen(sskt.secret_mut(), spkt.deref_mut())?;
/// ///
/// let (mut sskt2, mut spkt2) = (SSk::zero(), SPk::zero()); /// let (mut sskt2, mut spkt2) = (SSk::zero(), SPk::zero());
/// StaticKem::keygen(sskt2.secret_mut(), spkt2.deref_mut())?; /// StaticKem.keygen(sskt2.secret_mut(), spkt2.deref_mut())?;
/// ///
/// let psk = SymKey::random(); /// let psk = SymKey::random();
/// ///
@@ -834,7 +834,7 @@ pub trait Mortal {
/// ///
/// ``` /// ```
/// use std::ops::DerefMut; /// use std::ops::DerefMut;
/// use rosenpass_ciphers::kem::StaticKem; /// use rosenpass_ciphers::StaticKem;
/// use rosenpass::protocol::{SSk, SPk, testutils::ServerForTesting, ProtocolVersion}; /// use rosenpass::protocol::{SSk, SPk, testutils::ServerForTesting, ProtocolVersion};
/// ///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets(); /// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
@@ -1376,13 +1376,13 @@ impl CryptoServer {
/// ``` /// ```
/// use std::ops::DerefMut; /// use std::ops::DerefMut;
/// use rosenpass::protocol::{SSk, SPk, CryptoServer, ProtocolVersion}; /// use rosenpass::protocol::{SSk, SPk, CryptoServer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem; /// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::Kem; /// use rosenpass_cipher_traits::primitives::Kem;
/// ///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets(); /// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
/// ///
/// let (mut sskm, mut spkm) = (SSk::zero(), SPk::zero()); /// let (mut sskm, mut spkm) = (SSk::zero(), SPk::zero());
/// StaticKem::keygen(sskm.secret_mut(), spkm.deref_mut())?; /// StaticKem.keygen(sskm.secret_mut(), spkm.deref_mut())?;
/// ///
/// let srv = CryptoServer::new(sskm, spkm.clone()); /// let srv = CryptoServer::new(sskm, spkm.clone());
/// assert_eq!(srv.spkm, spkm); /// assert_eq!(srv.spkm, spkm);
@@ -1441,17 +1441,17 @@ impl CryptoServer {
/// ``` /// ```
/// use std::ops::DerefMut; /// use std::ops::DerefMut;
/// use rosenpass::protocol::{SSk, SPk, SymKey, CryptoServer, ProtocolVersion}; /// use rosenpass::protocol::{SSk, SPk, SymKey, CryptoServer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem; /// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::Kem; /// use rosenpass_cipher_traits::primitives::Kem;
/// ///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets(); /// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
/// ///
/// let (mut sskm, mut spkm) = (SSk::zero(), SPk::zero()); /// let (mut sskm, mut spkm) = (SSk::zero(), SPk::zero());
/// StaticKem::keygen(sskm.secret_mut(), spkm.deref_mut())?; /// StaticKem.keygen(sskm.secret_mut(), spkm.deref_mut())?;
/// let mut srv = CryptoServer::new(sskm, spkm); /// let mut srv = CryptoServer::new(sskm, spkm);
/// ///
/// let (mut sskt, mut spkt) = (SSk::zero(), SPk::zero()); /// let (mut sskt, mut spkt) = (SSk::zero(), SPk::zero());
/// StaticKem::keygen(sskt.secret_mut(), spkt.deref_mut())?; /// StaticKem.keygen(sskt.secret_mut(), spkt.deref_mut())?;
/// ///
/// let psk = SymKey::random(); /// let psk = SymKey::random();
/// ///
@@ -1698,7 +1698,7 @@ impl Session {
/// ///
/// ``` /// ```
/// use rosenpass::protocol::{Session, HandshakeRole}; /// use rosenpass::protocol::{Session, HandshakeRole};
/// use rosenpass_ciphers::keyed_hash::KeyedHash; /// use rosenpass_ciphers::KeyedHash;
/// ///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets(); /// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
/// ///