pyrus_crypto/

lib.rs

//! # Pyrus Crypto
//!
//! This crate provides an OpenPGP inspired crypto system. It is 
//! based on generating certificates and using them to sign, encrypt 
//! and decrypt messages. Because it is designed for use in a larger 
//! application, this crate has some shortcomings. Mainly: symmetric 
//! encryption requires supplying a sender's certificate.
//!
//! # Warning!
//!
//! This is not a serious crypto crate. It has no tests and is not reviewed 
//! by third parties. It's security goes as far as the author's will 
//! to make his school project seem secure.
//!
//! # Examples
//!
//! ## Generate and serialize a certificate keeping its secret parts:
//! ```rust
//! # use std::error::Error;
//! use pyrus_crypto::prelude::*;
//!
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let larry = Cert::new("Larry <larry@gentoo.org>");
//! let cert_bytes = postcard::to_stdvec(&larry)?;
//!
//! //.. save the certificate
//! // use the certificate here
//! # Ok(())
//! # }
//! ```
//!
//! ## Encrypt a message symmetrically using a passphrase:
//! ```rust
//! # use std::error::Error;
//! use pyrus_crypto::prelude::*;
//!
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let larry: Cert = //..
//! # Cert::new("Larry <larry@gentoo.org>");
//! 
//! let secret_text = b"This is a very secret message";
//! let message = Message::new(&larry)?
//!     .write(&secret_text[..])?
//!     .encrypt_with(b"alcmdzmafia")? // don't use such passwords
//!     .finalize()?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Sign and encrypt a message asymmetrically:
//!
//! Note that the certificates are behind an [`std::sync::Arc`]. 
//! This is how they will usually appear in the wild.
//! ```rust
//! # use std::error::Error;
//! use pyrus_crypto::prelude::*;
//! # use std::sync::Arc;
//!
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let larry: Arc<Cert> = //..
//! # Arc::new(Cert::new("Larry <larry@gentoo.org>"));
//! let agentcow: Arc<Cert> = //..
//! # Arc::new(Cert::new("agentcow"));
//! let agenthorse: Arc<Cert> = //..
//! # Arc::new(Cert::new("agenthorse"));
//! let agentfox: Arc<Cert> = //..
//! # Arc::new(Cert::new("agentfox"));
//! let friends = vec![agentcow.clone(), agenthorse.clone()];
//!
//! let secret_text = b"Let's meet up in the evening";
//! let msg = Message::new(&larry)?
//!     .write(&secret_text[..])?
//!     .sign()
//!     .encrypt_for(&friends)?
//!     .finalize()?;
//! # Ok(())
//! # }
//! ```
//!
//! ## Decrypt a symmetrically encrypted message
//! ```rust
//! # use std::error::Error;
//! use pyrus_crypto::prelude::*;
//!
//! # fn main() -> Result<(), Box<dyn Error>> {
//! # let larry: Cert = Cert::new("Larry <larry@gentoo.org>");
//! # let secret_text = b"This is a very secret message";
//! # let message = Message::new(&larry)?
//! #     .write(&secret_text[..])?
//! #     .encrypt_with(b"alcmdzmafia")? // don't use such passwords
//! #     .finalize()?;
//! // another of the aforementioned shortcomings
//! let dummy = Cert::new("dummy cert");
//! // assume we already have a message
//! let (_, content, sig) = message
//!     .parse(&dummy)?
//!     .decrypt_with(&b"alcmdzmafia"[..])?
//!     .finalize();
//!
//! assert_eq!(&secret_text[..], &content[..]);
//! assert!(sig.is_none()); // the message is not signed
//! # Ok(())
//! # }
//! ```
//!
//! ## Decrypt and verify a signed message
//! ```rust
//! # use std::error::Error;
//! use pyrus_crypto::prelude::*;
//! # use std::sync::Arc;
//!
//! # fn main() -> Result<(), Box<dyn Error>> {
//! let larry: Arc<Cert> = //..
//! # Arc::new(Cert::new("Larry <larry@gentoo.org>"));
//! let agentcow: Arc<Cert> = //..
//! # Arc::new(Cert::new("agentcow"));
//! let agenthorse: Arc<Cert> = //..
//! # Arc::new(Cert::new("agenthorse"));
//! let agentfox: Arc<Cert> = //..
//! # Arc::new(Cert::new("agentfox"));
//! # let friends = vec![agentcow.clone(), agenthorse.clone()];
//!
//! let secret_text = b"Let's meet up in the evening";
//! # let message = Message::new(&larry)?
//! #     .write(&secret_text[..])?
//! #     .sign()
//! #     .encrypt_for(&friends)?
//! #     .finalize()?;
//! let (message, content, signature) = message
//!     .parse(&agentcow)? // decrypt using agentcow's certificate
//!     .decrypt(larry.clone())?
//!     .verify_signature(larry.clone())?
//!     .finalize();
//!
//! assert_eq!(&secret_text[..], &content[..]);
//! assert!(signature.unwrap()); // signature is Some and is good
//!
//! let fail = message
//!     .parse(&agentfox)?
//!     .decrypt(larry.clone());
//! assert!(fail.is_err()); // cannot decrypt, not a recipient
//! # Ok(())
//! # }
//! ```

/// Certificate generation and serialization.
pub mod cert;
/// Message creation and parsing.
pub mod message;
/// Cryptographic primitives, the foundation of this crate.
pub mod crypto;
/// [`CryptoError`](crate::error::CryptoError) type and 
/// [`Result<T>`](crate::error::Result) type specialization.
pub mod error;
/// Re-exports commonly used types
pub mod prelude;

/// Alias for the certificate's fingerprint type.
///
/// The hash type is [`blake3::Hash`].
///
/// # A note on equality
/// To ensure constant time equality checking it is recommended to keep 
/// the type as is. Check the [`blake3`] crate documentation for more 
/// information.
pub type Fingerprint = blake3::Hash;

fn timestamp_bytes() -> [u8; 8] {
    use std::time::{SystemTime, UNIX_EPOCH};
    use rand_core::{OsRng, RngCore};
    if let Ok(t) = SystemTime::now().duration_since(UNIX_EPOCH) {
        let t = t.as_secs();
        t.to_le_bytes()
    } else {
        let mut t = [0; 8];
        OsRng.fill_bytes(&mut t);
        t
    }
}