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;
44use schemars::JsonSchema;
45use serde::{Deserialize, Serialize};
46#[cfg(feature = "wasm")]
47use {tsify_next::Tsify, wasm_bindgen::prelude::*};
48
49/// The type of key / signature scheme used for signing and verifying.
50#[derive(Serialize, Deserialize, Debug, JsonSchema, PartialEq)]
51#[serde(rename_all = "camelCase", deny_unknown_fields)]
52#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]
53#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]
54pub enum SignatureAlgorithm {
55    /// Ed25519 is the modern, secure recommended option for digital signatures on eliptic curves.
56    Ed25519,
57}
58
59impl SignatureAlgorithm {
60    /// Returns the currently accepted safe algorithm for new keys.
61    pub fn default_algorithm() -> Self {
62        SignatureAlgorithm::Ed25519
63    }
64}
65
66#[cfg(test)]
67mod tests {
68    use super::*;
69    use crate::CoseSerializable;
70
71    #[derive(Deserialize, Debug, PartialEq, Serialize)]
72    struct TestMessage {
73        field1: String,
74    }
75
76    /// The function used to create the test vectors below, and can be used to re-generate them.
77    /// Once rolled out to user accounts, this function can be removed, because at that point we
78    /// cannot introduce format-breaking changes anymore.
79    #[test]
80    fn make_test_vectors() {
81        let signing_key = SigningKey::make(SignatureAlgorithm::Ed25519);
82        let verifying_key = signing_key.to_verifying_key();
83        let test_message = TestMessage {
84            field1: "Test message".to_string(),
85        };
86        let (signature, serialized_message) = signing_key
87            .sign_detached(&test_message, &SigningNamespace::ExampleNamespace)
88            .unwrap();
89        let signed_object = signing_key
90            .sign(&test_message, &SigningNamespace::ExampleNamespace)
91            .unwrap();
92        let raw_signed_array = signing_key.sign_raw("Test message".as_bytes());
93        println!("const SIGNING_KEY: &[u8] = &{:?};", signing_key.to_cose());
94        println!(
95            "const VERIFYING_KEY: &[u8] = &{:?};",
96            verifying_key.to_cose()
97        );
98        println!("const SIGNATURE: &[u8] = &{:?};", signature.to_cose());
99        println!(
100            "const SERIALIZED_MESSAGE: &[u8] = &{:?};",
101            serialized_message.as_bytes()
102        );
103        println!(
104            "const SIGNED_OBJECT: &[u8] = &{:?};",
105            signed_object.to_cose()
106        );
107        println!(
108            "const SIGNED_OBJECT_RAW: &[u8] = &{:?};",
109            raw_signed_array.as_slice()
110        );
111    }
112}
bitwarden_crypto/signing/mod.rs

bitwarden_crypto/signing/
mod.rs
