Traceability Interoperability v0.0

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:

MAJOR - significant changes rolled forward from the previous major version. Major versions MAY include breaking or non-backwards compatible changes
MINOR - backwards compatible changes that may introduce new functionality or extensions of objects
PATCH - minor changes that are backwards compatible and resolve discovered issues or bugs

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

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

At the Business layer, supply chain actors are exchanging data in support of exchanged goods and services.
The Trust layer is supported by actors signing and verifying data as Verifiable Credentials.
The Process layer defines standardized APIs for exchanging Verifiable Credentials (VC-API) and Verifiable Presentations (trace-interop).
Linked Data establishes a concise semantic context of the data exchanged, enabled with JSON-LD by the [[[TRACE-VOCAB]]] [[TRACE-VOCAB]].
Semantics are defined in a multitude of established vocabularies and come in many forms, from narrowly-specialized, industry-vertical vocabularies, to broadly-applicable, generic vocabularies.

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.

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}`

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 documentation for details on how to import and run these Postman test suites.

A conformance test suite is provided as a guideline to implementers, aiding development efforts. Conformance tests do not address matters of interoperability.

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:

Runner calls `/credentials/issue` on Party A's platform, representing Party A acting as `issuer`.
Runner calls `/credentials/verify` on Party B's platform, representing Party B acting as `verifier`.

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.

Credential Securing Mechanism

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.

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.