cose2 0.5.0

//! COSE_Mac0: MAC without recipients (RFC 9052 §6.2).

use cbor2::Cbor;

use crate::{
    header::{decode_protected, encode_protected, validate_header_buckets},
    iana, tag, util, Error, Header, Label, Macer,
};

/// The on-the-wire COSE_Mac0 array: `[protected, unprotected, payload, tag]`.
#[derive(Clone, Debug, PartialEq, Cbor)]
#[cbor(tag = 17, array)]
struct Mac0Wire {
    #[serde(with = "crate::strict::bytes")]
    protected: Vec<u8>,
    unprotected: Header,
    #[serde(with = "crate::strict::optional_bytes")]
    payload: Option<Vec<u8>>,
    #[serde(with = "crate::strict::bytes")]
    tag: Vec<u8>,
}

/// A COSE_Mac0 message.
///
/// Reference: <https://datatracker.ietf.org/doc/html/rfc9052#name-maced-messages-with-implici>.
#[derive(Clone, Debug, Default, PartialEq)]
pub struct Mac0Message {
    /// Protected header parameters (e.g. `alg`), authenticated by the tag.
    pub protected: Header,
    /// Unprotected header parameters (e.g. `kid`).
    pub unprotected: Header,
    /// The payload, or `None` when detached.
    pub payload: Option<Vec<u8>>,
    tag: Vec<u8>,
    protected_raw: Vec<u8>,
    state: util::OperationState,
}

impl Mac0Message {
    /// Creates a new message with the given payload.
    pub fn new(payload: Option<Vec<u8>>) -> Self {
        Mac0Message {
            payload,
            ..Default::default()
        }
    }

    /// Encodes the `MAC_structure` to be authenticated (RFC 9052 §6.3).
    ///
    /// This is the low-level helper for external or async MAC code. New
    /// messages should usually call [`prepare_tag`](Self::prepare_tag) or
    /// [`prepare_detached_tag`](Self::prepare_detached_tag) so the protected
    /// header bytes stored in the message match the bytes being MACed.
    pub fn to_be_maced(
        protected_raw: &[u8],
        external_aad: &[u8],
        payload: &[u8],
    ) -> Result<Vec<u8>, Error> {
        util::encode_structure(&(
            "MAC0",
            serde_bytes::Bytes::new(protected_raw),
            serde_bytes::Bytes::new(external_aad),
            serde_bytes::Bytes::new(payload),
        ))
    }

    /// Prepares this embedded-payload message for an externally produced tag.
    ///
    /// The returned bytes are the `MAC_structure` that must be MACed. After an
    /// async or remote MAC service returns the tag bytes, call
    /// [`set_tag`](Self::set_tag) and then [`to_vec`](Self::to_vec).
    pub fn prepare_tag(
        &mut self,
        alg: Option<Label>,
        kid: Option<&[u8]>,
        external_aad: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        self.prepare_tag_headers(alg, kid)?;
        let payload = util::require_embedded_payload(&self.payload, "Mac0Message::prepare_tag")?;
        Self::to_be_maced(&self.protected_raw, external_aad.unwrap_or(&[]), payload)
    }

    /// Prepares this detached-payload message for an externally produced tag.
    ///
    /// The message's on-the-wire payload is set to `nil`; `detached_payload` is
    /// used only in the `MAC_structure`.
    pub fn prepare_detached_tag(
        &mut self,
        alg: Option<Label>,
        kid: Option<&[u8]>,
        detached_payload: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        self.prepare_tag_headers(alg, kid)?;
        let tbm = Self::to_be_maced(
            &self.protected_raw,
            external_aad.unwrap_or(&[]),
            detached_payload,
        )?;
        self.payload = None;
        Ok(tbm)
    }

