gitea-mirror/rosenpass
1
0
Fork 0
mirror of https://github.com/rosenpass/rosenpass.git synced 2025-12-05 20:40:02 -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`].
pub const KEY_LEN: usize = 32;
/// The hash length used in [`KeyedHashShake256`].
pub const OUT_LEN: usize = 32;
pub const HASH_LEN: usize = 32;
/// 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

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]
//! trait could be used as well.
//!```rust
//! use rosenpass_cipher_traits::Kem;
//! use rosenpass_cipher_traits::primitives::Kem;
//! use rosenpass_oqs::Kyber512;
//! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret};
//!
@@ -25,14 +25,14 @@
//! secret_policy_use_only_malloc_secrets();
//! let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero();
//! 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_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();
//! 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());
//! # Ok::<(), anyhow::Error>(())
@@ -43,13 +43,10 @@
//! be implemented using a **HORRIBLY INSECURE** DummyKem that only uses static values for keys
//! and ciphertexts as an example.
//!```rust
//!# use rosenpass_cipher_traits::Kem;
//!# use rosenpass_cipher_traits::primitives::{Kem, KemError as Error};
//!
//! struct DummyKem {}
//! impl Kem for DummyKem {
//!
//! // For this DummyKem, using String for errors is sufficient.
//! type Error = String;
//! impl Kem<1,1,1,1> for DummyKem {
//!
//! // For this DummyKem, we will use a single `u8` for everything
//! const SK_LEN: usize = 1;
@@ -57,74 +54,56 @@
//! const CT_LEN: usize = 1;
//! const SHK_LEN: usize = 1;
//!
//! fn keygen(sk: &mut [u8], pk: &mut [u8]) -> Result<(), Self::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());
//! }
//! fn keygen(&self, sk: &mut [u8;1], pk: &mut [u8;1]) -> Result<(), Error> {
//! sk[0] = 42;
//! pk[0] = 21;
//! Ok(())
//! }
//!
//! fn encaps(shk: &mut [u8], ct: &mut [u8], pk: &[u8]) -> Result<(), Self::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());
//! }
//! fn encaps(&self, shk: &mut [u8;1], ct: &mut [u8;1], pk: &[u8;1]) -> Result<(), Error> {
//! if pk[0] != 21 {
//! return Err("Invalid public key!".to_string());
//! return Err(Error::InvalidArgument);
//! }
//! ct[0] = 7;
//! shk[0] = 17;
//! Ok(())
//! }
//!
//! fn decaps(shk: &mut [u8], sk: &[u8], ct: &[u8]) -> Result<(), Self::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());
//! }
//! fn decaps(&self, shk: &mut [u8;1 ], sk: &[u8;1], ct: &[u8;1]) -> Result<(), Error> {
//! if sk[0] != 42 {
//! return Err("Invalid public key!".to_string());
//! return Err(Error::InvalidArgument);
//! }
//! if ct[0] != 7 {
//! return Err("Invalid ciphertext!".to_string());
//! return Err(Error::InvalidArgument);
//! }
//! shk[0] = 17;
//! Ok(())
//! }
//! }
//!
//! impl Default for DummyKem {
//! fn default() -> Self {
//! Self{}
//! }
//! }
//! # use rosenpass_secret_memory::{secret_policy_use_only_malloc_secrets, Secret};
//! #
//! # type MyKem = DummyKem;
//! # secret_policy_use_only_malloc_secrets();
//! # let mut alice_sk: Secret<{ MyKem::SK_LEN }> = Secret::zero();
//! # 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_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();
//! # 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());
//! #
//! # Ok::<(), String>(())
//! # Ok::<(), Error>(())
//!```
//!
@@ -154,9 +133,9 @@ use thiserror::Error;
///
/// fn encaps_given_a_kem<KemImpl>(
/// kem: &KemImpl,
/// pk: &[u8l PK_LEN],
/// pk: &[u8; PK_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];
/// kem.encaps(&mut shk, ct, pk).unwrap();
/// shk
@@ -174,9 +153,10 @@ use thiserror::Error;
/// const SHK_LEN: usize = 32;
///
/// fn encaps_without_kem<KemImpl>(
/// pk: &[u8l PK_LEN],
/// pk: &[u8; PK_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];
/// KemImpl::default().encaps(&mut shk, ct, pk).unwrap();
/// 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_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::KEY_LEN;
pub use rosenpass_cipher_traits::algorithms::keyed_hash_blake2b::{HASH_LEN, KEY_LEN};
/// Specify that the used implementation of BLAKE2b is the MAC version of BLAKE2b
/// 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::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.
#[derive(Clone, Debug, PartialEq, Eq)]
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::To;
use rosenpass_cipher_traits::algorithms::aead_xchacha20poly1305::{
AeadXChaCha20Poly1305, KEY_LEN, NONCE_LEN, TAG_LEN,
};
use rosenpass_cipher_traits::algorithms::aead_xchacha20poly1305::AeadXChaCha20Poly1305;
use rosenpass_cipher_traits::primitives::{Aead, AeadError, AeadWithNonceInCiphertext};
use chacha20poly1305::aead::generic_array::GenericArray;
use chacha20poly1305::XChaCha20Poly1305 as AeadImpl;
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
/// implementation.
pub struct XChaCha20Poly1305;

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

