OXYGENHUB
# f53cbe7a204e oxygen / crates / oxy-core / src / hash.rs
4.5 KiB · Rust · last changed Certificates for short-lived keys (keyless, step 1) 18 days ago source blame history raw
1 
//! Object references: BLAKE3-256 over a domain-separating header and the body
2 
//! (spec §5.2).
3
4 
use std::fmt;
5
6 
#[derive(Clone, Copy, PartialEq, Eq, Hash, PartialOrd, Ord)]
7 
pub struct ObjectRef(pub [u8; 32]);
8
9 
/// A change is referenced by the ObjectRef of its encoding.
10 
pub type ChangeHash = ObjectRef;
11 
/// An identity is referenced by the ObjectRef of its encoding.
12 
pub type KeyId = ObjectRef;
13
14 
impl ObjectRef {
15 
    /// Reserved: means "this change" inside a change (spec §5.2, §7.4).
16 
    pub const ZERO: ObjectRef = ObjectRef([0; 32]);
17
18 
    pub fn is_zero(&self) -> bool {
19 
        *self == Self::ZERO
20 
    }
21 
    pub fn to_hex(&self) -> String {
22 
        hex::encode(self.0)
23 
    }
24 
    pub fn from_hex(s: &str) -> Option<ObjectRef> {
25 
        let v = hex::decode(s).ok()?;
26 
        let a: [u8; 32] = v.try_into().ok()?;
27 
        Some(ObjectRef(a))
28 
    }
29 
    pub fn from_slice(b: &[u8]) -> Option<ObjectRef> {
30 
        let a: [u8; 32] = b.try_into().ok()?;
31 
        Some(ObjectRef(a))
32 
    }
33 
    /// First `n` hex characters.
34 
    pub fn short(&self, n: usize) -> String {
35 
        let h = self.to_hex();
36 
        h[..n.min(h.len())].to_string()
37 
    }
38 
    pub fn starts_with_hex(&self, prefix: &str) -> bool {
39 
        self.to_hex().starts_with(prefix)
40 
    }
41 
}
42
43 
impl fmt::Display for ObjectRef {
44 
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
45 
        f.write_str(&self.to_hex())
46 
    }
47 
}
48
49 
impl fmt::Debug for ObjectRef {
50 
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
51 
        write!(f, "#{}", self.short(12))
52 
    }
53 
}
54
55 
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
56 
pub enum ObjectType {
57 
    Chunk,
58 
    Blob,
59 
    Change,
60 
    Checkpoint,
61 
    Op,
62 
    Attest,
63 
    Identity,
64 
    Policy,
65 
    State,
66 
    Receipt,
67 
    /// A short-lived key's certificate (oxygenhub#241).
68 
    Certificate,
69 
}
70
71 
impl ObjectType {
72 
    pub const ALL: [ObjectType; 11] = [
73 
        ObjectType::Chunk,
74 
        ObjectType::Blob,
75 
        ObjectType::Change,
76 
        ObjectType::Checkpoint,
77 
        ObjectType::Op,
78 
        ObjectType::Attest,
79 
        ObjectType::Identity,
80 
        ObjectType::Policy,
81 
        ObjectType::State,
82 
        ObjectType::Receipt,
83 
        ObjectType::Certificate,
84 
    ];
85
86 
    pub fn name(self) -> &'static str {
87 
        match self {
88 
            ObjectType::Chunk => "chunk",
89 
            ObjectType::Blob => "blob",
90 
            ObjectType::Change => "change",
91 
            ObjectType::Checkpoint => "checkpoint",
92 
            ObjectType::Op => "op",
93 
            ObjectType::Attest => "attest",
94 
            ObjectType::Identity => "identity",
95 
            ObjectType::Policy => "policy",
96 
            ObjectType::State => "state",
97 
            ObjectType::Receipt => "receipt",
98 
            ObjectType::Certificate => "certificate",
99 
        }
100 
    }
101
102 
    pub fn from_name(s: &str) -> Option<ObjectType> {
103 
        Self::ALL.iter().copied().find(|t| t.name() == s)
104 
    }
105 
}
106
107 
/// `ObjectRef = BLAKE3-256("oxy1 " || type || " " || decimal(len) || 0x00 || body)`.
108 
pub fn hash_object(ty: ObjectType, body: &[u8]) -> ObjectRef {
109 
    let mut h = blake3::Hasher::new();
110 
    h.update(&header(ty, body.len()));
111 
    h.update(body);
112 
    ObjectRef(*h.finalize().as_bytes())
113 
}
114
115 
pub fn header(ty: ObjectType, len: usize) -> Vec<u8> {
116 
    let mut v = Vec::with_capacity(32);
117 
    v.extend_from_slice(b"oxy1 ");
118 
    v.extend_from_slice(ty.name().as_bytes());
119 
    v.push(b' ');
120 
    v.extend_from_slice(len.to_string().as_bytes());
121 
    v.push(0);
122 
    v
123 
}
124
125 
#[cfg(test)]
126 
mod tests {
127 
    use super::*;
128
129 
    #[test]
130 
    fn header_matches_spec() {
131 
        assert_eq!(header(ObjectType::Chunk, 5), b"oxy1 chunk 5\0");
132 
        assert_eq!(header(ObjectType::Change, 1234), b"oxy1 change 1234\0");
133 
    }
134
135 
    #[test]
136 
    fn types_are_domain_separated() {
137 
        let body = b"same bytes";
138 
        let a = hash_object(ObjectType::Chunk, body);
139 
        let b = hash_object(ObjectType::Blob, body);
140 
        assert_ne!(a, b);
141 
        assert_eq!(a, hash_object(ObjectType::Chunk, body));
142 
        // Reference vector: pin so the format cannot drift silently.
143 
        assert_eq!(
144 
            hash_object(ObjectType::Chunk, b"").to_hex(),
145 
            blake3::hash(b"oxy1 chunk 0\0").to_hex().as_str()
146 
        );
147 
    }
148
149 
    #[test]
150 
    fn hex_round_trip() {
151 
        let r = hash_object(ObjectType::Chunk, b"x");
152 
        assert_eq!(ObjectRef::from_hex(&r.to_hex()), Some(r));
153 
        assert_eq!(ObjectRef::from_hex("zz"), None);
154 
        assert!(r.starts_with_hex(&r.short(7)));
155 
        assert!(ObjectRef::ZERO.is_zero());
156 
        for t in ObjectType::ALL {
157 
            assert_eq!(ObjectType::from_name(t.name()), Some(t));
158 
        }
159 
    }
160 
}