Skip to main content

libkeri/cesr/signing/
salter.rs

1use crate::cesr::signing::signer::Signer;
2use crate::cesr::{mtr_dex, raw_size, BaseMatter, Parsable, Tiers};
3use crate::errors::MatterError;
4use crate::Matter;
5use sodiumoxide::crypto::pwhash::argon2id13 as pwhash;
6use sodiumoxide::crypto::pwhash::argon2id13::Salt;
7use sodiumoxide::randombytes;
8use std::any::Any;
9
10/// Salter is Matter subclass to maintain random salt for secrets (private keys)
11/// Its .raw is random salt, .code as cipher suite for salt
12///
13/// To initialize with deterministic salt pass in 16 bytes for raw:
14///     salter = Salter::new(Some(b"0123456789abcdef"), None, None).unwrap();
15///
16/// To create a deterministic secret, seed, or private key from salt
17/// call .signer:
18///     signer = salter.signer(Some(mtr_dex::ED25519_SEED), Some(true), "", None, false).unwrap();
19#[derive(Debug, Clone)]
20pub struct Salter {
21    base: BaseMatter,
22    tier: Tiers,
23}
24
25impl Salter {
26    /// Initialize salter's raw and code
27    pub fn new(
28        raw: Option<&[u8]>,
29        code: Option<&str>,
30        tier: Option<Tiers>,
31    ) -> Result<Self, MatterError> {
32        let code = code.unwrap_or(mtr_dex::SALT_128);
33
34        let raw = match raw {
35            Some(r) => r,
36            None => {
37                if code == mtr_dex::SALT_128 {
38                    // Initialize sodium library if not already done
39                    if sodiumoxide::init().is_err() {
40                        return Err(MatterError::CryptoError(
41                            "Sodium initialization failed".to_string(),
42                        ));
43                    }
44
45                    // Generate random salt using sodiumoxide
46                    let salt_bytes = randombytes::randombytes(pwhash::SALTBYTES);
47                    &salt_bytes.clone()[..]
48                } else {
49                    return Err(MatterError::ValidationError(format!(
50                        "Unsupported salter code = {}",
51                        code
52                    )));
53                }
54            }
55        };
56
57        if code != mtr_dex::SALT_128 {
58            return Err(MatterError::ValidationError(format!(
59                "Unsupported salter code = {}",
60                code
61            )));
62        }
63
64        // Use a default tier if none provided
65        let tier = tier.unwrap_or(Tiers::LOW);
66
67        let base = BaseMatter::new(Some(raw), Some(code), None, None)?;
68        Ok(Self { base, tier })
69    }
70
71    /// Returns raw binary seed (secret) derived from path and .raw
72    /// and stretched to size given by code using argon2id stretching algorithm.
73    pub fn stretch(
74        &self,
75        size: usize,
76        path: &str,
77        tier: Option<&Tiers>,
78        temp: bool,
79    ) -> Result<Vec<u8>, MatterError> {
80        let tier = tier.unwrap_or(&self.tier);
81
82        let (opslimit, memlimit) = if temp {
83            (pwhash::OpsLimit(1), pwhash::MemLimit(8192))
84        } else {
85            match tier {
86                Tiers::LOW => (pwhash::OPSLIMIT_INTERACTIVE, pwhash::MEMLIMIT_INTERACTIVE),
87                Tiers::MED => (pwhash::OPSLIMIT_MODERATE, pwhash::MEMLIMIT_MODERATE),
88                Tiers::HIGH => (pwhash::OPSLIMIT_SENSITIVE, pwhash::MEMLIMIT_SENSITIVE),
89            }
90        };
91
92        // Initialize sodium library if not already done
93        if sodiumoxide::init().is_err() {
94            return Err(MatterError::CryptoError(
95                "Sodium initialization failed".to_string(),
96            ));
97        }
98
99        // Convert path to bytes
100        let path_bytes = path.as_bytes();
101
102        // Create salt from raw
103        let salt = match Salt::from_slice(self.raw()) {
104            Some(s) => s,
105            None => {
106                return Err(MatterError::ValidationError(
107                    "Invalid salt size".to_string(),
108                ))
109            }
110        };
111
112        // Use argon2id13 algorithm for stretching
113        let mut kb = vec![0u8; size];
114        let kb = kb.as_mut_slice();
115        let seed = pwhash::derive_key(kb, path_bytes, &salt, opslimit, memlimit)
116            .map_err(|_| MatterError::Conversion("Key derivation failed".to_string()))?;
117
118        Ok(seed.to_vec())
119    }
120
121    /// Returns Signer instance whose .raw secret is derived from path and
122    /// salter's .raw and stretched to size given by code. The signers public key
123    /// for its .verfer is derived from code and transferable.
124    pub fn signer(
125        &self,
126        code: Option<&str>,
127        transferable: Option<bool>,
128        path: &str,
129        tier: Option<&Tiers>,
130        temp: bool,
131    ) -> Result<Signer, MatterError> {
132        let code = code.unwrap_or(mtr_dex::ED25519_SEED);
133        let transferable = transferable.unwrap_or(true);
134
135        // Calculate raw size based on code
136        let size = raw_size(code)?;
137
138        let seed = self.stretch(size, path, tier, temp)?;
139
140        Signer::new(Some(&seed), Some(code), Some(transferable))
141    }
142
143    /// Returns vector of count number of Signer instances with unique derivation
144    /// path made from path prefix and suffix of start plus offset for each count
145    /// value from 0 to count - 1.
146    pub fn signers(
147        &self,
148        count: usize,
149        start: usize,
150        path: &str,
151        code: Option<&str>,
152        transferable: Option<bool>,
153        tier: Option<&Tiers>,
154        temp: bool,
155    ) -> Result<Vec<Signer>, MatterError> {
156        let mut signers = Vec::with_capacity(count);
157
158        for i in 0..count {
159            let path_with_suffix = format!("{}{:x}", path, i + start);
160            let signer = self.signer(code, transferable, &path_with_suffix, tier, temp)?;
161            signers.push(signer);
162        }
163
164        Ok(signers)
165    }
166
167    pub fn tier(&self) -> &Tiers {
168        &self.tier
169    }
170
171    pub fn from_qb64_and_tier(data: &str, tier: Option<Tiers>) -> Result<Self, MatterError> {
172        let tier = tier.unwrap_or(Tiers::LOW);
173        let base = BaseMatter::from_qb64(data)?;
174
175        if base.code() != mtr_dex::SALT_128 {
176            return Err(MatterError::ValidationError(format!(
177                "Unsupported salter code = {}",
178                base.code()
179            )));
180        }
181
182        Ok(Self { base, tier })
183    }
184}
185
186impl Parsable for Salter {
187    fn from_qb64b(data: &mut Vec<u8>, strip: Option<bool>) -> Result<Self, MatterError> {
188        let base = BaseMatter::from_qb64b(data, strip)?;
189
190        if base.code() != mtr_dex::SALT_128 {
191            return Err(MatterError::ValidationError(format!(
192                "Unsupported salter code = {}",
193                base.code()
194            )));
195        }
196
197        Ok(Self {
198            base,
199            tier: Tiers::LOW,
200        })
201    }
202
203    fn from_qb2(data: &mut Vec<u8>, strip: Option<bool>) -> Result<Self, MatterError> {
204        let base = BaseMatter::from_qb2(data, strip)?;
205
206        if base.code() != mtr_dex::SALT_128 {
207            return Err(MatterError::ValidationError(format!(
208                "Unsupported salter code = {}",
209                base.code()
210            )));
211        }
212
213        Ok(Self {
214            base,
215            tier: Tiers::LOW,
216        })
217    }
218}
219
220impl Matter for Salter {
221    fn code(&self) -> &str {
222        self.base.code()
223    }
224
225    fn raw(&self) -> &[u8] {
226        self.base.raw()
227    }
228
229    fn qb64(&self) -> String {
230        self.base.qb64()
231    }
232
233    fn qb64b(&self) -> Vec<u8> {
234        self.base.qb64b()
235    }
236
237    fn qb2(&self) -> Vec<u8> {
238        self.base.qb2()
239    }
240
241    fn soft(&self) -> &str {
242        self.base.soft()
243    }
244
245    fn full_size(&self) -> usize {
246        self.base.full_size()
247    }
248
249    fn size(&self) -> usize {
250        self.base.size()
251    }
252
253    fn is_transferable(&self) -> bool {
254        self.base.is_transferable()
255    }
256
257    fn is_digestive(&self) -> bool {
258        self.base.is_digestive()
259    }
260
261    fn is_prefixive(&self) -> bool {
262        self.base.is_prefixive()
263    }
264
265    fn is_special(&self) -> bool {
266        self.base.is_special()
267    }
268
269    fn as_any(&self) -> &dyn Any {
270        self
271    }
272}
273
274#[cfg(test)]
275mod tests {
276    use super::*;
277
278    #[test]
279    fn test_salter_creation() {
280        // Create salter with random salt
281        let salter = Salter::new(None, None, None).unwrap();
282        assert_eq!(salter.code(), mtr_dex::SALT_128);
283        assert_eq!(salter.raw().len(), 16); // Salt_128 should be 16 bytes
284
285        // Create salter with specific salt
286        let raw = b"0123456789abcdef";
287        let salter = Salter::new(Some(raw), None, None).unwrap();
288        assert_eq!(salter.code(), mtr_dex::SALT_128);
289        assert_eq!(salter.raw(), raw);
290    }
291
292    #[test]
293    fn test_stretching() {
294        let raw = b"0123456789abcdef";
295        let salter = Salter::new(Some(raw), None, None).unwrap();
296
297        // Test with temp=true for faster tests
298        let stretched = salter.stretch(32, "test-path", None, true).unwrap();
299        assert_eq!(stretched.len(), 32);
300
301        // Same inputs should produce same output
302        let stretched2 = salter.stretch(32, "test-path", None, true).unwrap();
303        assert_eq!(stretched, stretched2);
304
305        // Different path should produce different output
306        let stretched3 = salter.stretch(32, "different-path", None, true).unwrap();
307        assert_ne!(stretched, stretched3);
308    }
309
310    #[test]
311    fn test_signer_creation() {
312        let raw = b"0123456789abcdef";
313        let salter = Salter::new(Some(raw), None, None).unwrap();
314
315        // Create a signer with temp=true for faster tests
316        let signer = salter.signer(None, None, "test-path", None, true).unwrap();
317
318        // Should have created an Ed25519 signer by default
319        assert_eq!(signer.code(), mtr_dex::ED25519_SEED);
320        assert!(signer.is_transferable());
321
322        // Creating another signer with same parameters should give same key
323        let signer2 = salter.signer(None, None, "test-path", None, true).unwrap();
324        assert_eq!(signer.raw(), signer2.raw());
325    }
326
327    #[test]
328    fn test_signers_creation() {
329        let raw = b"0123456789abcdef";
330        let salter = Salter::new(Some(raw), None, None).unwrap();
331
332        // Create multiple signers
333        let signers = salter
334            .signers(3, 0, "test-path", None, None, None, true)
335            .unwrap();
336
337        // Should have 3 signers
338        assert_eq!(signers.len(), 3);
339
340        // Each signer should be different
341        assert_ne!(signers[0].raw(), signers[1].raw());
342        assert_ne!(signers[1].raw(), signers[2].raw());
343        assert_ne!(signers[0].raw(), signers[2].raw());
344    }
345
346    #[test]
347    fn test_salter_default() {
348        // Test default constructor
349        let salter = Salter::new(None, None, None).unwrap();
350        assert_eq!(salter.code(), mtr_dex::SALT_128);
351        assert_eq!(salter.raw().len(), 16); // Same as Matter::raw_size(salter.code())
352    }
353
354    #[test]
355    fn test_salter_with_raw() {
356        // Test constructor with raw bytes
357        let raw = b"0123456789abcdef";
358        let salter = Salter::new(Some(raw), None, None).unwrap();
359        assert_eq!(salter.raw(), raw);
360        assert_eq!(salter.qb64(), "0AAwMTIzNDU2Nzg5YWJjZGVm");
361    }
362
363    #[test]
364    fn test_salter_from_qb64() {
365        // Test constructor from qb64
366        let qb64 = "0AAwMTIzNDU2Nzg5YWJjZGVm";
367        let salter = Salter::from_qb64b(&mut qb64.as_bytes().to_vec(), None).unwrap();
368        assert_eq!(salter.raw(), b"0123456789abcdef");
369        assert_eq!(salter.qb64(), qb64);
370    }
371
372    #[test]
373    fn test_salter_empty_qb64() {
374        // Test that empty qb64 fails
375        let result = Salter::from_qb64b(&mut "".as_bytes().to_vec(), None);
376        assert!(result.is_err());
377    }
378
379    #[test]
380    fn test_signer_with_temp() {
381        // Test signer creation with temp=true
382        let raw = b"0123456789abcdef";
383        let salter = Salter::new(Some(raw), None, None).unwrap();
384        assert_eq!(salter.code(), mtr_dex::SALT_128);
385        assert_eq!(salter.qb64(), "0AAwMTIzNDU2Nzg5YWJjZGVm");
386
387        let signer = salter.signer(None, None, "01", None, true).unwrap();
388
389        assert_eq!(signer.code(), mtr_dex::ED25519_SEED);
390        assert_eq!(signer.raw().len(), 32); // Expected size for Ed25519_Seed
391        assert_eq!(signer.verfer().code(), mtr_dex::ED25519);
392        assert_eq!(signer.verfer().raw().len(), 32); // Expected size for Ed25519
393        assert_eq!(
394            signer.qb64(),
395            "AMPsqBZxWdtYpBhrWnKYitwFa77s902Q-nX3sPTzqs0R"
396        );
397        assert_eq!(
398            signer.verfer().qb64(),
399            "DFYFwZJOMNy3FknECL8tUaQZRBUyQ9xCv6F8ckG-UCrC"
400        );
401    }
402
403    #[test]
404    fn test_signer_without_temp() {
405        // Test signer creation with temp=false (default)
406        let raw = b"0123456789abcdef";
407        let salter = Salter::new(Some(raw), None, None).unwrap();
408
409        let signer = salter.signer(None, None, "01", None, false).unwrap();
410
411        assert_eq!(signer.code(), mtr_dex::ED25519_SEED);
412        assert_eq!(signer.raw().len(), 32); // Expected size for Ed25519_Seed
413        assert_eq!(signer.verfer().code(), mtr_dex::ED25519);
414        assert_eq!(signer.verfer().raw().len(), 32); // Expected size for Ed25519
415        assert_eq!(
416            signer.qb64(),
417            "AEkqQiNTexWB9fTLpgJp_lXW63tFlT-Y0_mgQww4o-dC"
418        );
419        assert_eq!(
420            signer.verfer().qb64(),
421            "DPJGyH9H1M_SUSf18RzX8OqdyhxEyZJpKm5Em0PnpsWd"
422        );
423    }
424
425    #[test]
426    fn test_stretch() {
427        // Test stretching key material with different parameters
428        let raw = b"0123456789abcdef";
429        let salter = Salter::new(Some(raw), None, None).unwrap();
430
431        // Test with temp=true
432        let stretched_temp = salter.stretch(32, "", Some(&Tiers::LOW), true).unwrap();
433        assert_eq!(
434            stretched_temp,
435            [
436                212, 64, 235, 166, 120, 134, 223, 147, 214, 67, 220, 184, 166, 155, 2, 175, 104,
437                193, 109, 40, 76, 214, 246, 134, 89, 85, 62, 36, 91, 249, 239, 192
438            ]
439        );
440
441        // Test with Tiers::Low
442        let stretched_low = salter.stretch(32, "", Some(&Tiers::LOW), false).unwrap();
443        assert_eq!(
444            stretched_low,
445            [
446                248, 101, 128, 186, 88, 8, 185, 186, 198, 30, 132, 13, 29, 172, 167, 92, 130, 87,
447                99, 64, 96, 19, 253, 2, 52, 116, 140, 116, 211, 1, 25, 233
448            ]
449        );
450
451        // Test with Tiers::Med
452        let stretched_med = salter.stretch(32, "", Some(&Tiers::MED), false).unwrap();
453        assert_eq!(
454            stretched_med,
455            [
456                44, 243, 140, 187, 233, 41, 10, 83, 81, 236, 173, 140, 57, 63, 175, 184, 176, 179,
457                205, 66, 218, 216, 182, 247, 13, 246, 68, 125, 90, 185, 89, 22
458            ]
459        );
460
461        // Test with Tiers::High
462        let stretched_high = salter.stretch(32, "", Some(&Tiers::HIGH), false).unwrap();
463        assert_eq!(
464            stretched_high,
465            [
466                40, 205, 196, 184, 53, 205, 232, 58, 252, 0, 139, 253, 166, 9, 106, 46, 121, 152,
467                11, 4, 28, 227, 104, 66, 99, 33, 73, 228, 57, 75, 22, 45
468            ]
469        );
470    }
471
472    #[test]
473    fn test_multiple_signers() {
474        // Test creating multiple signers
475        let raw = b"0123456789abcdef";
476        let salter = Salter::new(Some(raw), None, None).unwrap();
477
478        // Create 3 signers starting at index 0
479        let signers = salter
480            .signers(3, 0, "test-path", None, None, None, false)
481            .unwrap();
482
483        assert_eq!(signers.len(), 3);
484        for signer in &signers {
485            assert_eq!(signer.code(), mtr_dex::ED25519_SEED);
486            assert_eq!(signer.verfer().code(), mtr_dex::ED25519);
487        }
488
489        // Verify signers are different from each other
490        assert_ne!(signers[0].qb64(), signers[1].qb64());
491        assert_ne!(signers[0].qb64(), signers[2].qb64());
492        assert_ne!(signers[1].qb64(), signers[2].qb64());
493    }
494
495    #[test]
496    fn test_salter_parsable() {
497        // Test Parsable implementation for Salter
498        let raw = b"0123456789abcdef";
499        let salter = Salter::new(Some(raw), None, None).unwrap();
500
501        // Convert to qb64b and parse back
502        let mut qb64b = salter.qb64b();
503        let parsed_salter = Salter::from_qb64b(&mut qb64b, Some(true)).unwrap();
504        assert_eq!(parsed_salter.raw(), raw);
505
506        // Convert to qb2 and parse back
507        // TODO: Come back to this test for from_qb2
508        // let mut qb2 = salter.qb2();
509        // let parsed_salter = Salter::from_qb2(&mut qb2, Some(true)).unwrap();
510        assert_eq!(parsed_salter.raw(), raw);
511    }
512}