bc_components/id/
xid.rs

1use dcbor::prelude::*;
2
3#[cfg(feature = "secp256k1")]
4use crate::PrivateKeyBase;
5use crate::{
6    Digest, Error, PublicKeys, Reference, ReferenceProvider, Result,
7    SigningPrivateKey, SigningPublicKey, tags,
8};
9
10/// A XID (eXtensible IDentifier).
11///
12/// A XID is a unique 32-byte identifier for a subject entity (person,
13/// organization, device, or any other entity). XIDs have the following
14/// characteristics:
15///
16/// - They're cryptographically tied to a public key at inception (the
17///   "inception key")
18/// - They remain stable throughout their lifecycle even as their keys and
19///   permissions change
20/// - They can be extended to XID documents containing keys, endpoints,
21///   permissions, and delegation info
22/// - They support key rotation and multiple verification schemes
23/// - They allow for delegation of specific permissions to other entities
24/// - They can include resolution methods to locate and verify the XID document
25///
26/// A XID is created by taking the SHA-256 hash of the CBOR encoding of a public
27/// signing key. This ensures the XID is cryptographically tied to the key.
28///
29/// As defined in [BCR-2024-010](https://github.com/BlockchainCommons/Research/blob/master/papers/bcr-2024-010-xid.md).
30#[derive(Clone, Copy, Eq, PartialEq, Hash)]
31pub struct XID([u8; Self::XID_SIZE]);
32
33impl XID {
34    pub const XID_SIZE: usize = 32;
35
36    /// Create a new XID from data.
37    pub fn from_data(data: [u8; Self::XID_SIZE]) -> Self { Self(data) }
38
39    /// Create a new XID from data.
40    ///
41    /// Returns `None` if the data is not the correct length.
42    pub fn from_data_ref(data: impl AsRef<[u8]>) -> Result<Self> {
43        let data = data.as_ref();
44        if data.len() != Self::XID_SIZE {
45            return Err(Error::invalid_size("XID", Self::XID_SIZE, data.len()));
46        }
47        let mut arr = [0u8; Self::XID_SIZE];
48        arr.copy_from_slice(data.as_ref());
49        Ok(Self::from_data(arr))
50    }
51
52    /// Return the data of the XID.
53    pub fn data(&self) -> &[u8; Self::XID_SIZE] { self.into() }
54
55    /// Get the data of the XID as a byte slice.
56    pub fn as_bytes(&self) -> &[u8] { self.as_ref() }
57
58    /// Create a new XID from the given public key (the "genesis key").
59    ///
60    /// The XID is the SHA-256 digest of the CBOR encoding of the public key.
61    pub fn new(genesis_key: impl AsRef<SigningPublicKey>) -> Self {
62        let key_cbor_data = genesis_key.as_ref().to_cbor_data();
63        let digest = Digest::from_image(key_cbor_data);
64        Self::from_data(*digest.data())
65    }
66
67    /// Validate the XID against the given public key.
68    pub fn validate(&self, key: &SigningPublicKey) -> bool {
69        let key_data = key.to_cbor_data();
70        let digest = Digest::from_image(key_data);
71        *digest.data() == self.0
72    }
73
74    /// Create a new XID from the given hexadecimal string.
75    ///
76    /// # Panics
77    /// Panics if the string is not exactly 64 hexadecimal digits.
78    pub fn from_hex(hex: impl AsRef<str>) -> Self {
79        Self::from_data_ref(hex::decode(hex.as_ref()).unwrap()).unwrap()
80    }
81
82    /// The data as a hexadecimal string.
83    pub fn to_hex(&self) -> String { hex::encode(self.0) }
84
85    /// The first four bytes of the XID as a hexadecimal string.
86    pub fn short_description(&self) -> String { self.ref_hex_short() }
87
88    /// The first four bytes of the XID as upper-case ByteWords.
89    pub fn bytewords_identifier(&self, prefix: bool) -> String {
90        self.ref_bytewords(if prefix { Some("🅧") } else { None })
91    }
92
93    /// The first four bytes of the XID as Bytemoji.
94    pub fn bytemoji_identifier(&self, prefix: bool) -> String {
95        self.ref_bytemoji(if prefix { Some("🅧") } else { None })
96    }
97}
98
99/// A provider trait for obtaining XIDs from various objects.
100pub trait XIDProvider {
101    /// Returns the XID for this object.
102    fn xid(&self) -> XID;
103}
104
105/// Implements XIDProvider for XID to return itself.
106impl XIDProvider for XID {
107    fn xid(&self) -> XID { *self }
108}
109
110/// Implements XIDProvider for SigningPublicKey to generate an XID from the key.
111impl XIDProvider for SigningPublicKey {
112    fn xid(&self) -> XID { XID::new(self) }
113}
114
115/// Implements ReferenceProvider for XID to generate a Reference from the XID.
116impl ReferenceProvider for XID {
117    fn reference(&self) -> Reference { Reference::from_data(*self.data()) }
118}
119
120/// Implements conversion from a XID reference to a byte array reference.
121impl<'a> From<&'a XID> for &'a [u8; XID::XID_SIZE] {
122    fn from(value: &'a XID) -> Self { &value.0 }
123}
124
125/// Implements conversion from a XID reference to a byte slice reference.
126impl<'a> From<&'a XID> for &'a [u8] {
127    fn from(value: &'a XID) -> Self { &value.0 }
128}
129
130/// Implements AsRef<[u8]> to allow XID to be treated as a byte slice.
131impl AsRef<[u8]> for XID {
132    fn as_ref(&self) -> &[u8] { &self.0 }
133}
134
135/// Implements PartialOrd to allow XIDs to be compared and partially ordered.
136impl std::cmp::PartialOrd for XID {
137    fn partial_cmp(&self, other: &Self) -> Option<std::cmp::Ordering> {
138        Some(self.0.cmp(&other.0))
139    }
140}
141
142/// Implements Ord to allow XIDs to be fully ordered.
143impl std::cmp::Ord for XID {
144    fn cmp(&self, other: &Self) -> std::cmp::Ordering { self.0.cmp(&other.0) }
145}
146
147/// Implements Debug formatting for XID showing the full hex representation.
148impl std::fmt::Debug for XID {
149    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
150        write!(f, "XID({})", hex::encode(self.0))
151    }
152}
153
154/// Implements Display formatting for XID showing a shortened hex
155/// representation.
156impl std::fmt::Display for XID {
157    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
158        write!(f, "XID({})", self.short_description())
159    }
160}
161
162/// Implements CBORTagged trait to provide CBOR tag information for XID.
163impl CBORTagged for XID {
164    fn cbor_tags() -> Vec<Tag> { tags_for_values(&[tags::TAG_XID]) }
165}
166
167/// Implements conversion from XID to CBOR for serialization.
168impl From<XID> for CBOR {
169    fn from(value: XID) -> Self { value.tagged_cbor() }
170}
171
172/// Implements conversion from SigningPublicKey reference to XID.
173impl From<&SigningPublicKey> for XID {
174    fn from(key: &SigningPublicKey) -> Self { Self::new(key) }
175}
176
177/// Implements conversion from SigningPrivateKey reference to XID via the public
178/// key.
179impl TryFrom<&SigningPrivateKey> for XID {
180    type Error = Error;
181
182    fn try_from(
183        key: &SigningPrivateKey,
184    ) -> std::result::Result<Self, Self::Error> {
185        Ok(Self::new(&key.public_key()?))
186    }
187}
188
189/// Implements conversion from PublicKeys reference to XID via the signing
190/// public key.
191impl From<&PublicKeys> for XID {
192    fn from(key: &PublicKeys) -> Self { Self::new(key.signing_public_key()) }
193}
194
195/// Implements conversion from PrivateKeyBase reference to XID via the Schnorr
196/// signing key.
197#[cfg(feature = "secp256k1")]
198impl From<&PrivateKeyBase> for XID {
199    fn from(key: &PrivateKeyBase) -> Self {
200        Self::new(key.schnorr_signing_private_key().public_key().unwrap())
201    }
202}
203
204/// Implements CBORTaggedEncodable to provide CBOR encoding functionality for
205/// XID.
206impl CBORTaggedEncodable for XID {
207    fn untagged_cbor(&self) -> CBOR { CBOR::to_byte_string(self.0) }
208}
209
210/// Implements conversion from CBOR to XID for deserialization.
211impl TryFrom<CBOR> for XID {
212    type Error = dcbor::Error;
213
214    fn try_from(cbor: CBOR) -> dcbor::Result<Self> {
215        Self::from_tagged_cbor(cbor)
216    }
217}
218
219/// Implements CBORTaggedDecodable to provide CBOR decoding functionality for
220/// XID.
221impl CBORTaggedDecodable for XID {
222    fn from_untagged_cbor(cbor: CBOR) -> dcbor::Result<Self> {
223        let data = CBOR::try_into_byte_string(cbor)?;
224        Ok(Self::from_data_ref(data)?)
225    }
226}
227
228/// Implements conversion from XID to `Vec<u8>` to allow access to the raw
229/// bytes.
230impl From<XID> for Vec<u8> {
231    fn from(xid: XID) -> Self { xid.0.to_vec() }
232}
233
234#[cfg(test)]
235mod tests {
236    use bc_ur::prelude::*;
237    use hex_literal::hex;
238    #[cfg(feature = "secp256k1")]
239    use indoc::indoc;
240
241    use super::*;
242    #[cfg(feature = "secp256k1")]
243    use crate::{ECPrivateKey, SigningPrivateKey};
244
245    #[test]
246    fn test_xid() {
247        crate::register_tags();
248        let xid = XID::from_data_ref(hex!(
249            "de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037"
250        ))
251        .unwrap();
252        assert_eq!(
253            xid.to_hex(),
254            "de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037"
255        );
256        assert_eq!(xid.short_description(), "de285368");
257        assert_eq!(
258            xid.data(),
259            &hex!(
260                "de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037"
261            )
262        );
263        assert_eq!(
264            format!("{:?}", xid),
265            "XID(de2853684ae55803a08b36dd7f4e566649970601927330299fd333f33fecc037)"
266        );
267        assert_eq!(format!("{}", xid), "XID(de285368)");
268
269        let xid_string = xid.ur_string();
270        assert_eq!(
271            xid_string,
272            "ur:xid/hdcxuedeguisgevwhdaxnbluenutlbglhfiygamsamadmojkdydtneteeowffhwprtemcaatledk"
273        );
274        assert_eq!(XID::from_ur_string(xid_string).unwrap(), xid);
275        assert_eq!(xid.bytewords_identifier(true), "🅧 URGE DICE GURU IRIS");
276        assert_eq!(xid.bytemoji_identifier(true), "🅧 🐻 😻 🍞 💐");
277    }
278
279    #[test]
280    #[cfg(feature = "secp256k1")]
281    fn test_xid_from_key() {
282        crate::register_tags();
283        let private_key = SigningPrivateKey::new_schnorr(
284            ECPrivateKey::from_data(hex!(
285                "322b5c1dd5a17c3481c2297990c85c232ed3c17b52ce9905c6ec5193ad132c36"
286            )),
287        );
288        let public_key = private_key.public_key().unwrap();
289
290        let key_cbor = public_key.to_cbor();
291        #[rustfmt::skip]
292        assert_eq!(key_cbor.diagnostic(), indoc! {"
293            40022(
294                h'e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a'
295            )
296        "}.trim());
297        #[rustfmt::skip]
298        assert_eq!(key_cbor.hex_annotated(), indoc! {"
299            d9 9c56                                 # tag(40022) signing-public-key
300                5820                                # bytes(32)
301                    e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a
302        "}.trim());
303        let key_cbor_data = key_cbor.to_cbor_data();
304        assert_eq!(
305            key_cbor_data,
306            hex!(
307                "d99c565820e8251dc3a17e0f2c07865ed191139ecbcddcbdd070ec1ff65df5148c7ef4005a"
308            )
309        );
310        let digest = Digest::from_image(&key_cbor_data);
311        assert_eq!(
312            digest.data(),
313            &hex!(
314                "d40e0602674df1b732f5e025d04c45f2e74ed1652c5ae1740f6a5502dbbdcd47"
315            )
316        );
317
318        let xid = XID::new(&public_key);
319        assert_eq!(
320            format!("{:?}", xid),
321            "XID(d40e0602674df1b732f5e025d04c45f2e74ed1652c5ae1740f6a5502dbbdcd47)"
322        );
323        xid.validate(&public_key);
324
325        assert_eq!(format!("{}", xid), "XID(d40e0602)");
326        let reference = xid.reference();
327        assert_eq!(format!("{reference}"), "Reference(d40e0602)");
328
329        assert_eq!(reference.bytewords_identifier(None), "TINY BETA ATOM ALSO");
330        assert_eq!(reference.bytemoji_identifier(None), "🧦 🤨 😎 😆");
331
332        assert_eq!(digest.data(), xid.data());
333    }
334}
bc_components/id/xid.rs

bc_components/id/
xid.rs
