pyrus_crypto/message/

mod.rs

mod header;
pub use header::{Header, MessageType};

mod builder;
pub use builder::MessageBuilder;
pub use builder::MessageFinal;

mod parser;
pub use parser::MessageParser;

use base64::prelude::*;

use postcard;
use serde::{Deserialize, Serialize};

use crate::Fingerprint;
use crate::cert::Cert;
use crate::error::{CryptoError, Result};

mod ser;

/// A struct describing a message.
///
/// Each message is composed of:
/// * a payload - optionally encrypted binary data,
/// * a header - [`Header`] struct containing the message's metadata.
///
/// A message is constructed by using the [`Message::new`] function which 
/// returns a [`MessageBuilder`]. Then the builder configures the message using 
/// the state pattern and after calling `finalize()` returns a message ready 
/// for sending.
///
/// # Serialization
///
/// Messages implement [`serde::Serialize`] and [`serde::Deserialize`] 
/// traits, which allow for serialization and deserialization using any 
/// serde format. Additionally for human readable formats messages
/// serialize bytes as hex encoded strings to please the users' eyes.
///
/// # Examples
///
/// Constructing a signed and encrypted message.
/// ```rust
/// # use std::error::Error;
/// use pyrus_crypto::message::Message;
/// use pyrus_crypto::message::MessageFinal;
/// # use pyrus_crypto::cert::Cert;
/// # 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::new(Cert::new("agentcow"));
/// # let agenthorse = Arc::new(Cert::new("agenthorse"));
/// # let friends = vec![agentcow.clone(), agenthorse.clone()];
/// let secret_text = b"Let's meet up in the evening";
/// let msg = Message::new(&larry)? // returns MessageBuilder here
///     .write(&secret_text[..])? // MessageBuilder
///     .sign() // SignedMessage (almost the same API as the builder)
///     .encrypt_for(&friends)? // AsmEncryptedMessage (can only finalize)
///     .finalize()?; // returns Message
/// # Ok(())
/// # }
/// ```
///
/// The message may then be base64 encoded for transmission:
/// ```rust
/// # use std::error::Error;
/// # use pyrus_crypto::message::Message;
/// # use pyrus_crypto::message::MessageFinal;
/// # use pyrus_crypto::cert::Cert;
/// # 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::new(Cert::new("agentcow"));
/// # let agenthorse = Arc::new(Cert::new("agenthorse"));
/// # 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()?;
/// let b64msg: String = msg.b64encode()?;
/// # let msg_recv = Message::b64decode(b64msg.as_bytes())?;
/// # assert_eq!(msg, msg_recv);
/// # Ok(())
/// # }
/// ```
/// And then decoded back into a message:
/// ```rust
/// # use std::error::Error;
/// # use pyrus_crypto::message::Message;
/// # use pyrus_crypto::message::MessageFinal;
/// # use pyrus_crypto::cert::Cert;
/// # 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::new(Cert::new("agentcow"));
/// # let agenthorse = Arc::new(Cert::new("agenthorse"));
/// # 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()?;
/// # let b64msg: String = msg.b64encode()?;
/// let msg_recv = Message::b64decode(b64msg.as_bytes())?;
/// assert_eq!(msg, msg_recv);
/// # Ok(())
/// # }
/// ```
#[derive(Serialize, Deserialize, Debug, PartialEq, Clone)]
pub struct Message {
    header: Header,
    #[serde(with = "ser::payload")]
    payload: Vec<u8>,
}

