massa_models/
secure_share.rs

1use std::fmt::Display;
2
3use crate::{address::Address, error::ModelsError};
4use massa_hash::Hash;
5use massa_serialization::{Deserializer, SerializeError, Serializer};
6use massa_signature::{
7    KeyPair, PublicKey, PublicKeyDeserializer, Signature, SignatureDeserializer,
8};
9use nom::{
10    error::{context, ContextError, ParseError},
11    sequence::tuple,
12    IResult,
13};
14use serde::{Deserialize, Serialize};
15
16/// Packages type T such that it can be securely sent and received in a trust-free network
17///
18/// If the internal content is mutated, then it must be re-wrapped, as the associated
19/// signature, serialized data, etc. would no longer be in sync
20#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
21pub struct SecureShare<T, ID>
22where
23    T: Display + SecureShareContent,
24    ID: Id,
25{
26    /// Reference contents. Not required for the security protocols.
27    ///
28    /// Use the Lightweight equivalent structures when you need verifiable
29    /// serialized data, but do not need to read the values directly (such as when sending)
30    pub content: T,
31    #[serde(skip)]
32    /// Content in sharable, deserializable form. Is used in the secure verification protocols.
33    pub serialized_data: Vec<u8>,
34
35    /// A cryptographically generated value using `serialized_data` and a public key.
36    pub signature: Signature,
37    /// The public-key component used in the generation of the signature
38    pub content_creator_pub_key: PublicKey,
39    /// Derived from the same public key used to generate the signature
40    pub content_creator_address: Address,
41    /// A secure hash of the data. See also [massa_hash::Hash]
42    pub id: ID,
43}
44
45/// Used by signed structure
46/// TODO: Make this trait use versions
47pub trait Id {
48    /// New id from hash
49    fn new(hash: Hash) -> Self;
50    /// Get a reference to the underlying hash
51    fn get_hash(&self) -> &Hash;
52}
53
54/// Trait that define a structure that can be signed for secure sharing.
55pub trait SecureShareContent
56where
57    Self: Sized + Display,
58{
59    /// Sign the SecureShare given the content, on chain `chain_id`
60    /// (see [`Self::compute_signed_hash`]).
61    fn sign(
62        &self,
63        keypair: &KeyPair,
64        content_hash: &Hash,
65        chain_id: u64,
66    ) -> Result<Signature, ModelsError> {
67        Ok(keypair.sign(&self.compute_signed_hash(
68            &keypair.get_public_key(),
69            content_hash,
70            chain_id,
71        ))?)
72    }
73
74    /// Verify a signature produced on chain `chain_id`
75    /// (see [`Self::compute_signed_hash`]).
76    fn verify_signature(
77        &self,
78        public_key: &PublicKey,
79        content_hash: &Hash,
80        signature: &Signature,
81        chain_id: u64,
82    ) -> Result<(), ModelsError> {
83        Ok(public_key.verify_signature(
84            &self.compute_signed_hash(public_key, content_hash, chain_id),
85            signature,
86        )?)
87    }
88
89    /// Using the provided key-pair, applies a cryptographic signature, and packages
90    /// the data required to share and verify the data in a trust-free network of peers.
91    ///
92    /// `chain_id` is used for both the content id ([`Self::compute_hash`]) and the
93    /// signed hash ([`Self::compute_signed_hash`]).
94    fn new_verifiable<Ser: Serializer<Self>, ID: Id>(
95        self,
96        content_serializer: Ser,
97        keypair: &KeyPair,
98        chain_id: u64,
99    ) -> Result<SecureShare<Self, ID>, ModelsError> {
100        let mut content_serialized = Vec::new();
101        content_serializer.serialize(&self, &mut content_serialized)?;
102        let public_key = keypair.get_public_key();
103        let hash = Self::compute_hash(&self, &content_serialized, &public_key, chain_id);
104        let creator_address = Address::from_public_key(&public_key);
105        Ok(SecureShare {
106            signature: self.sign(keypair, &hash, chain_id)?,
107            content_creator_pub_key: public_key,
108            content_creator_address: creator_address,
109            content: self,
110            serialized_data: content_serialized,
111            id: ID::new(hash),
112        })
113    }
114
115    /// Compute hash
116    fn compute_hash(
117        &self,
118        content_serialized: &[u8],
119        content_creator_pub_key: &PublicKey,
120        _chain_id: u64,
121    ) -> Hash {
122        let mut hash_data = Vec::new();
123        hash_data.extend(content_creator_pub_key.to_bytes());
124        hash_data.extend(content_serialized);
125        Hash::compute_from(&hash_data)
126    }
127
128    /// Compute hash used for signature.
129    ///
130    /// The default returns `*content_hash`, which is correct for components whose
131    /// `compute_hash` already folds in the chain id (e.g. `Operation`).
132    /// `Endorsement` and `BlockHeader` override it to fold `chain_id` into the
133    /// signed hash, so that the same message signed on two chains cannot be
134    /// replayed as a denunciation on either (F90 / PDF #11).
135    fn compute_signed_hash(
136        &self,
137        _public_key: &PublicKey,
138        content_hash: &Hash,
139        _chain_id: u64,
140    ) -> Hash {
141        *content_hash
142    }
143
144    /// Serialize the secured structure
145    fn serialize(
146        signature: &Signature,
147        creator_public_key: &PublicKey,
148        serialized_content: &[u8],
149        buffer: &mut Vec<u8>,
150    ) -> Result<(), SerializeError> {
151        buffer.extend(signature.to_bytes());
152        buffer.extend(creator_public_key.to_bytes());
153        buffer.extend(serialized_content);
154        Ok(())
155    }
156
157    /// Deserialize the secured structure
158    fn deserialize<
159        'a,
160        E: ParseError<&'a [u8]> + ContextError<&'a [u8]>,
161        Deser: Deserializer<Self>,
162        ID: Id,
163    >(
164        content_serializer: Option<&dyn Serializer<Self>>,
165        signature_deserializer: &SignatureDeserializer,
166        creator_public_key_deserializer: &PublicKeyDeserializer,
167        content_deserializer: &Deser,
168        buffer: &'a [u8],
169        chain_id: u64,
170    ) -> IResult<&'a [u8], SecureShare<Self, ID>, E> {
171        let (serialized_data, (signature, creator_public_key)) = context(
172            "Failed SecureShare deserialization",
173            tuple((
174                context("Failed signature deserialization", |input| {
175                    signature_deserializer.deserialize(input)
176                }),
177                context("Failed public_key deserialization", |input| {
178                    creator_public_key_deserializer.deserialize(input)
179                }),
180            )),
181        )(buffer)?;
182        let (rest, content) = content_deserializer.deserialize(serialized_data)?;
183        let content_serialized = if let Some(content_serializer) = content_serializer {
184            let mut content_buffer = Vec::new();
185            content_serializer
186                .serialize(&content, &mut content_buffer)
187                .map_err(|_| {
188                    nom::Err::Error(ParseError::from_error_kind(
189                        rest,
190                        nom::error::ErrorKind::Fail,
191                    ))
192                })?;
193            content_buffer
194        } else {
195            // Avoid getting the rest of the data in the serialized data
196            serialized_data[..serialized_data.len() - rest.len()].to_vec()
197        };
198        let creator_address = Address::from_public_key(&creator_public_key);
199        let hash = Self::compute_hash(&content, &content_serialized, &creator_public_key, chain_id);
200
201        Ok((
202            rest,
203            SecureShare {
204                content,
205                signature,
206                content_creator_pub_key: creator_public_key,
207                content_creator_address: creator_address,
208                serialized_data: content_serialized.to_vec(),
209                id: ID::new(hash),
210            },
211        ))
212    }
213}
214
215impl<T, ID> Display for SecureShare<T, ID>
216where
217    T: Display + SecureShareContent,
218    ID: Id,
219{
220    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
221        writeln!(f, "Signature: {}", self.signature)?;
222        writeln!(f, "Creator pubkey: {}", self.content_creator_pub_key)?;
223        writeln!(f, "Creator address: {}", self.content_creator_address)?;
224        writeln!(f, "Id: {}", self.id.get_hash())?;
225        writeln!(f, "{}", self.content)?;
226        Ok(())
227    }
228}
229
230impl<T, ID> SecureShare<T, ID>
231where
232    T: Display + SecureShareContent,
233    ID: Id,
234{
235    /// check if self has been signed by public key on chain `chain_id`; see
236    /// [`SecureShareContent::compute_signed_hash`].
237    pub fn verify_signature(&self, chain_id: u64) -> Result<(), ModelsError> {
238        self.content.verify_signature(
239            &self.content_creator_pub_key,
240            self.id.get_hash(),
241            &self.signature,
242            chain_id,
243        )
244    }
245
246    /// Compute the signed hash for chain `chain_id`; see
247    /// [`SecureShareContent::compute_signed_hash`].
248    pub fn compute_signed_hash(&self, chain_id: u64) -> Hash {
249        self.content.compute_signed_hash(
250            &self.content_creator_pub_key,
251            self.id.get_hash(),
252            chain_id,
253        )
254    }
255
256    /// get full serialized size
257    pub fn serialized_size(&self) -> usize {
258        self.serialized_data
259            .len()
260            .saturating_add(self.signature.get_ser_len())
261            .saturating_add(self.content_creator_pub_key.get_ser_len())
262    }
263}
264
265// NOTE FOR EXPLICATION: No content serializer because serialized data is already here.
266/// Serializer for `SecureShare` structure
267#[derive(Default, Clone)]
268pub struct SecureShareSerializer;
269
270impl SecureShareSerializer {
271    /// Creates a new `SecureShareSerializer`
272    pub const fn new() -> Self {
273        Self
274    }
275
276    /// This method is used to serialize a `SecureShare` structure and use a custom serializer instead of
277    /// using the serialized form of the content stored in `serialized_data`.
278    /// This is useful when the content need to be serialized in a lighter form in specific cases.
279    ///
280    /// # Arguments:
281    /// * `content_serializer`: Custom serializer to be used instead of the data in `serialized_data`
282    /// * `value`: SecureShare structure to be serialized
283    /// * `buffer`: buffer of serialized data to be extend
284    pub fn serialize_with<Ser, T, ID>(
285        &self,
286        content_serializer: &Ser,
287        value: &SecureShare<T, ID>,
288        buffer: &mut Vec<u8>,
289    ) -> Result<(), SerializeError>
290    where
291        Ser: Serializer<T>,
292        T: Display + SecureShareContent,
293        ID: Id,
294    {
295        let mut content_buffer = Vec::new();
296        content_serializer.serialize(&value.content, &mut content_buffer)?;
297        T::serialize(
298            &value.signature,
299            &value.content_creator_pub_key,
300            &content_buffer,
301            buffer,
302        )
303    }
304}
305
306impl<T, ID> Serializer<SecureShare<T, ID>> for SecureShareSerializer
307where
308    T: Display + SecureShareContent,
309    ID: Id,
310{
311    fn serialize(
312        &self,
313        value: &SecureShare<T, ID>,
314        buffer: &mut Vec<u8>,
315    ) -> Result<(), SerializeError> {
316        T::serialize(
317            &value.signature,
318            &value.content_creator_pub_key,
319            &value.serialized_data,
320            buffer,
321        )
322    }
323}
324
325/// Deserializer for SecureShare structure
326pub struct SecureShareDeserializer<T, Deser>
327where
328    T: Display + SecureShareContent,
329    Deser: Deserializer<T>,
330{
331    signature_deserializer: SignatureDeserializer,
332    public_key_deserializer: PublicKeyDeserializer,
333    content_deserializer: Deser,
334    chain_id: u64,
335    marker_t: std::marker::PhantomData<T>,
336}
337
338impl<T, Deser> SecureShareDeserializer<T, Deser>
339where
340    T: Display + SecureShareContent,
341    Deser: Deserializer<T>,
342{
343    /// Creates a new `SecureShareDeserializer`
344    ///
345    /// # Arguments
346    /// * `content_deserializer` - Deserializer for the content
347    pub const fn new(content_deserializer: Deser, chain_id: u64) -> Self {
348        Self {
349            signature_deserializer: SignatureDeserializer::new(),
350            public_key_deserializer: PublicKeyDeserializer::new(),
351            content_deserializer,
352            chain_id,
353            marker_t: std::marker::PhantomData,
354        }
355    }
356
357    /// This method is used to deserialize data that has been serialized in a lightweight form.
358    /// The buffer doesn't have the whole content serialized and so
359    /// this serialized data isn't coherent with the full structure and can't be used to calculate id and signature.
360    /// We pass a serializer to serialize the full structure and retrieve a coherent `serialized_data`
361    /// that can be use for the id and signature computing.
362    ///
363    /// # Arguments:
364    /// * `content_serializer`: Serializer use to compute the `serialized_data` from the content
365    /// * `buffer`: buffer of serialized data to be deserialized
366    ///
367    /// # Returns:
368    /// A rest (data left over from deserialization), an instance of `T`, and the data enabling signature verification
369    pub fn deserialize_with<
370        'a,
371        E: ParseError<&'a [u8]> + ContextError<&'a [u8]>,
372        ID: Id,
373        Ser: Serializer<T>,
374    >(
375        &self,
376        content_serializer: &Ser,
377        buffer: &'a [u8],
378    ) -> IResult<&'a [u8], SecureShare<T, ID>, E> {
379        T::deserialize(
380            Some(content_serializer),
381            &self.signature_deserializer,
382            &self.public_key_deserializer,
383            &self.content_deserializer,
384            buffer,
385            self.chain_id,
386        )
387    }
388}
389
390impl<T, ID, Deser> Deserializer<SecureShare<T, ID>> for SecureShareDeserializer<T, Deser>
391where
392    T: Display + SecureShareContent,
393    ID: Id,
394    Deser: Deserializer<T>,
395{
396    /// ```
397    /// # use massa_models::{endorsement::{Endorsement, EndorsementSerializer, EndorsementDeserializer}, slot::Slot, secure_share::{SecureShare, SecureShareSerializer, SecureShareDeserializer, SecureShareContent}};
398    /// use massa_models::block_id::BlockId;
399    /// # use massa_serialization::{Deserializer, Serializer, DeserializeError, U16VarIntSerializer, U16VarIntDeserializer};
400    /// # use massa_signature::KeyPair;
401    /// # use std::ops::Bound::Included;
402    /// # use massa_hash::Hash;
403    /// use massa_models::config::CHAINID;
404    ///
405    /// let content = Endorsement {
406    ///    slot: Slot::new(10, 1),
407    ///    index: 0,
408    ///    endorsed_block: BlockId::generate_from_hash(Hash::compute_from("blk".as_bytes())),
409    /// };
410    /// let keypair = KeyPair::generate(0).unwrap();
411    /// let secured: SecureShare<Endorsement, BlockId> = Endorsement::new_verifiable(
412    ///    content,
413    ///    EndorsementSerializer::new(),
414    ///    &keypair,
415    ///    *CHAINID
416    /// ).unwrap();
417    /// let mut serialized_data = Vec::new();
418    /// let serialized = SecureShareSerializer::new().serialize(&secured, &mut serialized_data).unwrap();
419    /// let deserializer = SecureShareDeserializer::new(EndorsementDeserializer::new(32, 1), 77);
420    /// let (rest, deserialized): (&[u8], SecureShare<Endorsement, BlockId>) = deserializer.deserialize::<DeserializeError>(&serialized_data).unwrap();
421    /// assert!(rest.is_empty());
422    /// assert_eq!(secured.id, deserialized.id);
423    /// ```
424    fn deserialize<'a, E: ParseError<&'a [u8]> + ContextError<&'a [u8]>>(
425        &self,
426        buffer: &'a [u8],
427    ) -> IResult<&'a [u8], SecureShare<T, ID>, E> {
428        T::deserialize(
429            None,
430            &self.signature_deserializer,
431            &self.public_key_deserializer,
432            &self.content_deserializer,
433            buffer,
434            self.chain_id,
435        )
436    }
437}