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 provided 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 contribue 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.

In this interaction-model, the presenting party initiates an interaction, notifying the receiver. The presentation receiver responds to the presentation intention with cryptographic material for completing the presentation. This is used by the presenter for proving the Verifiable Presentation, which finally passed to the receiver.

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.

Workflows

Workflows enable presenters to correlate individual presentations. A workflow definition can be used to indicate that presentations relate to the same type of workflow.

Workflow instances indicate that separate individual presentations are part of the very same workflow.

Workflows for US Customs and Border Protection (US CBP)

workflow-def-ex

In the above example, two separate 7501 Entry Summaries are submitted to US CBP at different points in time, and related to different imports. By specifying the same workflow definition, it is made clear to US CBP that both relate to the same type of import workflows.

workflow-inst-ex

The majority of data elements in a "10+2" Importer Security Filing must be presented to CBP no later than 24 hours before vessel loading, and the remaining data elements no later than 24 hours before arrival. Specifying the same workflow instance indicates to US CBP that the two presentations are part of the same import workflow.

A workflow definition indended for use with US CBP imports MUST have a corresponding plain text manifest document that may be uniquely identified, referenced, and retrieved by a third party in a publicly accessible and documented manner by the UUID of the workflow definition.

This workflow manifest document MUST list each required credential from the Traceability Vocabulary , one per line, and identified by the "type" of credential, for the workflow to be considered "complete". Completeness in this sense refers to an optimal state where all possible information that can be provided in relation to that workflow definition is present.

Following the credential "type" a space, followed by a numeric value that ranges from 0 to 1 MAY be added. If this value is not provided a value of 1 MUST by inferred by any system using this property. This numeric value MUST be referred to as "weight", and may be utilized to calculate a weighted average indicating the completeness of a particular workflow instance.

The standard calculation for weighted averages and algorithm for calculating this weighted average indicating the completeness of available information should be described, along with examples.

Stakeholders at US CBP should be consulted to determine if this weighted average SHOULD, MUST, or MAY be included with each traceable presentation.

Terminology

See terms as defined in the Traceability Vocabulary document.

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; for example, `Credential Issuance`, `Credential Verification`, and `Presentation Exchange`. These Postman collections are described with a set of tutorials that show how to run the tests against a particular implementation.

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: https://github.com/w3c-ccg/traceability-interop/actions/workflows/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. The following OAS modifications are required:

Add the target tokenUrl:

        components:
          securitySchemes:
            OAuth2:
              type: oauth2
              flows:
                clientCredentials:
                  tokenUrl: https://conformant-platform.example.com/oauth/token
        

Add the target server:

          servers:
            - url: https://conformant-platform.example.com
        

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 SHA-256, Ed25519, and Rijndael versus other competing algorithms.

Linked Data Signature Suites

Any system conforming with this specification for interoperability MUST utilize Linked Data Signatures for JWS or superceding version if it is standardized as a part of the VC Working Group for signing Linked Data in usage with Verifiable Credentials.

Any system conforming with this specification for interoperability MUST support Revocation List 2020 to handle revocation of Verifiable credentials.

As later approaches to revocation stabilize, a successor approach is expected to replace Revocation List 2020, assuming future standardization of a replacement approach at a future date.

Encryption in Transport

Any system conforming with this specification for interoperability MUST utilize TLS and comply with NIST SP 800-52 rev2 or superceding 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 superceding publications.

Key Management

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

Selective Disclosure from Credentials

All current approaches to selective disclosure are active works in progress with notable security or other considerations. These are actively being tracked in Issue #39. Selective Disclosure using any mechanism SHOULD NOT be used for production data at this time until further testing and security analysis has been performed. Selective Disclosure mechanisms MAY be used for testing and validation purposes.

Selective disclosure of certain values from signed credentials is a highly desireable feature that is actively being worked towards. At the moment, two general approaches exist for this particular feature:

BBS+

BBS+ approaches to signatures for use with selective disclosure rely on pairing friendly curves, specifically BLS12-381 in the current specifications.

BBS+ Signatures 2020 MUST NOT be used due to issues related to one or more blank nodes as well as sensitivity around the ordering of a signed message. See issue #62 for more details.

The BBS+ Signature Scheme specification is consolidating work towards an updated version of BBS+ signatures that aim to resolve prior issues.

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 superceding documents.

Solutions implementing this specification SHOULD seek conformance with NIST 800-218 or superceding 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 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, specifically at a minimum guidance from the following whitepapers and specifications SHOULD be used:

NB: the above list links out to multiple NIST and other standards, many of which are referenced directly in this specification, but each of which 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 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 should be utilized 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.