Struct Credential 

pub struct Credential {
    pub id: u64,
    pub version: CredentialVersion,
    pub issuer_schema_id: u64,
    pub sub: FieldElement,
    pub genesis_issued_at: u64,
    pub expires_at: u64,
    pub claims: Vec<FieldElement>,
    pub associated_data_commitment: FieldElement,
    pub signature: Option<EdDSASignature>,
    pub issuer: EdDSAPublicKey,
}

Base representation of a Credential in the World ID Protocol.

A credential is generally a verifiable digital statement about a subject. It is the canonical object: everything a verifier needs for proofs and authorization.

In the case of World ID these statements are about humans, with the most common credentials being Orb verification or document verification.

Credential Lifecycle

The following official terminology is defined for the lifecycle of a Credential.

• Issuance (can also be called Enrollment): Process by which a credential is initially issued to a user.
• Renewal: Process by which a user requests a new Credential from a previously existing active or expired Credential. This usually happens close to Credential expiration. It is analogous to when you request a renewal of your passport, you get a new passport with a new expiration date.
• Re-Issuance: Process by which a user obtains a copy of their existing Credential. The copy does not need to be exact, but the original expiration date MUST be preserved. This usually occurs when a user accidentally lost their Credential (e.g. disk failure, authenticator loss) and needs to recover for an existing period.

Associated Data

Credentials have a pre-defined strict structure, which is determined by their version. Issuers may opt to include additional arbitrary data with the Credential (Associated Data). This arbitrary data can be used to support the issuer in the operation of their Credential (for example it may contain an identifier to allow credential refresh).

• Associated data is stored by Authenticators with the Credential.
• Introducing associated data is a decision by the issuer. Its structure and content is solely determined by the issuer and the data will not be exposed to RPs or others.
• An example of associated data use is supporting data to re-issue a credential (e.g. a sign up number).
• Associated data is never exposed to RPs or others. It only lives in the Authenticator and may be provided to issuers.
• Associated data is authenticated in the Credential through the associated_data_commitment field. The issuer MUST determine how this commitment is computed. Issuers may opt to use the Credential::associated_data_commitment_from_raw_bytes helper to ensure their raw data is committed, but other commitment mechanisms may make sense depending on the structure of the associated data.

+------------------------------------+
|          Credential                |
|                                    |
|  - associated_data_commitment <----+
|  - signature                       |
+------------------------------------+
              ^
              |
    Commitment(associated_data)
              |
Associated Data
+------------------------------------+
| Optional arbitrary data            |
+------------------------------------+

Design Principles:

• A credential clearly separates:
  • Assertion (the claim being made)
  • Issuer (who attests to it / vouches for it)
  • Subject (who it is about)
  • Presenter binding (who can present it)
• Credentials are usable across authenticators without leaking correlate-able identifiers to RPs.
• Revocation, expiry, and re-issuance are first-class lifecycle properties.
• Flexibility: credentials may take different formats but share common metadata (validity, issuer, trust, type).

All credentials have an issuer and schema, identified with the issuer_schema_id field. This identifier is registered in the CredentialSchemaIssuerRegistry contract. It represents a particular schema issued by a particular issuer. Some schemas are intended to be global (e.g. representing an ICAO-compliant passport) and some issuer-specific. Schemas should be registered in the CredentialSchemaIssuerRegistry contract and should be publicly accessible.

We want to encourage schemas to be widely distributed and adopted. If everyone uses the same passport schema, for example, the Protocol will have better interoperability across passport credential issuers, reducing the burden on holders (to make sense of which passport they have), and similarly, RPs.

Fields

id: u64

A reference identifier for the credential. This can be used by issuers to manage credential lifecycle.

• This ID is never exposed or used outside of issuer scope. It is never part of proofs or exposed to RPs.
• Generally, it is recommended to maintain the default of a random identifier.

Example Uses

• Track issued credentials to later support revocation after refreshing.

version: CredentialVersion

The version of the Credential determines its structure.

issuer_schema_id: u64

Unique issuer schema id represents the unique combination of the credential’s schema and the issuer.

The issuer_schema_id is registered in the CredentialSchemaIssuerRegistry. With this identifier, the RPs lookup the authorized keys that can sign the credential.

sub: FieldElement

The blinded subject (World ID) for which the credential is issued.

The underlying identifier comes from the WorldIDRegistry and is the leaf_index of the World ID on the Merkle tree. However, this is blinded for each issuer_schema_id with a blinding factor to prevent correlation of credentials by malicious issuers. See Self::compute_sub for details on how the credential blinding factor is computed.

genesis_issued_at: u64

