Struct XIDDocument 

pub struct XIDDocument { /* private fields */ }

Implementations

impl XIDDocument

pub fn new( key_options: XIDInceptionKeyOptions, mark_options: XIDGenesisMarkOptions, ) -> Self

pub fn from_xid(xid: impl Into<XID>) -> Self

pub fn resolution_methods(&self) -> &HashSet<URI>

pub fn resolution_methods_mut(&mut self) -> &mut HashSet<URI>

pub fn add_resolution_method(&mut self, method: URI)

pub fn remove_resolution_method( &mut self, method: impl AsRef<URI>, ) -> Option<URI>

pub fn keys(&self) -> &HashSet<Key>

pub fn keys_mut(&mut self) -> &mut HashSet<Key>

pub fn add_key(&mut self, key: Key) -> Result<()>

pub fn find_key_by_public_keys( &self, key: &dyn PublicKeysProvider, ) -> Option<&Key>

pub fn find_key_by_reference(&self, reference: &Reference) -> Option<&Key>

pub fn private_key_envelope_for_key( &self, public_keys: &PublicKeys, password: Option<&str>, ) -> Result<Option<Envelope>>

Get the private key envelope for a specific key, optionally decrypting it.

Arguments

• public_keys - The public keys identifying the key to retrieve
• password - Optional password for decryption

Returns

• Ok(None) if the key is not found or has no private key
• Ok(Some(Envelope)) containing:
  • Decrypted PrivateKeys if unencrypted
  • Decrypted PrivateKeys if encrypted and correct password provided
  • Encrypted envelope if encrypted and no password provided
• Err(Error::InvalidPassword) if encrypted and wrong password provided

Examples

use bc_components::{PrivateKeyBase, PublicKeysProvider};
use bc_envelope::prelude::*;
use bc_xid::{XIDDocument, XIDGenesisMarkOptions, XIDInceptionKeyOptions};

let prvkey_base = PrivateKeyBase::new();
let doc = XIDDocument::new(
    XIDInceptionKeyOptions::PrivateKeyBase(prvkey_base.clone()),
    XIDGenesisMarkOptions::None,
);

// Get unencrypted private key
let key = doc.keys().iter().next().unwrap();
let envelope = doc
    .private_key_envelope_for_key(key.public_keys(), None)
    .unwrap()
    .unwrap();

pub fn take_key(&mut self, key: &dyn PublicKeysProvider) -> Option<Key>

pub fn remove_key(&mut self, key: &dyn PublicKeysProvider) -> Result<()>

pub fn set_name_for_key( &mut self, key: &dyn PublicKeysProvider, name: impl Into<String>, ) -> Result<()>

pub fn is_inception_signing_key( &self, signing_public_key: &SigningPublicKey, ) -> bool

pub fn inception_signing_key(&self) -> Option<&SigningPublicKey>

pub fn inception_key(&self) -> Option<&Key>

pub fn remove_inception_key(&mut self) -> Option<Key>

pub fn verification_key(&self) -> Option<&SigningPublicKey>

pub fn encryption_key(&self) -> Option<&EncapsulationPublicKey>

pub fn inception_private_keys(&self) -> Option<&PrivateKeys>

Get the private keys from the inception key, if available.

Returns None if there is no inception key or if the inception key does not have private key material (e.g., if it was encrypted and not decrypted).

pub fn extract_inception_private_keys_from_envelope( envelope: &Envelope, password: &[u8], ) -> Result<Option<PrivateKeys>>

Extract private keys from an envelope containing an encrypted XIDDocument.

This is a convenience method that loads the document with the password and returns the inception key’s private keys if available.

Returns None if:

• The document has no inception key
• The inception key has no private key material
• The password is incorrect

pub fn is_empty(&self) -> bool

pub fn delegates(&self) -> &HashSet<Delegate>

pub fn delegates_mut(&mut self) -> &mut HashSet<Delegate>

pub fn add_delegate(&mut self, delegate: Delegate) -> Result<()>

pub fn find_delegate_by_xid( &self, xid_provider: &dyn XIDProvider, ) -> Option<&Delegate>

pub fn find_delegate_by_reference( &self, reference: &Reference, ) -> Option<&Delegate>

pub fn take_delegate( &mut self, xid_provider: &dyn XIDProvider, ) -> Option<Delegate>

pub fn remove_delegate(&mut self, xid_provider: &dyn XIDProvider) -> Result<()>

pub fn find_service_by_uri(&self, uri: impl AsRef<URI>) -> Option<&Service>

pub fn services(&self) -> &HashSet<Service>

pub fn add_service(&mut self, service: Service) -> Result<()>

pub fn take_service(&mut self, uri: impl AsRef<URI>) -> Option<Service>

