Traceability Interoperability v1.0

Abstract

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

Discovery via an organization's did:web
Cross organization OAuth2-based authentication
Structure of the https-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.

Note

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.

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:

The Verifier MUST establish the OAuth 2.0 binding by providing client ID and secret to the Holder.
The Verifier MUST provide an authentication endpoint for the Holder to authenticate and obtain an access token.
The Verifier MUST provide a presentations endpoint for the Holder to submit presentations.

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.

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:

Example 1

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:

Example 2

"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:

Example 3

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.

Example 4

{
  "@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": "https://university.example/issuers/565049#key-123",
      "type": "JsonWebKey",
      "controller": "https://university.example/issuers/565049",
      "publicKeyJwk": {
        "kty": "EC",
        "crv": "P-384",
        "alg": "ES384",
        "x": "PxgAmVYOQvSNcMYL2tOzoLwSWn4Ta3tIMPEUKR8pxeb-gmR11-DyKHBoIiY-2LhM",
        "y": "BZEBTkImVdpwvxR9THIRw16eblnj5-tZa7m-ww5uVd4kyPJNRoWUn2aT9ZuarAe-"
      }
    }
  ],
  "service": [
    {
      "id": "did:web:platform.example:organization:123#traceability-api",
      "type": ["TraceabilityAPI"],
      "serviceEndpoint": "https://platform.example/organization/123"
    }
  ]
}

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, in that they present an area where various attacks could be made by sending data with identifiers already in use with malicious intent to confuse a receiver of the data.

Identifiers conformant with this specification 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. 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.

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:

Example 5

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

Add the target tokenUrl:

Example 6

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

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 Digital Signature Standard (DSS), FIPS 180-4 Secure Hash Standard (SHS), and FIPS 197 Advanced Encryption Standard (AES). 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.

Traceability Interoperability v1.0

Abstract

Status of This Document

1. Conformance

2. Introduction

3. Mandatory Algorithms

4. Terminology

5. Conformance

6. Use Cases and Requirements

6.1 Initial Party Binding

6.2 Identifier Discovery

6.2.1 Integration Considerations

6.2.2 Discovering Organizational Identifiers

service

assertionMethod

verificationMethod

7. Authentication

7.1 Presentation Authentication

8. Services

9. Rules for Processing Data

9.1 Identifiers

9.2 Presentations

9.3 Credentials

10. OAS Implementation

11. Privacy Considerations

12. Security Considerations

12.1 General Guidelines

12.2 Credential Securing Mechanism

12.3 Encryption in Transport

A. Appendix

A.1 Acknowledgements

B. References

B.1 Normative references

B.2 Informative references