Timestamp of first issuance of this credential (unix seconds), i.e. this represents when the holder first obtained the credential. Even if the credential has been issued multiple times (e.g. because of a renewal), this timestamp should stay constant.

This timestamp can be queried (only as a minimum value) by RPs.

expires_at: u64

Expiration timestamp (unix seconds)

claims: Vec<FieldElement>

For Future Use. Concrete statements that the issuer attests about the receiver.

They can be just commitments to data (e.g. passport image) or the value directly (e.g. date of birth).

Currently these statements are not in use in the Proofs yet.

associated_data_commitment: FieldElement

The commitment to the Associated Data issued with the Credential.

This may use a common hashing algorithm from the raw bytes of the asscociated data and one function is exposed for this convenience, hash_bytes_to_field_element. Each issuer however determines how best to construct this value to establish the integrity of their Associated Data.

This commitment is only for issuer use.

signature: Option<EdDSASignature>

The signature of the credential (signed by the issuer’s key)

issuer: EdDSAPublicKey

The public component of the issuer’s key which signed the Credential.

Implementations

impl Credential

pub const MAX_CLAIMS: usize = 16

The maximum number of claims that can be included in a credential.

pub fn new() -> Credential

Initializes a new credential.

Note default fields occupy a sentinel value of BaseField::zero()

pub const fn id(self, id: u64) -> Credential

Set the id of the credential.

pub const fn version(self, version: CredentialVersion) -> Credential

Set the version of the credential.

pub const fn issuer_schema_id(self, issuer_schema_id: u64) -> Credential

Set the issuerSchemaId of the credential.

pub const fn subject(self, sub: FieldElement) -> Credential

Set the sub for the credential.

pub const fn genesis_issued_at(self, genesis_issued_at: u64) -> Credential

Set the genesis issued at of the credential.

pub const fn expires_at(self, expires_at: u64) -> Credential

Set the expires at of the credential.

pub fn claim_hash( self, index: usize, claim: Uint<256, 4>, ) -> Result<Credential, PrimitiveError>

Set a claim hash for the credential at an index.

Errors

Will error if the index is out of bounds.

pub fn claim( self, index: usize, claim: &[u8], ) -> Result<Credential, PrimitiveError>

Set the claim hash at specific index by hashing arbitrary bytes using Poseidon2.

This method accepts arbitrary bytes, converts them to field elements, applies a Poseidon2 hash, and stores the result as claim at the provided index.

Arguments

• claim - Arbitrary bytes to hash (any length).

Errors

Will error if the data is empty and if the index is out of bounds.

pub fn associated_data_commitment( self, associated_data_commitment: Uint<256, 4>, ) -> Result<Credential, PrimitiveError>

Set the associated data commitment of the credential.

Errors

Will error if the provided hash cannot be lowered into the field.

pub fn associated_data_commitment_from_raw_bytes( self, data: &[u8], ) -> Result<Credential, PrimitiveError>

Set the associated data commitment from arbitrary bytes. This can be used to construct the associated data commitment in a canonical way.

This method takes arbitrary bytes, converts them to field elements, applies a Poseidon2 hash, and stores the result as the associated data commitment.

Arguments

• data - Arbitrary bytes to be committed (any length).

Errors

Will error if the data is empty.

pub fn get_cred_ds(&self) -> FieldElement

Get the credential domain separator for the given version.

pub fn claims_hash(&self) -> Result<FieldElement, Report>

Get the claims hash of the credential.

Errors

Will error if there are more claims than the maximum allowed. Will error if the claims cannot be lowered into the field. Should not occur in practice.

pub fn hash(&self) -> Result<FieldElement, Report>

Computes the canonical hash of the Credential.

The hash is signed by the issuer to provide authenticity for the credential.

Errors

• Will error if there are more claims than the maximum allowed.
• Will error if the claims cannot be lowered into the field. Should not occur in practice.

pub fn sign(self, signer: &EdDSAPrivateKey) -> Result<Credential, Report>

Sign the credential.

Errors

Will error if the credential cannot be hashed.

pub fn verify_signature( &self, expected_issuer_pubkey: &EdDSAPublicKey, ) -> Result<bool, Report>

Verify the signature of the credential against the issuer public key and expected hash.

Errors

Will error if the credential is not signed. Will error if the credential cannot be hashed.

pub fn compute_sub( leaf_index: u64, blinding_factor: FieldElement, ) -> FieldElement

Compute the sub for a credential computed from leaf_index and a blinding_factor.

Trait Implementations

impl Clone for Credential

fn clone(&self) -> Credential

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Credential

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

Formats the value using the given formatter.

impl Default for Credential

fn default() -> Credential

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Credential

fn deserialize<__D>( __deserializer: __D, ) -> Result<Credential, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Credential

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.