Unofficial Draft
++ Copyright © + 2024 + the document editors/authors. + Text is available under the + Creative Commons Attribution 4.0 International Public License; additional terms may apply. +
++ This specification describes discovery and exchange mechanisms of W3C Verifiable Credentials Data Model v2.0 [VC-DATA-MODEL], + particularly as they relate to supply chain use cases. + Exchanged Verifiable Credentials often implement schemas defined in + the Traceability Vocabulary [TRACE-VOCAB].. +
++ Using Verifiable Credentials to represent supply chain data enables interoperability between disparate actors, + and provides the ability to cryptographically verify the authenticity of the data. +
++ This specification uses W3C Decentralized Identifiers [DID-CORE] + to identify organizations within a supply chain. This enables organizations to interact with parties + outside their traditional supply chains, and removes the need for a central authority to identify supply chain + organizations. +
++ This document is a draft of a potential specification. It has no official + standing of any kind and does not represent the support or consensus of + any standards organization. +
+
+ This repository will be versioned at periodic points in time with a Q1
+ Calendar Year target for major releases.
+ Versioning tags will follow a pattern of [MAJOR].[MINOR].[PATCH]
+
+ As a rule, versioning will follow the specification outlined in the + Semantic Versioning 2.0 spec This + approach to versioning gives the ability to + integrate with and provide automated testing and validation against + defined types without worry of instability + or breaking changes being introduced, while also limiting the frequency of + possibly breaking changes to prevent + a large number of incompatible versions. +
+ ++ To contribute to this vocabulary or reference technical details related to + the project, please reference the + primary README located on + GitHub. +
+ ++ Please + open an + issue, if you wish to collaborate + on this specification. +
+ ++ You may also reach out via the mailing list: + public-credentials@w3.org + (subscribe, + archives) +
+As well as sections marked as non-normative, 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, and SHOULD in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +
+This section is non-normative.
+ ++ This specification describes how verifiable data can be shared securely + over an authenticated channel. The purpose of the specification is to facilitate + cross trust boundary interactions among organizations conducting or otherwise + involved in trade, seeking to digitize and automate their operations. + Examples of targeted organizations include Buyers, Sellers, Shippers, Consignees, + Carriers, and Customs Authorities. +
+ ++ The specification comprises of the following necessary elements: +
did:webOAuth2-based authenticationhttps-based data exchange endpoint+ The specification is opinionated in order to promote actual interoperability. + Baking more choices into the specification decreases ambiguity for + implementers. +
++ This specification seeks to make implementation as simple and light a lift as possible, + leveraging existing, well-known standards and technologies wherever possible. +
++ This specification attempts not to define any unnecessary functionality beyond the + core use case of interoperability. Some obvious peripheral use cases include + verifiable credential issuance and verification. Implementers are encouraged to design + their platforms and applications to provide such functionality to best serve their + specific circumstances. +
+ ++ The following digital signature algorithms + MUST be implemented by conforming issuers and verifiers. +
+This section is non-normative.
+ ++ Term definitions for this specification can be found in the + Traceability Vocabulary [TRACE-VOCAB]. + This specification does not define any additional terms. +
+This section is non-normative.
+ + ++ The following use cases outline a number of key scenarios that readers might + find useful in a variety of sectors, especially those that deal with cross + border supply chain data interchange. +
+ + ++ The following requirements are necessary for the Verifier to establish binding, enabling the Holder to submit data: +
++ Binding data is provided out of band between parties. The binding data MAY conveniently be exchanged in an environment file. +
++ This exchange of binding information MAY be done bi-directionally between parties, enabling bi-directional flow of data. +
++As supply chains invest in web compatible standards such as +GS1 Digital Link +and GS1 EPCIS, the +need to discover identifiers associated with legal entities, products, +and associated web origins becomes critical to the adoption of +verifiable credentials in a supply chain context. +
+ ++This API specification describes how existing web standards can be +applied to the identifier discovery use case for supply chain actors and +products. +
+ ++The did:web +method MUST be supported. +
+ ++This document defines the discoverability feature +necessary to complete integration tests in postman with authentication. +
+ ++The current APIs exploit the well known DID configuration, +which has some limitations, most notably regarding multi-tenant platforms. +
+ ++An organization will have an application authorized to act on their behalf. +
+ +
+The application will be identified with a CLIENT_ID which MAY be publically shared.
+
+Implementations are encouraged to include specific DIDs per CLIENT_ID in an allow-list.
+
+The application will be authenticated with a CLIENT_SECRET which MUST NOT be disclosed.
+
+The organization MAY have more than one DID. +
+ +
+Each organization DID will have DID URLs for assertionMethod and authentication relationships.
+
+ As a representative of an organization, I can discover another organization's supported API features from their did:web.
+
+1. Resolve did:web:platform.example:organization:123.
+
+This is trivial, simply do:
+
HTTP GET https://platform.example/organization/123/did.json => didDocument.json
+2. Review the serviceEndpoint, and assertionMethod sections of the DID document.
+
+The service block provides a means of communicating or interacting with the DID subject or associated entities via one or more service endpoints. +
+ ++ See service. +
+ ++This entry MUST be present. +
+
+This entry MUST have an element of type TraceabilityAPI with a serviceEndpoint URL for an endpoint which supports presentation exchange.
+
For example:
+ +"service": [
+ {
+ "id": "did:web:platform.example:organization:123#traceability-api",
+ "type": ["TraceabilityAPI"],
+ "serviceEndpoint": "https://platform.example/organization/123"
+ }
+]This definition implies that a /presentations endpoint is available for data submissions:
https://platform.example/organization/123/presentations+This endpoint must be secured as defined in Authentication. + +
+ +
+ The assertionMethod references public key material used by the organization for issuing Verifiable Credentials.
+
+See assertionMethod. +
+ ++ This entry MUST be present. +
+ +
+ This entry MUST have at least one entry referencing an available verificationMethod.
+
+ The verificationMethod contains cryptographic material for public keys.
+
+ See verificationMethod. +
+ +
+ The didDocument MUST contain at least one verificationMethod element.
+
+ The didDocument MUST NOT contain verificationMethods where the controller is different from the DID Subject.
+
+
+ +
+ All JsonWebKey types support securing with JOSE, as described in W3C VC-JOSE-COSE.
+
{
+ "@context": [
+ "https://www.w3.org/ns/did/v1",
+ "https://w3id.org/traceability/v1"
+ ],
+ "id": "did:web:platform.example:organization:123",
+ "assertionMethod": [
+ "did:web:platform.example:organization:123#key1"
+ ],
+ "verificationMethod": [
+ {
+ "id": "did:web:platform.example:organization:123#key1",
+ "type": "JsonWebKey2020",
+ "controller": "did:web:platform.example:organization:123",
+ "publicKeyJwk": {
+ "kty": "OKP",
+ "crv": "Ed25519",
+ "x": "rfsiofZ3RcuMWZSoYbvNEZ_8oxeep8uapJDyT0ku8EM"
+ }
+ }
+ ],
+ "service": [
+ {
+ "id": "did:web:platform.example:organization:123#traceability-api",
+ "type": ["TraceabilityAPI"],
+ "serviceEndpoint": "https://platform.example/organization/123"
+ }
+ ]
+}+ This section describes the HTTP services a conformant Traceability API MUST + implement. +
+ +See the Open API for Interoperable Traceability for the full API definition.
++ Data exchanged according to this specification will often need to + be handled by external systems that have a more transactional + nature. By design, data exchanged using this specification is + asynchronous in nature. This means that certain rules should be + followed to ensure that a reciever of data using this + specification can assemble a graph of connected data elements and + have a high degree of certainty (unless they are missing data) + that the data they are looking at is the most current information, + assembled in the right order, and is the best known state at a + given time. The following section details rules for handling + identifiers and references to data to prevent issues with + informational processing. +
++ Identifiers in objects exchanged using this specification are + particularly important, not least in that they uniquely identify + an object or network transaction, but also, given the + asynchronous nature of this mode of data exchange, that they + present an area where various attacks could arise by sending + data with identifiers already in use with malicious intent to + confuse a receiver of the data. +
++ Identifiers conformant with this spec MUST be + [rfc3986] conformant URIs. Unless otherwise noted, an + identifier MAY be a DID identifier per [did-core], a + UUID v4 per [rfc4122], or a [URL] that identifies a resource + directly. +
++ Presentations in this spec are + Traceable + Presentations, which contain several notable identifiers + that can be used for correlation, retrieval, and business rule + processing of data. +
+
+ TraceablePresentation.id MUST be unique to each
+ presentation. A presentation received with a duplicate ID
+ MUST be rejected with a 409 Conflict status code per
+ [rfc9110]. A presenter encountering this error,
+ SHOULD generate a new presentation, with a new UUID
+ v4 for the ID and then retry the presentation.
+
+ The holder MAY indicate replacement of a previously sent
+ Traceable
+ Presentation with the replace property.
+ If this member is present, its value SHOULD be interpreted as defined in
+ Presentation Replace.
+
+ Multiple Traceable Presentations MAY be correlated by referencing + a Workflow. +
+
+ A TraceablePresentation, while being part of a two party
+ exchange of information via a VerifiablePresentation,
+ provides the ability for multiple parties to exchange related
+ information by use of the same workflow definition and
+ instance. Use of the same workflow definition and instance by
+ multiple presenters implies that the credentials contained in
+ the separate presentations are related, and
+ SHOULD be treated as part of the same instance of a
+ given workflow type. A good
+ example of this type of scenario is when a vendor is exchanging some
+ information, say a commercial invoice,
+ with a third party, such as a broker, and the shipping company is
+ presenting related information to that
+ same broker.
+
+ Verifiable Credentials bundled in
+ Traceable
+ Presentations
+ using this specification MUST contain the property
+ verifiableCredential.id. This ID is unique to the object,
+ entity, or action described in the credential. As per the
+ [VC-DATA-MODEL] "The id property is intended to
+ unambiguously refer to an object, such as a person, product,
+ or organization. Using the id property allows for the
+ expression of statements about specific things in the
+ verifiable credential."
+
+ In the case of credentials used in systems implementing this
+ specification, a credential ID MUST be a UUID v4 per
+ [rfc4122]. The issuing system MUST return the
+ credential in question with an HTTP request to their API of
+ GET /credentials/{credential-id}
+
This section is non-normative.
+ ++ Participating platforms are proving actual interoperability by + enrolling in continuous integration tests. These tests are based + on Postman collections which orchestrate the interaction of + participating parties. + Please refer to the interoperability + documentation for details on how to import and run these Postman test suites. +
++ An interoperability report is continuously created from the + results of executing these collections, targeting the + participating platforms. Interchange between all combinations of + participating platforms are executed. The Interoperability report + is executed by a GitHub Action on the Traceability Interoperability GitHub repository: + interoperability-report.yml +
+
+ In each test, the GitHub Action runner carries out a number of
+ invocations, acting on behalf of varying parties taking different
+ roles (issuer, holder, and verifier), in turn invoking the
+ participating platform.
+
This section is non-normative.
+ ++ The Traceability Interoperability + Open API + Specification + is designed to be easily implemented and used to access conforming + platforms. +
++ In order to make use of the provide OpenAPI specifications + directly, several placeholder URLs need to be modified to reflect + your operating environment: +
+Add the target server:
servers:
+ - url: https://conformant-platform.example.comAdd the target tokenUrl:
components:
+ securitySchemes:
+ OAuth2:
+ type: oauth2
+ flows:
+ clientCredentials:
+ tokenUrl: https://conformant-platform.example.com/oauth/token
+ The openapi-typescript-codegen project provides
+ a means for generating typescript clients based on OpenAPI specifications.
+
# Install openapi-typescript-codegen globally
+npm install -g openapi-typescript-codegen
+
+# Produce a dereferenced openapi specification JSON file from this repo.
+npm run preserve
+
+# Generate a typescript client from the dereferenced openapi specification JSON file.
+npx openapi-typescript-codegen --input ./docs/openapi/openapi.json
+ Please refer to the openapi-typescript-codegen project page for more detailed
+ installation
+ and usage
+ instructions.
+
+ Systems complying with this specification SHOULD leverage + and comply with, and service providers complying with this + specification SHOULD be able to provide results to, the + guidance provided in + + NIST 800 53 rev 5 + (Security and Privacy Controls for Information Systems and Organizations). +
++ There are a number of security considerations that implementers + should be aware of when processing data described by this + specification. Ignoring or not understanding the implications of + this section can result in security vulnerabilities. +
+ ++ While this section attempts to highlight a broad set of security + considerations, it is not a complete list. Implementers are urged + to seek the advice of security and cryptography professionals when + implementing mission critical systems using the technology + outlined in this specification. +
+ ++ As a rule, systems conforming with this specification SHOULD + leverage and comply with encryption and security guidelines as + listed in: + FIPS 186-5 (DRAFT), + FIPS 180-4, and + FIPS 197. This + effectively means that committers should be thinking along the lines of + P256 versus other competing + algorithms. +
++ Any system conforming with this specification for + interoperability + MUST + secure credentials with Securing Verifiable Credentials using JOSE and COSE [VC-JOSE-COSE] +
++ Any system conforming with this specification for interoperability + MUST + support Bitstring Status List v1.0 [BITSTRING-STATUS-LIST] + to handle revocation and status tracking for Verifiable Credentials. +
++ Any system conforming with this specification for + interoperability + MUST utilize TLS and comply with + + NIST SP 800-52 rev2 + or superseding publications for configuration and use of TLS in + transport of data over API or web endpoints. +
++ Special care should be taken to avoid use of obsolete TLS + profiles or configurations that do not match the latest TLS + Protocol configurations. The + special + publication + provided by the NSA on this topic should be referred to as a guide for + systems administrators deploying + infrastructure intended to comply with the standard for interoperability + discussed here. +
++ Tool lists such as those compiled + here + may be helpful in identifying and mitigating issues related to TLS + misconfiguration. +
++ Portions of the work on this specification have been funded by the + United States Department of Homeland Security's (US DHS) Silicon Valley + Innovation Program under contracts 70RSAT20T00000003, 70RSAT20T00000031, + 70RSAT20T00000033, 70RSAT20T00000043, and 70RSAT20T00000044. The content + of this specification does not necessarily reflect the position or the + policy of the U.S. Government and no official endorsement should be + inferred. +
+