pub fn check_services_consistency(&self) -> Result<()>

pub fn check_service_consistency(&self, service: &Service) -> Result<()>

pub fn check_contains_key(&self, key: &dyn PublicKeysProvider) -> Result<()>

pub fn check_contains_delegate( &self, xid_provider: &dyn XIDProvider, ) -> Result<()>

pub fn services_reference_key(&self, key: &dyn PublicKeysProvider) -> bool

pub fn services_reference_delegate( &self, xid_provider: &dyn XIDProvider, ) -> bool

pub fn remove_service(&mut self, uri: impl AsRef<URI>) -> Result<()>

pub fn provenance(&self) -> Option<&ProvenanceMark>

pub fn provenance_generator(&self) -> Option<&ProvenanceMarkGenerator>

pub fn set_provenance(&mut self, provenance: Option<ProvenanceMark>)

pub fn set_provenance_with_generator( &mut self, generator: ProvenanceMarkGenerator, mark: ProvenanceMark, )

pub fn next_provenance_mark_with_embedded_generator( &mut self, password: Option<Vec<u8>>, date: Option<Date>, info: Option<CBOR>, ) -> Result<()>

Advance the provenance mark using the embedded generator.

This method uses the generator embedded in the document’s provenance to generate the next provenance mark. If the generator is encrypted, it will be decrypted using the provided password. After advancement, the generator remains in the document in decrypted state.

Parameters

• password: Optional password to decrypt the generator if encrypted. Pass as Vec<u8> or None.
• date: Optional date for the new mark. If None, the current date is used.
• info: Optional CBOR-encodable info to attach to the new mark.

Errors

Returns an error if:

• The document does not have a provenance mark (Error::NoProvenanceMark)
• The document does not have a generator (Error::NoGenerator)
• The generator is encrypted and the password is wrong (Error::InvalidPassword)

pub fn next_provenance_mark_with_provided_generator( &mut self, generator: &mut ProvenanceMarkGenerator, date: Option<Date>, info: Option<CBOR>, ) -> Result<()>

Advance the provenance mark using a provided generator.

This method uses an external generator to generate the next provenance mark. The generator is not embedded in the document after advancement; the caller maintains ownership of the generator.

Parameters

• generator: Mutable reference to the external ProvenanceMarkGenerator.
• date: Optional date for the new mark. If None, the current date is used.
• info: Optional CBOR-encodable info to attach to the new mark.

Errors

Returns an error if:

• The document does not have a provenance mark (Error::NoProvenanceMark)
• The document already has an embedded generator (Error::GeneratorConflict)
• The provided generator’s chain ID doesn’t match the current mark’s chain ID
• The provided generator’s next_seq doesn’t match the expected sequence number

pub fn to_envelope( &self, private_key_options: XIDPrivateKeyOptions, generator_options: XIDGeneratorOptions, signing_options: XIDSigningOptions, ) -> Result<Envelope>

Convert XIDDocument to an Envelope.

pub fn from_envelope( envelope: &Envelope, password: Option<&[u8]>, verify_signature: XIDVerifySignature, ) -> Result<Self>

Extract an XIDDocument from an envelope.

Parameters

• envelope: The envelope to extract the document from. Can be signed or unsigned.
• password: Optional password to decrypt encrypted private keys. If private keys are encrypted and no password is provided, the keys will be stored without their private key material.
• verify_signature: Signature verification mode. Use XIDVerifySignature::None to skip verification, or XIDVerifySignature::Inception to verify that the envelope is signed with the inception key.

Returns

Returns Ok(XIDDocument) on success.

Errors

• Error::EnvelopeNotSigned: When verify_signature is Inception but the envelope is not signed.
• Error::MissingInceptionKey: When verify_signature is Inception but the inception key is not found in the document.
• Error::SignatureVerificationFailed: When the signature verification fails.
• Error::InvalidXid: When the inception key does not match the XID.
• Other errors from envelope parsing or key extraction.

pub fn to_signed_envelope(&self, signing_key: &impl Signer) -> Envelope

pub fn to_signed_envelope_opt( &self, signing_key: &impl Signer, private_key_options: XIDPrivateKeyOptions, ) -> Envelope

Trait Implementations

impl AsRef<XIDDocument> for XIDDocument

fn as_ref(&self) -> &XIDDocument

Converts this type into a shared reference of the (usually inferred) input type.

impl Attachable for XIDDocument

fn attachments(&self) -> &Attachments

Returns a reference to the attachments container.

fn attachments_mut(&mut self) -> &mut Attachments

Returns a mutable reference to the attachments container.

fn add_attachment( &mut self, payload: impl EnvelopeEncodable, vendor: &str, conforms_to: Option<&str>, )

