cose2 0.3.0

A Rust library for CBOR Object Signing and Encryption (COSE, RFC 9052) and CBOR Web Token (CWT, RFC 8392), built on cbor2.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

//! Pluggable cryptographic interfaces.
//!
//! `cose2` models COSE structures but does not implement cryptography
//! itself. Callers supply signing, verification, MAC and encryption by
//! implementing these traits with the crypto library of their choice.

use crate::{Error, Label};

/// AEAD inputs prepared by a COSE_Encrypt or COSE_Encrypt0 message.
///
/// `aad` is the encoded `Enc_structure` from RFC 9052 ยง5.3. Pass both values
/// to external encryption or decryption code together with the plaintext or
/// ciphertext bytes.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct EncryptionContext {
    /// The nonce (IV) to pass to the AEAD operation.
    pub nonce: Vec<u8>,
    /// The additional authenticated data to pass to the AEAD operation.
    pub aad: Vec<u8>,
}

/// Produces digital signatures for COSE_Sign and COSE_Sign1.
///
/// Reference: <https://datatracker.ietf.org/doc/html/rfc9052#name-signature-algorithms>.
pub trait Signer {
    /// The COSE algorithm identifier this signer uses.
    ///
    /// Returning `None` leaves the `alg` header untouched. Returning `Some`
    /// writes the identifier when it is absent, or checks that an existing
    /// protected `alg` value matches. COSE algorithm identifiers are
    /// `int / tstr`, represented by [`Label`].
    fn alg(&self) -> Option<Label> {
        None
    }

    /// The key identifier to write to the unprotected header.
    ///
    /// Returning `None` leaves the `kid` header untouched.
    fn kid(&self) -> Option<&[u8]> {
        None
    }

    /// Computes the signature over `data`.
    fn sign(&self, data: &[u8]) -> Result<Vec<u8>, Error>;
}

/// Verifies digital signatures for COSE_Sign and COSE_Sign1.
pub trait Verifier {
    /// The COSE algorithm identifier this verifier expects, if any.
    fn alg(&self) -> Option<Label> {
        None
    }

    /// The key identifier matched against a message's `kid` header, if any.
    fn kid(&self) -> Option<&[u8]> {
        None
    }

    /// Returns `Ok(())` if `signature` is valid for `data`, otherwise an error.
    fn verify(&self, data: &[u8], signature: &[u8]) -> Result<(), Error>;
}

/// Computes and verifies message authentication codes for COSE_Mac and
/// COSE_Mac0.
///
/// Reference: <https://datatracker.ietf.org/doc/html/rfc9052#name-message-authentication-code>.
pub trait Macer {
    /// The COSE algorithm identifier this MACer uses, if any.
    fn alg(&self) -> Option<Label> {
        None
    }

    /// The key identifier to write to the unprotected header, if any.
    fn kid(&self) -> Option<&[u8]> {
        None
    }

    /// Computes the authentication tag over `data`.
    fn mac_create(&self, data: &[u8]) -> Result<Vec<u8>, Error>;

    /// Returns `Ok(())` if `tag` is a correct MAC for `data`.
    fn mac_verify(&self, data: &[u8], tag: &[u8]) -> Result<(), Error>;
}

/// Encrypts and decrypts content for COSE_Encrypt and COSE_Encrypt0.
///
/// Reference: <https://datatracker.ietf.org/doc/html/rfc9052#name-content-encryption-algorith>.
pub trait Encryptor {
    /// The COSE algorithm identifier this encryptor uses, if any.
    fn alg(&self) -> Option<Label> {
        None
    }

    /// The key identifier to write to the unprotected header, if any.
    fn kid(&self) -> Option<&[u8]> {
        None
    }

    /// The nonce (IV) size, in bytes, this encryptor expects.
    fn nonce_size(&self) -> usize;

    /// The Base IV / Context IV used to derive the nonce when a COSE message
    /// carries `Partial IV` instead of a full `IV`.
    ///
    /// Returning `None` rejects messages that use `Partial IV`. When present,
    /// the slice length must match [`nonce_size`](Self::nonce_size); the
    /// message nonce is the Base IV XORed with the left-padded Partial IV.
    fn base_iv(&self) -> Option<&[u8]> {
        None
    }

    /// Encrypts `plaintext` with `nonce` and additional authenticated data.
    fn encrypt(&self, nonce: &[u8], plaintext: &[u8], aad: &[u8]) -> Result<Vec<u8>, Error>;

    /// Decrypts `ciphertext` with `nonce` and additional authenticated data.
    fn decrypt(&self, nonce: &[u8], ciphertext: &[u8], aad: &[u8]) -> Result<Vec<u8>, Error>;
}