impl Message {
    /// Starts the construction of the message by returning a 
    /// [`MessageBuilder`]. The builder should be a temporary object 
    /// and live only for a short duration in a method call chain.
    ///
    /// # Errors
    /// * [`CryptoError::NotSecret`] if the issuer's certificate does not 
    /// contain secret keys. (This is not your certificate, why do you try to 
    /// impersonate people?)
    pub fn new<'a>(issuer: &'a Cert) -> Result<MessageBuilder<'a>> {
        if issuer.is_secret() {
            Ok(MessageBuilder {
                issuer,
                payload: Vec::new(),
            })
        } else {
            Err(CryptoError::NotSecret)
        }
    }

    /// Reads the header of the message, discards any associated data and 
    /// returns the type of the message. See [`MessageDesc`] for more details.
    pub fn describe(&self) -> MessageDesc {
        match self.header.msg_type {
            MessageType::Signed { .. } => MessageDesc::Signed,
            MessageType::EncryptedSym { .. } => MessageDesc::EncryptedSym,
            MessageType::EncryptedAsm { .. } => MessageDesc::EncryptedAsm,
            MessageType::SignedEncryptedSym { .. } => MessageDesc::SignedEncryptedSym,
            MessageType::SignedEncryptedAsm { .. } => MessageDesc::SignedEncryptedAsm,
        }
    }

    /// Convenience function. Instead of checking the header for the message
    /// issuer, this function may be use to forward it.
    pub fn issuer(&self) -> &Fingerprint {
        &self.header.issuer
    }

    /// Returns the header of this message for inspection. In reality this is 
    /// only useful for automated message parsing. The [`MessageParser`] 
    /// internals access the header differently.
    pub fn header(&self) -> &Header {
        &self.header
    }

    /// Returns the payload of this message. The payload is the optionally 
    /// encrypted message content and on its own is not useful unless the goal 
    /// is to implement automated message parsing.
    pub fn payload(&self) -> &[u8] {
        &self.payload
    }

    /// Starts the process of message parsing. See [`MessageParser`] for more 
    /// details.
    ///
    /// # Errors
    /// * [`CryptoError::NotSecret`] if the recipient's (decrypting) 
    /// certificate does not contain secret keys.
    pub fn parse<'a>(self, recipient: &'a Cert) -> Result<MessageParser<'a>> {
        if recipient.is_secret() {
            Ok(MessageParser {
                recipient,
                desc: self.describe(),
                message: self,
                payload: Vec::new(),
                verified: None
            })
        } else {
            Err(CryptoError::NotSecret)
        }
    }

    /// Encodes the message as a base64 string.
    ///
    /// # Errors
    /// * [`CryptoError::SerializationError`] if a serialization error occured.
    pub fn b64encode(&self) -> Result<String> {
        let bytes = postcard::to_stdvec(self)?;
        Ok(BASE64_STANDARD.encode(bytes))
    }

    /// Decodes a message from a base64 representation.
    ///
    /// # Errors
    /// * [`CryptoError::SerializationError`] if a serialization error occured.
    /// * [`CryptoError::DecodingError`] if the base64 representation is 
    /// invalid.
    pub fn b64decode(repr: impl AsRef<[u8]>) -> Result<Self> {
        let bytes = BASE64_STANDARD.decode(repr.as_ref())?;
        Ok(postcard::from_bytes(&bytes)?)
    }
}

/// Describes the message structure.
///
/// In case the message is signed it should always be signed first 
/// and then encrypted, i.e. the signature should be done over the 
/// plaintext.
#[derive(Debug)]
pub enum MessageDesc {
    /// Plaintext message. Only possible after using a message parser.
    Plaintext,
    /// Signed message.
    Signed,
    /// Symmetrically encrypted message.
    EncryptedSym,
    /// Asymmetrically encrypted message.
    EncryptedAsm,
    /// Signed and symmetrically encrypted message.
    SignedEncryptedSym,
    /// Signed and asymmetrically encrypted message.
    SignedEncryptedAsm,
}

impl std::fmt::Display for MessageDesc {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        let name = match self {
            MessageDesc::Plaintext => "Plaintext",
            MessageDesc::Signed => "Signed",
            MessageDesc::EncryptedSym => "Symmetrically Encrypted",
            MessageDesc::EncryptedAsm => "Asymmetrically Encrypted",
            MessageDesc::SignedEncryptedSym => "Signed & Symmetrically Encrypted",
            MessageDesc::SignedEncryptedAsm => "Signed & Asymmetrically Encrypted",
        };
        write!(f, "{name}")
    }
}

#[cfg(test)]
mod tests;