Struct DTGCredential

Source

pub struct DTGCredential { /* private fields */ }

Expand description

Defined DTG Credentials

Implementations§

Source §

impl DTGCredential

Source

pub fn new_vmc( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, personhood: bool, ) -> Self

Creates a new community-issued Verifiable Membership Credential (VMC) — the membership grant, the community → member half of a membership edge.

A membership edge is a pair of VMCs, and this is only one of them. The member answers with DTGCredential::new_member_vmc, and the edge is not complete until they have: a community can always issue a credential naming somebody as a member, but it cannot produce the acknowledgement without that party’s signature. The pair is what makes an unconsented membership claim unprovable.

The grant MUST NOT carry a digest — that property is what marks the other direction — and this constructor does not set one.

issuer: The C-DID of the VTC or VTN granting membership subject: The M-DID of the member, or the member VTC’s C-DID for VTN membership valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until personhood: Whether this VMC can be used as a form of Personhood Credential - Adds PersonhoodCredential to the type array if true

§Give it an `id`

Chain DTGCredential::with_id on: the member stores the grant under its id, and re-issuing is only recognisable as a renewal rather than a duplicate if there is one.

Source

pub fn new_member_vmc( grant: &DTGCredential, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, ) -> Result<Self, DTGCredentialError>

Creates a new member-issued Verifiable Membership Credential (VMC) — the membership acknowledgement, the member → community half of a membership edge.

The roles of DTGCredential::new_vmc are reversed (the member issues, the community is the subject) and the subject carries a digest of the grant being acknowledged. That digest is what binds the two halves into one edge: an acknowledgement whose digest matches no valid grant does not complete anything, and the binding forces an order — the grant must exist before this can reference it.

This is the member’s consent artifact. Because the member is its issuer, withdrawing consent needs no cooperation from the community.

grant: The community-issued VMC being acknowledged. Its subject is taken as the member and its issuer as the community, so the two halves cannot disagree about who they are between. valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until

§Errors

DTGCredentialError::WrongCredentialType if grant is not a MembershipCredential, and DTGCredentialError::NotAMembershipGrant if it already carries a digest — that is an acknowledgement, and acknowledging one does not form an edge.

§Digest the grant in the form you hold it

The digest covers the grant’s claims and not its proof, so this may be called before or after the grant is signed and gives the same answer either way. What it cannot survive is a grant whose claims differ — a re-issued grant carries a different digest, which is what forces re-acknowledgement on renewal.

§Give it an `id`

As with the grant, chain DTGCredential::with_id on before signing. A community keys a member’s VMC by id to tell a re-send from a renewal.

Source

pub fn new_vrc( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, ) -> Self

Creates a new Verified Relationship Credential (VRC) issuer: The issuer DID of the credential subject: The DID of the subject of this credential valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until

Source

pub fn new_vic( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, ) -> Self

Creates a new Verified Invitation Credential (VIC) issuer: The issuer DID of the credential subject: The DID of the subject of this credential valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until

Source

pub fn new_vpc( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, ) -> Self

Creates a new Verified Persona Credential (VPC) issuer: The issuer DID of the credential subject: The DID of the subject of this credential valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until

Source

pub fn new_vec( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, endorsement: Value, ) -> Self

Creates a new Verified Endorsement Credential (VEC) issuer: The issuer DID of the credential subject: The DID of the subject of this credential valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until endorsement: The endorsement details for this credential

Source

pub fn new_vwc( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, task_context: String, digest: Option<String>, witness_context: Option<WitnessContext>, ) -> Self

Creates a new Verified Witness Credential (VWC) issuer: The issuer DID of the credential - an M-DID, or the DID of a VTA acting according to VTC policy subject: The DID of the observed party. For a witnessed bi-directional exchange this MUST be the issuer of the VRC that this VWC attests (the VRC referenced by digest), so that the two VWCs of an exchange are unambiguously bound to their respective directions. The witness should issue one VWC per direction. valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until task_context: Required threadId of the trust task exchange the witnessing occurred in digest: Cryptographic hash of the witnessed edge credential, binding this VWC to the specific edge. Produce it with DTGCredential::digest on that credential. REQUIRED by the specification; Option here because a VWC that predates the requirement still has to deserialize. A VWC without one identifies the observed party and the exchange, but not which edge was witnessed. witness_context: Optional Semantic context for the witness

Source

pub fn new_rcard( issuer: String, subject: String, valid_from: DateTime<Utc>, valid_until: Option<DateTime<Utc>>, card: Value, ) -> Self

👎Deprecated since 0.2.0:

The r-card is a verifiable data structure (VDS), not a DTGCredential subtype. It was removed from the DTG Core Credentials specification in Working Draft 01 and will be defined by the planned DTG Verifiable Data Structures specification. This constructor will be removed in a future release.

Creates a new Verified RCard Credential (VWC) issuer: The issuer DID of the credential subject: The DID of the subject of this credential valid_from: The datetime from which this credential is valid valid_until: Optional: The datetime this credential is valid until card: JSON Value representing a Jcard (RFC 7095) format

Source

pub fn with_id(self, id: impl Into<String>) -> Self

Sets this credential’s own identifier, consuming and returning it so it chains onto any of the new_* constructors above.

id MUST be a single URL per the W3C VC Data Model; urn:uuid:<uuid> is the usual choice for a credential with no dereferenceable home. This crate does not validate it.

let vmc = DTGCredential::new_vmc(
    "did:example:member".to_string(),
    "did:example:community".to_string(),
    Utc::now(),
    None,
    false,
)
.with_id("urn:uuid:2a4e1d90-6e0c-4d3f-9a4a-6d0a8f7c1b52");
assert_eq!(vmc.id(), Some("urn:uuid:2a4e1d90-6e0c-4d3f-9a4a-6d0a8f7c1b52"));