    fn prepare_tag_headers(&mut self, alg: Option<Label>, kid: Option<&[u8]>) -> Result<(), Error> {
        util::ensure_protected_alg(&mut self.protected, &mut self.unprotected, alg)?;
        util::ensure_unprotected_kid(&self.protected, &mut self.unprotected, kid)?;
        validate_header_buckets(&self.protected, &self.unprotected)?;
        let protected_raw = encode_protected(&self.protected)?;
        self.protected_raw = protected_raw;
        self.state = util::OperationState::Prepared;
        self.tag.clear();
        Ok(())
    }

    /// Stores externally produced tag bytes on this message.
    pub fn set_tag(&mut self, tag: impl Into<Vec<u8>>) -> Result<(), Error> {
        validate_header_buckets(&self.protected, &self.unprotected)?;
        if !self.state.initialized() {
            self.protected_raw = encode_protected(&self.protected)?;
        }
        crate::header::validate_protected_state(&self.protected, &self.protected_raw)?;
        self.tag = tag.into();
        self.state = util::OperationState::Complete;
        Ok(())
    }

    /// Computes the authentication tag with `macer`.
    pub fn compute(&mut self, macer: &dyn Macer, external_aad: Option<&[u8]>) -> Result<(), Error> {
        self.prepare_tag_headers(macer.alg(), macer.kid())?;
        let payload = util::require_embedded_payload(&self.payload, "Mac0Message::compute")?;
        let tbm = Self::to_be_maced(&self.protected_raw, external_aad.unwrap_or(&[]), payload)?;
        let tag = macer.mac_create(&tbm)?;
        self.set_tag(tag)
    }

