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
118
119
120
121
122
123
124
125
126
127
128
//! # Signature Extension
//!
//! This module provides functionality for digitally signing Envelopes and
//! verifying signatures, with optional metadata support.
//!
//! The signature extension allows:
//! - Signing envelope subjects to validate their authenticity
//! - Adding metadata to signatures (e.g., signer identity, date, purpose)
//! - Verification of signatures, both with and without metadata
//! - Support for multiple signatures on a single envelope
//!
//! ## Core Concepts
//!
//! 1. **Basic Signatures**: Sign an envelope's subject to verify its
//! authenticity, without modifying its content
//! 2. **Signatures with Metadata**: Add metadata to a signature that is itself
//! signed with the same key
//! 3. **Multi-Signatures**: Support for multiple signatures on a single
//! envelope, each potentially with its own metadata
//!
//! ## Signature Approaches
//!
//! The signature module supports two main approaches:
//!
//! 1. **Subject-Only Signing**: When `add_signature()` is called on an
//! envelope, only the subject is signed
//! 2. **Wrapped Envelope Signing**: When `sign()` is called, the entire
//! envelope (subject + assertions) is wrapped and then signed
//!
//! ## Usage Examples
//!
//! ### Basic Signature Example
//!
//! ```ignore
//! use bc_envelope::prelude::*;
//!
//! # fn main() -> bc_envelope::Result<()> {
//! # // In a real application, you would use proper key generation
//! # // The following would be your actual key variables from your application
//! # let alice_private_key = /* your private key */;
//! # let alice_public_key = /* your public key */;
//! # let bob_public_key = /* another public key */;
//!
//! // Create and sign an envelope
//! let envelope = Envelope::new("Hello.")
//! .add_signature(&alice_private_key);
//!
//! // The structure is "Hello." ['signed': Signature]
//!
//! // Verify the signature
//! assert!(envelope.has_signature_from(&alice_public_key)?);
//! assert!(!envelope.has_signature_from(&bob_public_key)?);
//!
//! // Extract the verified subject
//! let verified = envelope.verify_signature_from(&alice_public_key)?;
//! let message = verified.extract_subject::<String>()?;
//! assert_eq!(message, "Hello.");
//! # Ok(())
//! # }
//! ```
//!
//! ### Signature with Metadata Example
//!
//! ```ignore
//! use bc_envelope::prelude::*;
//! use known_values::NOTE;
//!
//! # fn main() -> bc_envelope::Result<()> {
//! # // In a real application, you would use proper key generation
//! # // The following would be your actual key variables from your application
//! # let alice_private_key = /* your private key */;
//! # let alice_public_key = /* your public key */;
//!
//! // Create and sign an envelope with metadata
//! let metadata = SignatureMetadata::new()
//! .with_assertion(NOTE, "Alice signed this.");
//!
//! let envelope = Envelope::new("Hello.")
//! .wrap()
//! .add_signature_opt(&alice_private_key, None, Some(metadata));
//!
//! // The structure is:
//! // {
//! // "Hello."
//! // } [
//! // 'signed': {
//! // Signature [
//! // 'note': "Alice signed this."
//! // ]
//! // } [
//! // 'signed': Signature
//! // ]
//! // ]
//!
//! // Verify signature and extract metadata
//! let (verified_envelope, metadata_envelope) = envelope.verify_returning_metadata(&alice_public_key)?;
//!
//! // Extract the note from metadata
//! let note = metadata_envelope.object_for_predicate(NOTE)?.extract_subject::<String>()?;
//! assert_eq!(note, "Alice signed this.");
//!
//! // Read the original message
//! let message = verified_envelope.extract_subject::<String>()?;
//! assert_eq!(message, "Hello.");
//! # Ok(())
//! # }
//! ```
//!
//! ## Signature Verification Workflow
//!
//! 1. For a simple signature, verification checks if the signature matches the
//! subject's digest
//! 2. For a signature with metadata:
//! - The outer signature is verified against the wrapped metadata envelope
//! - The inner signature (subject of the metadata envelope) is verified
//! against the original envelope's subject
//! - Both signatures must be made with the same key
//!
//! ## Implementation Details
//!
//! The signature system is implemented using cryptographic primitives from the
//! `bc-components` crate. The signature extensions make use of the `Signer` and
//! `Verifier` traits to provide a flexible interface for different
//! signature algorithms.
pub use SignatureMetadata;