bitwarden_crypto/signing/
mod.rs

1//! Signing is used to assert integrity of a message to others or to oneself.
2//!
3//! Signing and signature verification operations are divided into three layers here:
4//! - (public) High-level: Give a struct, namespace, and get a signed object or signature +
5//!   serialized message. Purpose: Serialization should not be decided by the consumer of this
6//!   interface, but rather by the signing implementation. Each consumer shouldn't have to make the
7//!   decision on how to serialize. Further, the serialization format is written to the signature
8//!   object, and verified.
9//!
10//! - Mid-level: Give a byte array, content format, namespace, and get a signed object or signature.
11//!   Purpose: All signatures should be domain-separated, so that any proofs only need to consider
12//!   the allowed messages under the current namespace, and cross-protocol attacks are not possible.
13//!
14//! - Low-level: Give a byte array, and get a signature. Purpose: This just implements the signing
15//!   of byte arrays. Digital signature schemes generally just care about a set of input bytes to
16//!   sign; and this operation implements that per-supported digital signature scheme. To add
17//!   support for a new scheme, only this operation needs to be implemented for the new signing key
18//!   type. This is implemented in the ['signing_key'] and ['verifying_key'] modules.
19//!
20//! Signing operations are split into two types. The mid-level and high-level operations are
21//! implemented for each type respectively.
22//! - Sign: Create a [`signed_object::SignedObject`] that contains the payload. Purpose: If only one
23//!   signature is needed for an object then it is simpler to keep the signature and payload
24//!   together in one blob, so they cannot be separated.
25//!
26//! - Sign detached: Create a [`signature::Signature`] that does not contain the payload; but the
27//!   serialized payload is returned. Purpose: If multiple signatures are needed for one object,
28//!   then sign detached can be used.
29
30mod cose;
31use cose::*;
32mod namespace;
33pub use namespace::SigningNamespace;
34mod signed_object;
35pub use signed_object::SignedObject;
36mod signature;
37pub use signature::Signature;
38mod signing_key;
39pub use signing_key::SigningKey;
40mod verifying_key;
41pub use verifying_key::VerifyingKey;
42mod message;
43pub use message::SerializedMessage;
44
45/// The type of key / signature scheme used for signing and verifying.
46#[derive(Debug, PartialEq)]
47pub enum SignatureAlgorithm {
48    /// Ed25519 is the modern, secure recommended option for digital signatures on eliptic curves,
49    /// safe under the assumption that an attacker does not have access to a large-scale quantum
50    /// computer.
51    Ed25519,
52    /// ML-DSA-44 is the NIST post-quantum digital signature standard (FIPS 204), security category
53    /// 2.
54    MlDsa44,
55}
56
57impl SignatureAlgorithm {
58    /// Returns the currently accepted safe algorithm for new keys.
59    pub fn default_algorithm() -> Self {
60        SignatureAlgorithm::MlDsa44
61    }
62}
63
64impl std::fmt::Display for SignatureAlgorithm {
65    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
66        match self {
67            SignatureAlgorithm::Ed25519 => write!(f, "ed25519"),
68            SignatureAlgorithm::MlDsa44 => write!(f, "mldsa44"),
69        }
70    }
71}
72
73#[cfg(test)]
74mod tests {
75    use serde::{Deserialize, Serialize};
76
77    use super::*;
78    use crate::CoseSerializable;
79
80    #[derive(Deserialize, Debug, PartialEq, Serialize)]
81    struct TestMessage {
82        field1: String,
83    }
84
85    /// The function used to create the test vectors below, and can be used to re-generate them.
86    /// Once rolled out to user accounts, this function can be removed, because at that point we
87    /// cannot introduce format-breaking changes anymore.
88    #[test]
89    fn make_test_vectors() {
90        let signing_key = SigningKey::make(SignatureAlgorithm::Ed25519);
91        let verifying_key = signing_key.to_verifying_key();
92        let test_message = TestMessage {
93            field1: "Test message".to_string(),
94        };
95        let (signature, serialized_message) = signing_key
96            .sign_detached(&test_message, &SigningNamespace::ExampleNamespace)
97            .unwrap();
98        let signed_object = signing_key
99            .sign(&test_message, &SigningNamespace::ExampleNamespace)
100            .unwrap();
101        let raw_signed_array = signing_key.sign_raw("Test message".as_bytes());
102        println!("const SIGNING_KEY: &[u8] = &{:?};", signing_key.to_cose());
103        println!(
104            "const VERIFYING_KEY: &[u8] = &{:?};",
105            verifying_key.to_cose()
106        );
107        println!("const SIGNATURE: &[u8] = &{:?};", signature.to_cose());
108        println!(
109            "const SERIALIZED_MESSAGE: &[u8] = &{:?};",
110            serialized_message.as_bytes()
111        );
112        println!(
113            "const SIGNED_OBJECT: &[u8] = &{:?};",
114            signed_object.to_cose()
115        );
116        println!(
117            "const SIGNED_OBJECT_RAW: &[u8] = &{:?};",
118            raw_signed_array.as_slice()
119        );
120    }
121}
bitwarden_crypto/signing/mod.rs

bitwarden_crypto/signing/
mod.rs