Adds a new attachment with the specified payload and metadata.

fn get_attachment(&self, digest: Digest) -> Option<&Envelope>

Retrieves an attachment by its digest.

fn remove_attachment(&mut self, digest: Digest) -> Option<Envelope>

Removes an attachment by its digest.

fn clear_attachments(&mut self)

Removes all attachments from the object.

fn has_attachments(&self) -> bool

Returns whether the object has any attachments.

impl CBORTagged for XIDDocument

fn cbor_tags() -> Vec<Tag>

Returns the CBOR tags associated with this type.

impl CBORTaggedDecodable for XIDDocument

fn from_untagged_cbor(cbor: CBOR) -> Result<Self>

Creates an instance of this type by decoding it from untagged CBOR.

fn from_tagged_cbor(cbor: CBOR) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from tagged CBOR.

fn from_tagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded tagged CBOR.

fn from_untagged_cbor_data(data: impl AsRef<[u8]>) -> Result<Self, Error>

where Self: Sized,

Creates an instance of this type by decoding it from binary encoded untagged CBOR.

impl CBORTaggedEncodable for XIDDocument

fn untagged_cbor(&self) -> CBOR

Returns the untagged CBOR encoding of this instance.

fn tagged_cbor(&self) -> CBOR

Returns the tagged CBOR encoding of this instance.

fn tagged_cbor_data(&self) -> Vec<u8>

Returns the tagged value in CBOR binary representation.

impl Clone for XIDDocument

fn clone(&self) -> XIDDocument

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for XIDDocument

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for XIDDocument

fn default() -> Self

Returns the “default value” for a type.

impl Edgeable for XIDDocument

fn edges(&self) -> &Edges

Returns a reference to the edges container.

fn edges_mut(&mut self) -> &mut Edges

Returns a mutable reference to the edges container.

fn add_edge(&mut self, edge_envelope: Envelope)

Adds a pre-constructed edge envelope.

fn get_edge(&self, digest: Digest) -> Option<&Envelope>

Retrieves an edge by its digest.

fn remove_edge(&mut self, digest: Digest) -> Option<Envelope>

Removes an edge by its digest.

fn clear_edges(&mut self)

Removes all edges.

fn has_edges(&self) -> bool

Returns whether the object has any edges.

impl From<&PrivateKeyBase> for XIDDocument

fn from(inception_key: &PrivateKeyBase) -> Self

Converts to this type from the input type.

impl From<PrivateKeyBase> for XIDDocument

fn from(inception_key: PrivateKeyBase) -> Self

Converts to this type from the input type.

impl From<PublicKeys> for XIDDocument

fn from(inception_key: PublicKeys) -> Self

Converts to this type from the input type.

impl From<XID> for XIDDocument

fn from(xid: XID) -> Self

Converts to this type from the input type.

impl From<XIDDocument> for CBOR

fn from(value: XIDDocument) -> Self

Converts to this type from the input type.

impl From<XIDDocument> for Envelope

fn from(value: XIDDocument) -> Self

Converts to this type from the input type.

impl From<XIDDocument> for XID

fn from(doc: XIDDocument) -> Self

Converts to this type from the input type.

impl PartialEq for XIDDocument

fn eq(&self, other: &XIDDocument) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl ReferenceProvider for XIDDocument

fn reference(&self) -> Reference

Returns a cryptographic reference that uniquely identifies this object.

fn ref_hex(&self) -> String

Returns the reference data as a hexadecimal string.

fn ref_data_short(&self) -> [u8; 4]

Returns the first four bytes of the reference.

fn ref_hex_short(&self) -> String

Returns the first four bytes of the reference as a hexadecimal string.

fn ref_bytewords(&self, prefix: Option<&str>) -> String

Returns the first four bytes of the reference as upper-case ByteWords.

fn ref_bytemoji(&self, prefix: Option<&str>) -> String

Returns the first four bytes of the reference as Bytemoji.

impl TryFrom<&Envelope> for XIDDocument

type Error = Error

The type returned in the event of a conversion error.

fn try_from(envelope: &Envelope) -> Result<Self>

Performs the conversion.

impl TryFrom<CBOR> for XIDDocument

type Error = Error

The type returned in the event of a conversion error.

fn try_from(cbor: CBOR) -> Result<Self>

Performs the conversion.

impl TryFrom<Envelope> for XIDDocument

type Error = Error

The type returned in the event of a conversion error.

fn try_from(envelope: Envelope) -> Result<Self>

Performs the conversion.

impl XIDProvider for XIDDocument

fn xid(&self) -> XID

Returns the XID for this object.

impl Eq for XIDDocument

impl StructuralPartialEq for XIDDocument