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]`
Version Definitions:As a rule, versioning will follow the specification outlined in the Semantic Versioning 2.0 spec.
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)
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 endpointThe 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.
Though this specification began as a fork of the VC-API specification, it has diverged significantly. Knowledge and understanding of the VC-API specification is not necessary for implementers of this specification.
Term definitions for this specification can be found in the [[[TRACE-VOCAB]]] [[TRACE-VOCAB]]. This specification does not define any additional terms.
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}`
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.com
Add the target tokenUrl:
components:
securitySchemes:
OAuth2:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://conformant-platform.example.com/oauth/token
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 [[[VC-JOSE-COSE]]] [[VC-JOSE-COSE]]
Any system conforming with this specification for interoperability MUST support [[[BITSTRING-STATUS-LIST]]] [[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.