§Set it before signing

A Data Integrity proof covers the credential minus its proof, so id is part of what is signed. Chain this onto the constructor, before DTGCredential::sign — adding an id to an already-signed credential leaves a document whose proof no longer verifies.

Source

pub fn set_id(&mut self, id: impl Into<String>)

Sets this credential’s own identifier in place.

The non-consuming form of DTGCredential::with_id; the same “before signing” caveat applies.

Source §

impl DTGCredential

Source

pub fn credential(&self) -> &DTGCommon

get the raw credential

Source

pub fn credential_mut(&mut self) -> &mut DTGCommon

Get the raw credential as mutable

Source

pub fn signed(&self) -> bool

Has this credential been signed?

Source

pub fn type_(&self) -> DTGCredentialType

get the credential type

Source

pub fn id(&self) -> Option<&str>

This credential’s own identifier, if it has one.

None for a credential built by one of the new_* constructors and never given one with DTGCredential::with_id. See DTGCommon::id for why a counterparty may require it.

Source

pub fn issuer(&self) -> &str

Returns the Issuer DID

Source

pub fn subject(&self) -> &str

Returns the Subject DID

Source

pub fn valid_from(&self) -> DateTime<Utc>

Returns the valid_from timestamp

Source

pub fn valid_until(&self) -> Option<DateTime<Utc>>

Returns the valid until timestamp

Source

pub fn task_context(&self) -> Option<&str>

The threadId of the trust task exchange this credential was issued in, if set

This is always Some for DTGCredentialType::Witness credentials, where the spec makes taskContext REQUIRED.

Source

pub fn digest(&self) -> Result<String, DTGCredentialError>

This credential’s digest, as the digest property of a credential that references it — a member-issued VMC acknowledging a membership grant, or a VWC attesting an edge credential.

Per DTG Core Credentials, the digest is the SHA-256 hash of the credential’s JSON representation excluding its top-level proof member, canonicalized with the JSON Canonicalization Scheme (JCS, RFC 8785), encoded as sha256: followed by the lowercase hexadecimal digest.

§Why `proof` is excluded

The digest binds to what the credential says, not to a particular signature over it. A referencing credential therefore survives a re-proofing of its referent: a re-signed grant carrying identical claims still satisfies an acknowledgement made against the earlier signature. It also means the digest can be computed before the referent is signed, and is stable whichever of its proofs a holder happens to have.

Source

pub fn subject_digest(&self) -> Option<&str>

The digest this credential carries of the credential it references, if it carries one.

Some for a member-issued VMC (which MUST carry one) and for a VWC bound to the edge credential it attests; None for a community-issued VMC, which MUST omit it, and for every credential type that has no digest property.

Source

pub fn digest_multibase(&self) -> Result<String, DTGCredentialError>

👎Deprecated since 0.4.0:

This encoding is not what DTG Core Credentials specifies, so digests produced by it do not interoperate. Use DTGCredential::digest, which returns the conformant sha256:<lowercase hex> over the proofless JCS canonical form. This method will be removed in a future release.

Computes the digest of this credential in the multibase multihash encoding.

The underlying hash differs from DTGCredential::digest in two ways: it is encoded as a base58btc multibase multihash rather than sha256:<hex>, and it covers the credential including its proof.

Source

pub fn verify_digest( &self, referenced: &DTGCredential, ) -> Result<bool, DTGCredentialError>

Checks that this credential’s digest matches the credential it claims to reference.

Answers one question only — whether the hashes agree. It does not check that the two credentials are of the types the reference requires, nor that their issuers and subjects line up. For a membership acknowledgement, DTGCredential::acknowledges checks all of that together and is what a verifier completing an edge should call.

Returns Ok(false) if the digests do not match, or if this credential carries no digest, in which case there is nothing to rely on.

Source

pub fn acknowledges( &self, grant: &DTGCredential, ) -> Result<bool, DTGCredentialError>

Does this member-issued VMC acknowledge grant, completing that membership edge?

A membership edge is complete only when both VMCs of the pair exist and are valid: the community-issued VMC that grants membership, and the member-issued VMC that acknowledges it. This checks everything that binds the two together:

grant is a MembershipCredential carrying no digest — a community-issued grant
self is a MembershipCredential carrying one — a member-issued acknowledgement
the two name the same pair of parties, in mirrored roles: this credential’s issuer is the grant’s subject, and its subject is the grant’s issuer
the digest matches the grant

Returns Ok(false) where any of those does not hold, rather than distinguishing them: a caller deciding whether an edge is complete has one decision to make, and every failing case answers it the same way.

§What this does not check

Neither credential’s proof, and neither validity window. Both are the caller’s to verify — proof verification needs a resolver this crate does not hold, and whether a window is current is a question about an instant the caller chooses. An edge is complete when both VMCs are valid as well as bound, and this covers only the binding.

Source

pub fn proof_value(&self) -> Option<&str>

Returns the proof value if signed else None

Source

pub async fn sign( &mut self, signing_secret: &Secret, create_time: Option<DateTime<Utc>>, ) -> Result<DataIntegrityProof, DTGCredentialError>

Sign the credential using W3C Data Integrity Proof with JCS EdDSA 2022 signing_secret: The secret key to use to sign the credential create_time: Optional creation time for the proof, defaults to now if None

Source

pub fn verify_proof_with_public_key( &self, public_key_bytes: &[u8], ) -> Result<(), DTGCredentialError>

Verify the credential if you already know the public key bytes otherwise use the affinidi_tdk:verify_data() method public_key_bytes: The public key bytes to use to verify the credential

Source