mithril_common/crypto_helper/cardano/
codec.rs

1//! Module to provide functions to (de)serialise JSON data structures as used in Shelley,
2//! which have the following format:
3//! ```json
4//! {
5//!      "type": <NAME OF SERIALISED STRUCTURE>,
6//!      "description": <DESCRIPTION OF SERIALISED STRUCTURE>,
7//!      "cborHex": <CBOR HEX REPRESENTATION OF SERIALISED STRUCTURE>
8//!  }
9//! ```
10//!
11//! The trait `SerDeShelleyFileFormat` can be implemented for any structure that implements
12//! `Serialize` and `Deserialize`.
13
14use anyhow::{Context, anyhow};
15use hex::FromHex;
16use kes_summed_ed25519::kes::Sum6Kes;
17use kes_summed_ed25519::traits::KesSk;
18use serde::de::DeserializeOwned;
19use serde::{Deserialize, Serialize};
20use serde_with::{As, Bytes};
21use std::fs;
22use std::io::Write;
23use std::path::Path;
24use thiserror::Error;
25
26use crate::StdError;
27
28/// We need to create this struct because the design of Sum6Kes takes
29/// a reference to a mutable pointer. It is therefore not possible to
30/// implement Ser/Deser using serde.
31// We need this helper structure, because we are currently getting the key
32// from a file, instead of directly consuming a buffer.
33// todo: create the KES key directly from a buffer instead of deserialising from disk
34#[derive(Clone, Serialize, Deserialize)]
35pub struct Sum6KesBytes(#[serde(with = "As::<Bytes>")] pub [u8; 612]);
36
37/// Parse error
38#[derive(Error, Debug)]
39#[error("Codec parse error")]
40pub struct CodecParseError(#[source] StdError);
41
42/// Fields for a shelley formatted file (holds for vkeys, skeys or certs)
43#[derive(Clone, Debug, Default, Serialize, Deserialize)]
44struct ShelleyFileFormat {
45    #[serde(rename = "type")]
46    file_type: String,
47    description: String,
48    #[serde(rename = "cborHex")]
49    cbor_hex: String,
50}
51
52/// Trait that allows any structure that implements Serialize and DeserializeOwned to
53/// be serialized and deserialized following the Shelly json format.
54pub trait SerDeShelleyFileFormat: Serialize + DeserializeOwned {
55    /// The type of Cardano key
56    const TYPE: &'static str;
57
58    /// The description of the Cardano key
59    const DESCRIPTION: &'static str;
60
61    /// Deserialize a type `T: Serialize + DeserializeOwned` from file following Cardano
62    /// Shelley file format.
63    fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, CodecParseError> {
64        let data = fs::read_to_string(path)
65            .with_context(|| "SerDeShelleyFileFormat can not read data from file {}")
66            .map_err(|e| CodecParseError(anyhow!(e)))?;
67        let file: ShelleyFileFormat = serde_json::from_str(&data)
68            .with_context(|| "SerDeShelleyFileFormat can not unserialize json data")
69            .map_err(|e| CodecParseError(anyhow!(e)))?;
70
71        Self::from_cbor_hex(&file.cbor_hex)
72    }
73
74    /// Serialize a type `T: Serialize + DeserializeOwned` to file following Cardano
75    /// Shelley file format.
76    fn to_file<P: AsRef<Path>>(&self, path: P) -> Result<(), CodecParseError> {
77        let cbor_string = self
78            .to_cbor_hex()
79            .with_context(|| "SerDeShelleyFileFormat can not serialize data to cbor")
80            .map_err(|e| CodecParseError(anyhow!(e)))?;
81
82        let file_format = ShelleyFileFormat {
83            file_type: Self::TYPE.to_string(),
84            description: Self::DESCRIPTION.to_string(),
85            cbor_hex: cbor_string,
86        };
87
88        let mut file = fs::File::create(path)
89            .with_context(|| "SerDeShelleyFileFormat can not create file")
90            .map_err(|e| CodecParseError(anyhow!(e)))?;
91        let json_str = serde_json::to_string(&file_format)
92            .with_context(|| "SerDeShelleyFileFormat can not serialize data to json")
93            .map_err(|e| CodecParseError(anyhow!(e)))?;
94
95        write!(file, "{json_str}")
96            .with_context(|| "SerDeShelleyFileFormat can not write data to file")
97            .map_err(|e| CodecParseError(anyhow!(e)))?;
98        Ok(())
99    }
100
101    /// Serialize the structure to a CBOR bytes representation.
102    fn to_cbor_bytes(&self) -> Result<Vec<u8>, CodecParseError> {
103        let mut cursor = std::io::Cursor::new(Vec::new());
104        ciborium::ser::into_writer(&self, &mut cursor)
105            .with_context(|| "SerDeShelleyFileFormat can not serialize data to cbor")
106            .map_err(|e| CodecParseError(anyhow!(e)))?;
107
108        Ok(cursor.into_inner())
109    }
110
111    /// Serialize the structure to a CBOR hex representation.
112    fn to_cbor_hex(&self) -> Result<String, CodecParseError> {
113        Ok(hex::encode(self.to_cbor_bytes()?))
114    }
115
116    /// Deserialize a type `T: Serialize + DeserializeOwned` from CBOR bytes representation.
117    fn from_cbor_bytes(bytes: &[u8]) -> Result<Self, CodecParseError> {
118        let mut cursor = std::io::Cursor::new(&bytes);
119        let a: Self = ciborium::de::from_reader(&mut cursor)
120            .with_context(|| "SerDeShelleyFileFormat can not unserialize cbor data")
121            .map_err(|e| CodecParseError(anyhow!(e)))?;
122
123        Ok(a)
124    }
125
126    /// Deserialize a type `T: Serialize + DeserializeOwned` from CBOR hex representation.
127    fn from_cbor_hex(hex: &str) -> Result<Self, CodecParseError> {
128        let hex_vector = Vec::from_hex(hex)
129            .with_context(|| "SerDeShelleyFileFormat can not unserialize hex data")
130            .map_err(|e| CodecParseError(anyhow!(e)))?;
131
132        Self::from_cbor_bytes(&hex_vector)
133            .with_context(|| "SerDeShelleyFileFormat can not unserialize cbor data")
134            .map_err(|e| CodecParseError(anyhow!(e)))
135    }
136}
137
138impl SerDeShelleyFileFormat for Sum6KesBytes {
139    const TYPE: &'static str = "KesSigningKey_ed25519_kes_2^6";
140    const DESCRIPTION: &'static str = "KES Signing Key";
141
142    /// Deserialize a Cardano key from file. Cardano KES key Shelley format does not
143    /// contain the period (it is always zero). Therefore we need to include it in the
144    /// deserialisation.
145    fn from_file<P: AsRef<Path>>(path: P) -> Result<Self, CodecParseError> {
146        let data = fs::read_to_string(path)
147            .with_context(|| "Sum6KesBytes can not read data from file")
148            .map_err(|e| CodecParseError(anyhow!(e)))?;
149        let file: ShelleyFileFormat = serde_json::from_str(&data)
150            .with_context(|| "Sum6KesBytes can not unserialize json data")
151            .map_err(|e| CodecParseError(anyhow!(e)))?;
152        let mut hex_vector = Vec::from_hex(file.cbor_hex)
153            .with_context(|| "Sum6KesBytes can not unserialize hex data")
154            .map_err(|e| CodecParseError(anyhow!(e)))?;
155
156        // We check whether the serialisation was performed by the haskell library or the rust library
157        if (hex_vector[2] & 4u8) == 0 {
158            // First we need to change the cbor format to notify about the extra 4 bytes:
159            hex_vector[2] |= 4u8;
160            // Then we append the bytes representing the period = 0
161            hex_vector.extend_from_slice(&[0u8; 4]);
162        }
163
164        let mut cursor = std::io::Cursor::new(&hex_vector);
165        let a: Self = ciborium::from_reader(&mut cursor)
166            .with_context(|| "Sum6KesBytes can not unserialize cbor data")
167            .map_err(|e| CodecParseError(anyhow!(e)))?;
168        Ok(a)
169    }
170}
171
172impl<'a> TryFrom<&'a mut Sum6KesBytes> for Sum6Kes<'a> {
173    type Error = CodecParseError;
174
175    fn try_from(value: &'a mut Sum6KesBytes) -> Result<Self, Self::Error> {
176        Self::from_bytes(&mut value.0).map_err(|e| CodecParseError(anyhow!(format!("{e:?}"))))
177    }
178}
179
180#[cfg(test)]
181mod test {
182    use super::*;
183    use crate::test_utils::TempDir;
184
185    #[test]
186    fn compat_with_shelly_format() {
187        let temp_dir = TempDir::create("crypto_helper", "compat_with_shelly_format");
188        let sk_dir = temp_dir.join("dummy.skey");
189        let cbor_string = "590260fe77acdfa56281e4b05198f5136018057a65f425411f0990cac4aca0f2917aa00a3d51e191f6f425d870aca3c6a2a41833621f5729d7bc0e3dfc3ae77d057e5e1253b71def7a54157b9f98973ca3c49edd9f311e5f4b23ac268b56a6ac040c14c6d2217925492e42f00dc89a2a01ff363571df0ca0db5ba37001cee56790cc01cd69c6aa760fca55a65a110305ea3c11da0a27be345a589329a584ebfc499c43c55e8c6db5d9c0b014692533ee78abd7ac1e79f7ec9335c7551d31668369b4d5111db78072f010043e35e5ca7f11acc3c05b26b9c7fe56f02aa41544f00cb7685e87f34c73b617260ade3c7b8d8c4df46693694998f85ad80d2cbab0b575b6ccd65d90574e84368169578bff57f751bc94f7eec5c0d7055ec88891a69545eedbfbd3c5f1b1c1fe09c14099f6b052aa215efdc5cb6cdc84aa810db41dbe8cb7d28f7c4beb75cc53915d3ac75fc9d0bf1c734a46e401e15150c147d013a938b7e07cc4f25a582b914e94783d15896530409b8acbe31ef471de8a1988ac78dfb7510729eff008084885f07df870b65e4f382ca15908e1dcda77384b5c724350de90cec22b1dcbb1cdaed88da08bb4772a82266ec154f5887f89860d0920dba705c45957ef6d93e42f6c9509c966277d368dd0eefa67c8147aa15d40a222f7953a4f34616500b310d00aa1b5b73eb237dc4f76c0c16813d321b2fc5ac97039be25b22509d1201d61f4ccc11cd4ff40fffe39f0e937b4722074d8e073a775d7283b715d46f79ce128e3f1362f35615fa72364d20b6db841193d96e58d9d8e86b516bbd1f05e45b39823a93f6e9f29d9e01acf2c12c072d1c64e0afbbabf6903ef542e".to_string();
190
191        let file_format = ShelleyFileFormat {
192            file_type: Sum6KesBytes::TYPE.to_string(),
193            description: Sum6KesBytes::DESCRIPTION.to_string(),
194            cbor_hex: cbor_string,
195        };
196
197        let mut file =
198            fs::File::create(sk_dir.clone()).expect("Unexpected error with file creation.");
199        let json_str =
200            serde_json::to_string(&file_format).expect("Unexpected error with serialisation.");
201
202        write!(file, "{json_str}").expect("Unexpected error writing to file.");
203
204        let mut kes_sk_bytes =
205            Sum6KesBytes::from_file(&sk_dir).expect("Failure parsing Shelley file format.");
206
207        assert!(Sum6Kes::try_from(&mut kes_sk_bytes).is_ok());
208    }
209}
mithril_common/crypto_helper/cardano/codec.rs

mithril_common/crypto_helper/cardano/
codec.rs