    /// Computes the authentication tag over a detached payload.
    ///
    /// The message's on-the-wire payload is set to `nil`; `detached_payload`
    /// is used only in the `MAC_structure`.
    pub fn compute_detached(
        &mut self,
        macer: &dyn Macer,
        detached_payload: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<(), Error> {
        self.prepare_tag_headers(macer.alg(), macer.kid())?;
        let tbm = Self::to_be_maced(
            &self.protected_raw,
            external_aad.unwrap_or(&[]),
            detached_payload,
        )?;
        let tag = macer.mac_create(&tbm)?;
        self.set_tag(tag)?;
        self.payload = None;
        Ok(())
    }

    /// Computes the tag and encodes the message to tagged COSE_Mac0 bytes.
    pub fn compute_and_encode(
        &mut self,
        macer: &dyn Macer,
        external_aad: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        self.compute(macer, external_aad)?;
        self.to_vec()
    }

    /// Computes a detached-payload tag and encodes the message.
    pub fn compute_detached_and_encode(
        &mut self,
        macer: &dyn Macer,
        detached_payload: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<Vec<u8>, Error> {
        self.compute_detached(macer, detached_payload, external_aad)?;
        self.to_vec()
    }

    /// Encodes a computed message to tagged COSE_Mac0 bytes.
    pub fn to_vec(&self) -> Result<Vec<u8>, Error> {
        self.encode(tag::MAC0_PREFIX)
    }

    /// Encodes this tagged COSE_Mac0 as a CWT (`61(17(...))`).
    pub fn to_cwt_vec(&self) -> Result<Vec<u8>, Error> {
        self.encode(tag::CWT_MAC0_PREFIX)
    }

    /// Encodes a computed message to canonical COSE_Mac0 bytes without the CBOR tag.
    pub fn to_untagged_vec(&self) -> Result<Vec<u8>, Error> {
        self.encode(&[])
    }

    /// Serializes the wire array borrowing this message's buffers.
    fn encode(&self, prefix: &[u8]) -> Result<Vec<u8>, Error> {
        if !self.state.complete() {
            return Err(Error::InvalidState(
                "Mac0Message must be computed before encoding".into(),
            ));
        }
        validate_header_buckets(&self.protected, &self.unprotected)?;
        crate::header::validate_protected_state(&self.protected, &self.protected_raw)?;
        let unprotected = util::canonical_raw(&self.unprotected)?;
        util::encode_prefixed(
            prefix,
            &(
                serde_bytes::Bytes::new(&self.protected_raw),
                &unprotected,
                self.payload.as_deref().map(serde_bytes::Bytes::new),
                serde_bytes::Bytes::new(&self.tag),
            ),
        )
    }

    /// Decodes a COSE_Mac0 message (tagged or untagged) without verifying it.
    pub fn from_slice(data: &[u8]) -> Result<Self, Error> {
        let body = tag::message_body(data, Self::TAG)?;
        let wire: Mac0Wire = cbor2::from_slice(body)?;
        let protected = decode_protected(&wire.protected)?;
        validate_header_buckets(&protected, &wire.unprotected)?;
        Ok(Mac0Message {
            protected,
            unprotected: wire.unprotected,
            payload: wire.payload,
            tag: wire.tag,
            protected_raw: wire.protected,
            state: util::OperationState::Complete,
        })
    }

    /// Verifies the authentication tag with `macer`.
    pub fn verify(&self, macer: &dyn Macer, external_aad: Option<&[u8]>) -> Result<(), Error> {
        if !self.state.complete() {
            return Err(Error::InvalidState(
                "Mac0Message must be decoded before verifying".into(),
            ));
        }
        let payload = util::require_embedded_payload(&self.payload, "Mac0Message::verify")?;
        self.verify_payload(macer, payload, external_aad.unwrap_or(&[]))
    }

    /// Verifies the authentication tag over a detached payload.
    pub fn verify_detached(
        &self,
        macer: &dyn Macer,
        detached_payload: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<(), Error> {
        if !self.state.complete() {
            return Err(Error::InvalidState(
                "Mac0Message must be decoded before verifying".into(),
            ));
        }
        if self.payload.is_some() {
            return Err(Error::Custom(
                "Mac0Message carries an embedded payload; use verify".into(),
            ));
        }
        self.verify_payload(macer, detached_payload, external_aad.unwrap_or(&[]))
    }

    fn verify_payload(
        &self,
        macer: &dyn Macer,
        payload: &[u8],
        external_aad: &[u8],
    ) -> Result<(), Error> {
        crate::header::validate_protected_state(&self.protected, &self.protected_raw)?;
        self.protected
            .ensure_crit_understood(macer.understood_critical_headers())?;
        util::check_protected_alg(&self.protected, &self.unprotected, macer.alg())?;
        let tbm = Self::to_be_maced(&self.protected_raw, external_aad, payload)?;
        macer.mac_verify(&tbm, &self.tag)
    }

    /// Decodes and verifies a COSE_Mac0 message in one step.
    pub fn verify_and_decode(
        macer: &dyn Macer,
        data: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<Self, Error> {
        let msg = Self::from_slice(data)?;
        msg.verify(macer, external_aad)?;
        Ok(msg)
    }

    /// Decodes and verifies a detached-payload COSE_Mac0 message in one step.
    pub fn verify_detached_and_decode(
        macer: &dyn Macer,
        data: &[u8],
        detached_payload: &[u8],
        external_aad: Option<&[u8]>,
    ) -> Result<Self, Error> {
        let msg = Self::from_slice(data)?;
        msg.verify_detached(macer, detached_payload, external_aad)?;
        Ok(msg)
    }

    /// Returns the authentication tag (empty until computed/decoded).
    pub fn tag(&self) -> &[u8] {
        &self.tag
    }

    /// Returns the protected-header bytes used in the MAC structure.
    pub fn protected_raw(&self) -> &[u8] {
        &self.protected_raw
    }

    /// The on-the-wire CBOR tag for COSE_Mac0.
    pub const TAG: u64 = iana::CBORTagCOSEMac0;
}

#[cfg(test)]
mod tests {
    use super::*;

    fn assert_cbor_shape<T: cbor2::Cbor>(tag: Option<u64>, array: bool) {
        assert_eq!(T::TAG, tag);
        assert_eq!(T::ARRAY, array);
    }

    #[test]
    fn wire_metadata_declares_tagged_array_shape() {
        assert_cbor_shape::<Mac0Wire>(Some(iana::CBORTagCOSEMac0), true);
    }
}