diff --git a/ARCs/arc-0113.md b/ARCs/arc-0113.md new file mode 100644 index 000000000..cabe7ea38 --- /dev/null +++ b/ARCs/arc-0113.md @@ -0,0 +1,325 @@ +--- +arc: 113 +title: Verifiable Credentials (VCs) +description: Verifiable Credentials V 2.0 for Algorand. +author: MG (@emg110), GoPlausible (@GoPlausible), GoraNetwork (@GoraNetwork), DaffiDigital (@DaffiDigital) +status: Draft +type: Standards Track +category: ARC +created: 2023-12-18 +requires: 13, 52, 110 +--- + +## Abstract + +This ARC represents the W3C Verifiable Credentials Data Model Version 2.0 (17 December 2023) and Verifiable Credential Data Integrity 1.0living standards and also Verifiable Credentials API v0.3 and Verifiable Credential Controllers Standard Editor drafts, requirements, conventions and recommendations adopted for Algorand and AVM elements, methods as well as related ARCs. + +[ARC-113](./arc-0113.md) introduces the Verifiable Credentials ABI v0.3 in accordance to Verifiable Credentials API v0.3, deliverable through ABI calls with proper arguments according to [ARC-4](./arc-0004.md)! + +It can be implemented using/for ARC ASAs as an extension! Including support for: + +- [ARC-3](./arc-0003.md) +- [ARC-19](./arc-0019.md) +- [ARC-69](./arc-0069.md) +- [ARC-72](./arc-0072.md) +- [ARC-200](./arc-0200.md) + +ARC-113 as well as [ARC-13](./arc-0013.md), heavily depend and rely on [ARC-52](./arc-0052.md) line of work and reference implementation to proceed on both proofs and integrity parts! + +This ARC partially complies to Securing Verifiable Credentials using JOSE and COSE with focus on JOSE only! + +ARC-113 by using ARC-13 as DID standard and reference implementation, partially follows did:web Method Specification as well! + +[ARC-113] is in full compliance to: +- [ARC-13](./arc-0013.md) +- [ARC-110](./arc-0110.md) + +The goal to [ARC-113] is first to adopt VerifiableCredentials standards for already in place transaction history of chain and secondly to set AVM native conventions and methods as extension to original standard so that registering new VCs can be accessed publicly and generated dynamically for each transaction using either an API or an ABI! + +Important note: [ARC-113] tries to follow a micro architecture and plug and play approach in a way that Verifiers in general can offer their services and then depending on the service being available onchain (decentralized) or off chain (web 2.0) then can be included through either main verifiers or service extended (URI based services) verification relations! + +NOTE: THIS IS A DRAFT ARC! WORK IN PROGRESS! ALL HELP WELCOME! + +### General Format + +All authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative. The key words "MAY," "MUST," "MUST NOT," "OPTIONAL," "RECOMMENDED," "REQUIRED," "SHOULD," and "SHOULD NOT" in this document are to be interpreted as described in BCP 14 RFC2119 and RFC8174 when, and only when, they appear in all capitals, as shown here. + +Algorand DID elements used by this ARC follow the URI format in general as outlined in RFC 3986. This ARC aims to be as future-proof as possible; therefore, some generalized architectural elements and conventions (e.g., fragments and paths) may be set forth that may not find immediate use in the current ecosystem tooling. + +Elements of the query component may contain characters outside the valid range. These must first be encoded according to UTF-8, and then each octet of the corresponding UTF-8 sequence must be percent-encoded as described in [RFC 3986]. + +A conforming document is a compacted JSON-LD document that complies with all of the relevant "MUST" statements in this specification. Specifically, the relevant normative "MUST" statements in Sections 4. Basic Concepts, 5. Advanced Concepts, and 6. Syntaxes of this document MUST be enforced. A conforming document is either a verifiable credential that MUST be serialized using the application/vc+ld+json media type or a verifiable presentation that MUST be serialized using the application/vp+ld+json media type. A conforming document MUST be secured by at least one securing mechanisms mentioned by this document! + +A conforming issuer implementation produces conforming documents, MUST include all required properties in the conforming documents that it produces, and MUST secure the conforming documents it produces using a securing mechanism as described in securing mechanisms mentioned by this document. + +A conforming verifier implementation consumes conforming documents, MUST perform verification on a conforming document as described in securing mechanisms in this document, MUST check that each required property satisfies the normative requirements for that property, and MUST produce errors when non-conforming documents are detected. + +## Specification + +The [ARC-113] standard aims to seamlessly integrate the W3C Verifiable Credentials (VCs) Data Model, integrity and API for Algorand and AVM elements, leveraging all available tech stack and existing ARCs. This integration ensures that VCs on Algorand maintain usability, extendability and interoperability as well as compliance to DID standards through [ARC-13]! This integration and harmony is essential for verifiable digital identity and decentralized credentials, authentication, verification, and their presentations. + +[ARC-113] identifiers used with Verifiable Credentials ecosystem SHOULD BE an [ARC-13] DID! + +### Verifiable Credentials ecosystem Specification: +- **Holder**: An atomic or composite DID available on AVM ledger. Example holders include individual Algorand accounts like students, employees, and customers or composite ones like organizations, groups, universities, NGOs, DAOs, societies, clubs and ...! +- **Issuer** : An atomic or composite DID available on AVM ledger asserting claims about one or more subjects, creating a verifiable credential from these claims, and transmitting the verifiable credential to a holder. Example issuers include corporations, non-profit organizations, trade associations, governments, and individuals. +- **Subject**: An atomic or composite DID available on AVM ledger, about which claims are made. Example subjects include human beings, animals, and things tagged with DIDs. In many cases the holder of a verifiable credential is the subject, but in certain cases it is not. For example, an account DID (the holder) might hold the verifiable credentials of a NFT (the subject), or a TravelX ticket owner (the holder) might hold the verifiable credentials of their ticket (the subject), presentable everywhere from airport to vacation lottery websites. +- **Verifier**: An atomic or composite DID available on AVM ledger receiving one or more verifiable credentials, optionally inside a verifiable presentation, for processing. Example verifiers include universities, governments, and banks. +- **Verifiable data registry**: A role a system might perform by mediating the creation and verification of identifiers, keys, and other relevant data, such as verifiable credential schemas, revocation registries, issuer public keys, and so on, which might be required to use verifiable credentials. Some configurations might require correlatable identifiers for subjects. Example verifiable data registries include trusted databases, decentralized databases, government ID databases, and distributed ledgers. Often there is more than one type of verifiable data registry utilized in an ecosystem. + +### Verifiable Credentials necessities specification: + +- Verifiable credentials represent statements made by an issuer in a tamper-evident and privacy-respecting manner. +- Holders can assemble collections of verifiable credentials from different issuers into a single artifact, a verifiable presentation. +- Issuers can issue verifiable credentials about any subject. +- Acting as issuer, holder, or verifier requires neither registration nor approval by any authority, as the trust involved is bilateral between parties. +- Verifiable presentations allow any verifier to verify the authenticity of verifiable credentials from any issuer. +- Holders can receive verifiable credentials from anyone. +- Holders can interact with any issuer and any verifier through any user agent. +- Holders can share verifiable presentations, which can then be verified without revealing the identity of the verifier to the issuer. +- Holders can store verifiable credentials in any location, without affecting their verifiability and without the issuer knowing anything about where they are stored or when they are accessed. +- Holders can present verifiable presentations to any verifier without affecting authenticity of the claims and without revealing that action to the issuer. +- A verifier can verify verifiable presentations from any holder, containing proofs of claims from any issuer. +- Verification should not depend on direct interactions between issuers and verifiers. +- Verification should not reveal the identity of the verifier to any issuer. +The specification must provide a means for issuers to issue verifiable credentials that support selective disclosure, without requiring all conformant software to support that feature. +- Issuers can issue verifiable credentials that support selective disclosure. +If a single verifiable credential supports selective disclosure, then holders can present proofs of claims without revealing the entire verifiable credential. +- Verifiable presentations can either disclose the attributes of a verifiable credential, or satisfy derived predicates requested by the verifier. Derived predicates are Boolean conditions, such as greater than, less than, equal to, is in set, and so on. +Issuers can issue revocable verifiable credentials. +- The processes of cryptographically protecting and verifying verifiable credentials and verifiable presentations have to be deterministic, bi-directional, and lossless. Any verifiable credential or verifiable presentation has to be transformable to the JSON-LD data model defined in this document via a deterministic process so that its verification can be processed in an interoperable fashion. +- Verifiable credentials and verifiable presentations have to be serializable in one or more machine-readable data formats. The process of serialization and/or de-serialization has to be deterministic, bi-directional, and lossless. Any serialization of a verifiable credential or verifiable presentation needs to be transformable to the generic data model defined in this document in a deterministic process such that the resulting verifiable credential can be processed in an interoperable fashion. The serialized form also needs to be able to be generated from the data model without loss of data or content. +- The data model and serialization must be extendable with minimal coordination. +- Revocation by the issuer should not reveal any identifying information about the subject, the holder, the specific verifiable credential, or the verifier. +- Issuers can disclose the revocation reason. +- Issuers revoking verifiable credentials should distinguish between revocation for cryptographic integrity (for example, the signing key is compromised) versus revocation for a status change (for example, the driver's license is suspended). +- Issuers can provide a service for refreshing a verifiable credential. + +```mermaid +flowchart LR + subgraph vc ["Verifiable Credential"] + issuer["Issuer"] -->|Issues| credential["Credential"] + subject["Subject"] -->|Subject of| credential + credential -->|Presented by| holder["Holder"] + + proof -->|Signed by| verifier["Verifier"] + proof -->|Proof of| credential + end + + holder -->|Presents to| verifier["Verifier"] + verifier -->|Verifies| credential + + style vc stroke:#333,stroke-width:2px +``` + +Holders of verifiable credentials can generate verifiable presentations and then share these verifiable presentations with verifiers to prove they possess verifiable credentials with certain characteristics. + +```mermaid +flowchart LR + holder["Holder"] -->|Requests Credential| issuer["Issuer"] + issuer -->|Issues Credential| holder + holder -->|Creates Presentation| presentation["Verifiable Presentation"] + presentation -->|Presents to| verifier["Verifier"] + verifier -->|Verifies Presentation| presentation + verifier -->|Optionally, Verifies Credential| credential["Verifiable Credential"] + credential -->|Issued by| issuer + + style presentation stroke:#333,stroke-width:2px + +``` +### Metadata Grammar and properties + +The metadata for verifiable credentials on Algorand will adhere to the standards set forth in the W3C Verifiable Credentials Data Model, adapted to fit the unique identifiers and structures of the Algorand blockchain. This includes the use of Algorand-specific terms and properties within the credential's metadata. + +#### Internationalization convention: +[ARC-113] supports expressing content in different languages. To express a string with language and base direction information, one can use an object that contains the @value, @language, and @direction properties to express the text value, language tag, and base direction, respectively: + +``` +"[=property=]": { + "@value": "The string value", + "@language": "`LANGUAGE`" + "@direction": "`DIRECTION`" +} + +``` + +Example name with all different internationalization properties: + +``` +"name": [{ + "@value": "Example University", + "@language": "en" + }, { + "@value": "Université de Exemple", + "@language": "fr" + }, { + "@value": "جامعة المثال", + "@language": "ar", + "@direction": "rtl" + }] +``` +#### Properties +- @context: + [ARC-113] requires for a @context property to be present; this property is defined by [JSON-LD]. + The value of the @context property MUST be an ordered set where the first item is a URL with the value [https://www.w3.org/ns/credentials/v2]. For reference, a copy of the base context is provided in Appendix. Subsequent items in the array MUST be composed of any combination of URLs and/or objects where each is processable as a [JSON-LD] Context. +- id: + The value of the id property MUST be a single URL. It is RECOMMENDED that the URL in the id be one which, if dereferenced, results in a document containing machine-readable information about the id. + + - The id property MUST express an identifier that others are expected to use when expressing statements about a specific thing identified by that identifier. + - The id property MUST NOT have more than one value. + - The value of the id property MUST be a URL which MAY be dereferenced. +- type: + Verifiable claims, credentials and presentations MUST have a type property. That is, any credential or presentation that does not have type property is not verifiable, so is neither a verifiable credential nor a verifiable presentation. +- name: +An OPTIONAL property that expresses the name of the credential. If present, the value of the name property MUST be a string or a language value object as described in 11.1 Language and Base Direction. Ideally, the name of a credential is concise, human-readable, and could enable an individual to quickly differentiate one credential from any other credentials that they might hold. +- description: +An OPTIONAL property that conveys specific details about a credential. If present, the value of the description property MUST be a string or a language value object as described in 11.1 Language and Base Direction. Ideally, the description of a credential is no more than a few sentences in length and conveys enough information about the credential to remind an individual of its contents without their having to look through the entirety of the claims. +- credentialSubject: +The value of the credentialSubject property is defined as a set of objects where each object MUST be the subject of one or more claims, which MUST be serialized inside the credentialSubject property. Each object MAY also contain an id to identify the subject! +- issuer: +The value of the issuer property MUST be either a URL, or an object containing an id property whose value is a URL; in either case, the issuer selects this URL to identify itself in a globally unambiguous way. It is RECOMMENDED that the URL be one which, if dereferenced, results in a controller document VC-CONTROLLER-DOCUMENT about the issuer that can be used to verify the information expressed in the credential. It is also possible to express additional information about the issuer by associating an object with the issuer property! +- validFrom: +If present, the value of the validFrom property MUST be an XMLSCHEMA11-2 dateTimeStamp string value representing the date and time the credential becomes valid, which could be a date and time in the future or in the past. Note that this value represents the earliest point in time at which the information associated with the credentialSubject property becomes valid. If a validUntil value also exists, the validFrom value MUST express a datetime that is temporally the same or earlier than the datetime expressed by the validUntil value. This [XMLSCHEMA11-2] dateTimeStamp string format is available through [ARC-113] universal library as a method output! +- validUntil: +If present, the value of the validUntil property MUST be an [XMLSCHEMA11-2] dateTimeStamp string value representing the date and time the credential ceases to be valid, which could be a date and time in the past or in the future. Note that this value represents the latest point in time at which the information associated with the credentialSubject property is valid. If a validFrom value also exists, the validUntil value MUST express a datetime that is temporally the same or later than the datetime expressed by the validFrom value. This [XMLSCHEMA11-2] dateTimeStamp string format is available through [ARC-113] universal library as a method output! +- proof +One or more cryptographic proofs that can be used to detect tampering and verify the authorship of a verifiable credential or a verifiable presentation. Each proof is a separate named graph (referred to as a proof graph) containing a single proof. The specific method used for an embedded proof MUST be identified using the type property. +- credentialStatus + If present, the value of the credentialStatus property MUST include the following: + - id property, which MUST be a URL which MAY be dereferenced. + - type property, which expresses the credential status type. + + The precise content of the credential status information is determined by the specific credentialStatus type definition, and varies depending on factors such as whether it is simple to implement or if it is privacy-enhancing. It is expected that the value will provide enough information to determine the current status of the credential and that machine readable information will be retrievable from the URL. For example, the object could contain a link to an external document which notes whether or not the credential is suspended or revoked. + + +### Verifiable Credential document lifecycle + +The main types for Verifiable Credential documents on AVM chains include: + +- Verifiable Claims document: + Unverified Verifiable Credential documents are still Verifiable Claims which are claimable unverified (except for the issuer which is verifiable) draft Verifiable Credential documents, issued to be claimed by eligible users! + The claim process MUST contain all or part of verifications needed to satisfy claims under Verifiable Credential! + This is considering: + - The issuer and owner of the Verifiable Credential might be different + - The logic of verification for eligibility of claiming the Verifiable Credential (and its included claims) can be off-chain, on-chain or both! + - The decentralized and Web 3.0 initial values is to give the power of ownership, action and control to user so using the Verifiable Claim approach it is user who initiates the Verification and Claim process! + This is notable that a single Verifiable Credential can be a composite of multiple other Verifiable Credentials which have different approval and verification processes that MIGHT happen sequentially or in parallel! + + Dynamic Verifiable Credentials, the ones that are generated for AVM transactions and delivered by universal [ARC-113] verifiable registry and resolver API, ABI and UI, does not need this step and Verifiable Claim document does not exist for them since the Verifiable Credential is generated all at once based on this ARC ([ARC-113])! + + Verifiable Credentials are issued as Verifiable claims and after review and verification by verifier then will include the proof used by verifier and therefore can be verified by any third party through cryptography or Algorand stateproofs. + + ```mermaid + flowchart TB + vcs["Verifiable Claim"] --> metadata["Credential Metadata"] + vcs["Verifiable Claim"] --> claims["Claims"] + vcs["Verifiable Claim"] --> proofs["Proofs"] + ``` + + + Note: Proofs on Verifiable Claim stage are limited to OPTIONAL Issuer proof references only! + + Note2: [ARC-113] deviates from VC living standard + +- Verifiable presentation document: + + Verifiable Presentations are documents containing VCs to be presented for verification and signing which adds the proof for VCs. + + ```mermaid + flowchart TB + vcs["Verifiable Presentation"] --> metadata["Presentation Metadata"] + vcs["Verifiable Presentation"] --> credentials["Verifiable Credentials"] + vcs["Verifiable Presentation"] --> proofs["Proofs"] + ``` + + - id: + The id property is optional. It MAY be used to provide a unique identifier for the verifiable presentation. If present, the normative guidance in Section 4.3 Identifiers MUST be followed. + - type: + The type property MUST be present. It is used to express the type of verifiable presentation. One value of this property MUST be VerifiablePresentation, but additional types MAY be included. The related normative guidance in Section 4.4 Types MUST be followed. + - verifiableCredential + The verifiableCredential property MAY be present. The value MUST be one or more verifiable credential and/or enveloped verifiable credential objects (to be clear, the values MUST NOT be non-object values such as numbers, strings, or URLs). These types of objects are called verifiable credential graphs and MUST express information that is secured using a securing mechanism. See Section 5.12 Verifiable Credential Graphs for further details. + - holder + The verifiable presentation MAY include a holder property. If present, the value MUST be either a URL or an object containing an id property. It is RECOMMENDED that the URL in the holder or its id be one which, if dereferenced, results in a document containing machine-readable information about the holder that can be used to verify the information expressed in the verifiable presentation. If the holder property is absent, information about the holder is expected to either be obtained via the securing mechanism, or to not pertain to the validation of the verifiable presentation. + - proof + The verifiable presentation MAY include a proof property, which refers to a separate named graph containing a single proof. The specific method used for the MUST be identified using the type property. The proof covers of all claims in the following graphs: + + - the verifiable presentation graph; + - all verifiable credential graphs referred to by the verifiableCredential property of the presentation, as well as their corresponding proof graphs. + +- Verifiable Credential document + This is the proof-contained, verifiable document and can be shared and used for verifying a credential in general! + + ```mermaid + flowchart TB + vcs["Verifiable Credential"] --> metadata[Verifiable Credential metadata] + vcs["Verifiable Credential"] --> claims[Verifiable Credential Claims] + vcs["Verifiable Credential"] --> proofs[Verifiable Credential Proofs] + ``` + + + - **Credential Subject**: Identifies the entity the credential is about, which can be linked to an Algorand DID. + - **Issuer**: The entity that issues and attests to the verifiable credential, identified by an Algorand DID. + - **Issuance Date**: The date on which the credential was issued. + - **Claims**: The entity that issues and attests to the verifiable credential, identified by an Algorand DID. + - **Proof**: Cryptographic proof that verifies the authenticity of the credential, such as digital signatures. + + + +### Verifiable Credential requirements +Required decentralized identifiers and implementations which are used to construct VC main elements are (in compliance to [ARC-13](./arc-0013.md)): + +- Algorand DID URI: This is the unique identifier for a subject within the Algorand ecosystem. It follows the standard DID format but is specific to Algorand. + +- Algorand DID Document: This document contains information associated with the Algorand DID, such as verification methods and service endpoints. + +- DID Subject: The entity that the DID represents, which could be a user, an asset, an application, or any identifiable entity on Algorand. + +- DID Controller: The entity that has the capability to make changes to the DID document. This could be the DID subject itself or another authorized entity. + +- Verifiable Data Registry (Algorand Blockchain): The Algorand blockchain acts as the verifiable data registry where DIDs are recorded and can be looked up. GoPlausible API and ABI are the service interfaces delivering this facility and PLAUSIBLE protocol has expanded to include this role on Algorand blockchain as first Verifiable Data Registry! + +- DID Resolver: A system component that takes a DID as input and produces the corresponding DID document as output. GoPlausible API and ABI now include Algorand DID resolver endpoints and also there is a universal ES module (JS) client library algo-did-resolverfor dApp integration on client side, available through NPM! + +## Rationale + +The rationale behind [ARC-113] is to provide a robust framework for creating, issuing, and verifying digital credentials on the Algorand blockchain. By aligning with the W3C Verifiable Credentials standard, [ARC-113] ensures interoperability with global digital identity systems, enhancing the utility and trustworthiness of credentials within the Algorand ecosystem. +All protocols and projects on Algorand can use and benefit from VCs on Algorand to make their protocols and dApps more compliant to regulations , e.g GDPR and EU Blockchain regulations! + +Especially for adoption by global organizations, this becomes a requirement that ecosystem offers integration, adoption and interoperability with Verifiable Credentials as they are widely in use and are common best practice in Web 2.0 as well! + +## Security Considerations + +Security considerations for [ARC-113] include ensuring the integrity and verifiability of verifiable credentials, secure management of cryptographic keys, and adherence to privacy-preserving principles in credential issuance and verification. + +This specification recognizes 3 classes of securing mechanisms: those that use enveloping proofs, those that use embedded proofs and state proofs (Zero Knowledge Proofs). An enveloping proof is one that wraps a serialization of this data model. One such enveloping proof mechanism is elaborated on in the Securing Verifiable Credentials using JOSE and COSE [VC-JOSE-COSE] specification. An embedded proof is a mechanism where the proof is included in the data model. One such embedded proof mechanism is Verifiable Credential Data Integrity [VC-DATA-INTEGRITY]. An state proof is a verifiable proof that a transaction is added to decentralized ledger as a certain block! These three classes of securing mechanisms are not mutually exclusive. + +### Trust Model + +The [ARC-113] verifiable credentials trust model, based on Algorand technology features, is as follows: + +The verifier trusts the issuer to issue the credential that it received. To establish this trust, a credential is expected to either: + - Include a transaction or arbitrary data, signed by specific algo DID controller, that cryptographically proves the issuer generated the credential! + - Use the transaction stateproof that verifies the issuer generated the verifiable credential and that the verifiable credential was not tampered with, because of the nature of Algorand blockchain. +Important note: Both these trust scenarios are strong and post-quantum resistant for [ARC-113] implementations because of direct Algorand technology properties and specifications! + +All entities trust the verifiable data registry to be tamper-proof and to be a correct record of which data is controlled by which entities, because it is an on-chain stored value based on a valid and known ABI call transaction. + +The holder and verifier trust the issuer to issue true (that is, not false) credentials about the subject, and to revoke them quickly when appropriate. This is notable that with [ARC-113] scenarios during which a Verifiable Claim is initially generated by the verifier through issuer decentralized service ABI endpoints (methods), this trust model changes so that holder and verifier trust the Issuer's smart contract logic to provide deterministically true VCs and approvals or rejections! + +If the holder needs the repository to store credentials securely, and to not release them to anyone other than the holder, then [ARC-113] uses and recommends using [ARC-52] DH based symmetric secret implementation to make sure credentials are only shared between Holder and Verifier and stored with Issuer registry that securely that way (the DH key enveloped version of credentials will be stored on Issuer's registry) + +This trust model differentiates itself from other trust models by ensuring the: + - Issuer and the verifier do not need to trust the repository + - Issuer does not need to know or trust the verifier. + +//TODO: Securing mechanism specifications based on [ARC-52] to be added! E.g DH secret keys or derived keys for encryption! + +## Appendix + +// TODO: Examples of verifiable credentials and presentations in [JSON-LD] format will be provided, demonstrating the application of [ARC-113] in real-world scenarios. + +## Copyright + +This document and its content are released under the Creative Commons Zero (CC0) license, allowing for maximum flexibility and adoption within the Algorand community and beyond. + +Copyright and related rights waived via CCO.