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 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)

Introduction

This specification describes how verifiable data can be shared securely over an authenticated channel. Specifically, a set of OpenAPI HTTP endpoints is defined, allowing authenticated data senders and receivers to exchange Verifiable Presentations.

The Open API Specification section covers each operation and provides example inputs and expected responses.

CCG Standards Stack

standards-stack

The above diagram illustrates how traceability-interop fits into the larger family of W3C CCG standards.

Terminology

Term definitions for this specification can be found in the Traceability Vocabulary document. This specification does not define any additional terms.

Rules for Processing Data

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

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

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.

Some discussion and explicit clarification of use of `issuer` SHOULD be added to the spec text to clarify best practices for retrieval and ownership of data

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.

Credentials

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 specification needs to specify precise usage of id for members of credentials as well, in the furtherance or reuse of data already defined elsewhere with a defined id, e.g., an address, or other commonly repeated object

Interoperability Testing

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, such as `Credential Issuance`, `Credential Verification`, and `Presentation Exchange`. Please refer to the interoperability and conformance 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. In cases of multi-party interactions (such as party A making a verifiable presentation to party B), all combinations of platform interchange 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.

Below is an example of calls made by the runner as it is executing a DIDAuth Presentation Exchange flow:

OAS Implementation

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
    

Code Generation

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.

Privacy Considerations

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).

Security Considerations

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.

General Guidelines

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.

Data Integrity Proof Suites

Any system conforming with this specification for interoperability MUST secure credentials and presentations with JSON Object Signing and Encryption (JOSE) or CBOR Object Signing and Encryption (COSE)

There needs to be some discussion to clarify and finalize a list of signature suites and signing mechanisms.

Any system conforming with this specification for interoperability MUST support Status List 2021 to handle revocation and status tracking for Verifiable Credentials.

Encryption in Transport

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.

Encryption at Rest

Any system conforming with this specification for interoperability MUST deploy their infrastructure in compliance with NIST SP 800-53 rev5.1 SC-28 or superseding publications.

Key Management

Key management MUST conform to NIST SP 800-57 or superseding publication.

Threat Model

See NSA/CSS Technical Cyber Threat Framework v2. We are developing a down-scoped threat model for the purpose of evaluating presentation exchange over HTTPS.

Software Supply Chain

As this specification deals with the implementation of software that relates directly to the traceability of physical real world objects in the supply chain, implementations of software conformant with this specification SHOULD be treated as Critical Software and as such SHOULD follow all guidelines related to the protection of Software Supply Chains.

Solutions implementing this specification SHOULD seek conformance with NIST 800-161 Rev. 1 or superseding documents.

Solutions implementing this specification SHOULD seek conformance with NIST 800-218 or superseding documents.

The Guidelines on Minimum Standards for Developer Verification of Software - NISTIR 8397 MUST be followed by developers implementing solutions intended to be conformant with this specification.

NB: this guidance applies to sections beyond Software Supply Chain issues, and many of the topics covered have discrete sections in this specification or supplemental aids such as the interoperability test suite provided in the repository for this specification.

Disaster Recovery

Industry best practices related to disaster recovery SHOULD be followed by implementations compliant with this specification, at a minimum, guidance from the whitepapers and specifications listed below SHOULD be used.

NB: the list below links out to multiple NIST and other standards, many of which are referenced directly in this specification. Each should be carefully considered and reviewed, even if not linked to directly from this specification.

Accessibility Considerations

There are a number of accessibility considerations implementers should be aware of when processing data described in this specification. As with any web standard or protocol implementation, ignoring accessibility issues makes this information unusable by a large subset of the population. It is important to follow accessibility guidelines and standards, such as [[WCAG21]], to ensure that all people, regardless of ability, can make use of this data. This is especially important when establishing systems utilizing cryptography, which have historically created problems for assistive technologies.

This section details the general accessibility considerations to take into account when utilizing this data model.

Internationalization Considerations

There are a number of internationalization considerations implementers should be aware of when publishing data described in this specification. As with any web standards or protocols implementation, ignoring internationalization makes it difficult for data to be produced and consumed across a disparate set of languages and societies, which would limit the applicability of the specification and significantly diminish its value as a standard.

This section outlines general internationalization considerations to take into account when utilizing this data model.

Ethical and General Design Considerations

The W3C Group Note on Web Platform Design Principles serves well as general guidance for contributions to this specification, as well as for developers implementing a solution that is in compliance with or that interacts with solutions implementing this specification.

In general, when implementing any solution on the web, the developer should have a strong concern that their solution is implemented in an ethical manner that showcases the appropriate and ethical use of technology. Any such solution should provide a net positive social benefit, and be cognizant of the variety of principles that must be balanced when building and deploying a solution. The W3C TAG document on Ethical Web Principles provides a strong enumeration of these principles and considerations for how to best implement a solution with those principles in mind.

Appendix

Acknowledgements

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.