@@ -25,8 +25,8 @@
//! ```
//! use std::ops::DerefMut;
//! use rosenpass_secret_memory::policy::*;
//! use rosenpass_cipher_traits::Kem;
//! use rosenpass_ciphers::kem::StaticKem;
//! use rosenpass_cipher_traits::primitives::Kem;
//! use rosenpass_ciphers::StaticKem;
//! use rosenpass::{
//! protocol::{SSk, SPk, MsgBuf, PeerPtr, CryptoServer, SymKey},
//! };
@@ -38,11 +38,11 @@
//!
//! // initialize secret and public key for peer a ...
//! 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
//! 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
//! 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 rosenpass::protocol::{SSk, SPk, SymKey, Peer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem;
/// use rosenpass_cipher_traits::Kem;
/// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::primitives::Kem;
///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
///
/// 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());
/// StaticKem::keygen(sskt2.secret_mut(), spkt2.deref_mut())?;
/// StaticKem.keygen(sskt2.secret_mut(), spkt2.deref_mut())?;
///
/// let psk = SymKey::random();
///
@@ -834,7 +834,7 @@ pub trait Mortal {
///
/// ```
/// use std::ops::DerefMut;
/// use rosenpass_ciphers::kem::StaticKem;
/// use rosenpass_ciphers::StaticKem;
/// use rosenpass::protocol::{SSk, SPk, testutils::ServerForTesting, ProtocolVersion};
///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
@@ -1376,13 +1376,13 @@ impl CryptoServer {
/// ```
/// use std::ops::DerefMut;
/// use rosenpass::protocol::{SSk, SPk, CryptoServer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem;
/// use rosenpass_cipher_traits::Kem;
/// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::primitives::Kem;
///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
///
/// 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());
/// assert_eq!(srv.spkm, spkm);
@@ -1441,17 +1441,17 @@ impl CryptoServer {
/// ```
/// use std::ops::DerefMut;
/// use rosenpass::protocol::{SSk, SPk, SymKey, CryptoServer, ProtocolVersion};
/// use rosenpass_ciphers::kem::StaticKem;
/// use rosenpass_cipher_traits::Kem;
/// use rosenpass_ciphers::StaticKem;
/// use rosenpass_cipher_traits::primitives::Kem;
///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
///
/// 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 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();
///
@@ -1698,7 +1698,7 @@ impl Session {
///
/// ```
/// use rosenpass::protocol::{Session, HandshakeRole};
/// use rosenpass_ciphers::keyed_hash::KeyedHash;
/// use rosenpass_ciphers::KeyedHash;
///
/// rosenpass_secret_memory::secret_policy_try_use_memfd_secrets();
///