From 78e249271397ee49b9ded6e52bbd4b603872f800 Mon Sep 17 00:00:00 2001 From: Nis Jespersen Date: Thu, 10 Oct 2024 16:17:33 +0200 Subject: [PATCH] feat: cgfr file --- CGFR/2024-10-10/index.html | 1365 ++++++++++++++++++++++++++++++++++++ docs/spec/index.html | 3 + 2 files changed, 1368 insertions(+) create mode 100644 CGFR/2024-10-10/index.html diff --git a/CGFR/2024-10-10/index.html b/CGFR/2024-10-10/index.html new file mode 100644 index 000000000..08560ee73 --- /dev/null +++ b/CGFR/2024-10-10/index.html @@ -0,0 +1,1365 @@ + + + + + + + +Traceability Interoperability v0.0 + + + + + + + + + + + + + + + + + + + + + + + +
+ +

Traceability Interoperability v0.0

+

Unofficial Draft

+
+ More details about this document +
+ +
Latest published version:
+ https://www.w3.org/traceability-interop/ +
+
Latest editor's draft:
https://w3id.org/traceability/interoperability
+
History:
+ Commit history +
+ + + + + +
Editors:
+ Michael Prorock (Mesur.io), E-mail +
+ Mahmoud Alkhraishi (Mavennet), E-mail +
+ Nis Jespersen (Transmute), E-mail +
+
+ Former editor: +
+ Orie Steele (Transmute), E-mail +
+
Authors:
+ Chris Abernethy (mesur.io) +
+ Russell Hofvendahl (mesur.io) +
+ Ted Thibodeau Jr (OpenLink Software, Inc) +
+ Vivien Fan (Mavennet Systems Inc) +
+
Feedback:
+ GitHub w3c-ccg/traceability-interop + (pull requests, + new issue, + open issues) +
+ + +
+
+ + +

+ Copyright © + 2024 + the document editors/authors. + Text is available under the + Creative Commons Attribution 4.0 International Public License; additional terms may apply. +

+
+
+ +

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

+
+ + +

Status of This Document

+ This document is a draft of a potential specification. It has no official + standing of any kind and does not represent the support or consensus of + any standards organization. +

+

Status

+

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

+
+ +

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

+ The key words MAY, MUST, MUST NOT, and SHOULD in this document + are to be interpreted as described in + BCP 14 + [RFC2119] [RFC8174] + when, and only when, they appear in all capitals, as shown here. +

+

1.1

+
+ +

2. Introduction

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

+

+

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

+ +
+ +

3. Mandatory Algorithms

+ +

+ The following digital signature algorithms + MUST be implemented by conforming issuers and verifiers. +

+ +
+ + +

4. Terminology

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

+
+ + +

5. Use Cases and Requirements

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

+ + +

5.1 Initial Party Binding

+ +

+ 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 obtains an access token. +
    • +
  • + The Verifier MUST provide an + 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. +

+
+ + +

5.2 Identifier Discovery

+ + +

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

+ +

+The current APIs exploit the well known DID configuration, +which has some limitations, most notably regarding multi-tenant platforms. +

+ +

5.2.1 Integration Considerations

+ +

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

+ +
+ + +

5.2.2 Discovering Organizational Identifiers

+ + +

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

+
service
+ + + +

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

+ +
+ +
assertionMethod
+ +

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

+ +
+ +
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": "did:web:platform.example:organization:123#key1",
+          "type": "JsonWebKey2020",
+          "controller": "did:web:platform.example:organization:123",
+          "publicKeyJwk": {
+              "kty": "OKP",
+              "crv": "Ed25519",
+              "x": "rfsiofZ3RcuMWZSoYbvNEZ_8oxeep8uapJDyT0ku8EM"
+          }
+      }
+  ],
+  "service": [
+    {
+      "id": "did:web:platform.example:organization:123#traceability-api",
+      "type": ["TraceabilityAPI"],
+      "serviceEndpoint": "https://platform.example/organization/123"
+    }
+  ]
+}
+
+ +
+
+ +
+
+ + +

6. Authentication

+ +

Implementations MUST support OAuth 2.0 Client Credentials based authentication.

+ +

+ Client Credentials Grant is appropriate for verifying trusted application authorization for Internal/External APIs. +

+ +

See these links for more information on Machine to Machine API authorization:

+ + + +

6.1 Presentation Authentication

+ +

+ The following sequence of events is necessary for a Holder to present data to a Verifier: +

+
    +
  • + The Holder MUST authenticate by obtaining an + access token through the client + credentials flow, based on the client ID and client secret provided by the Verifier. +
    • +
  • + Subsequent + presentations MUST be made with the access token in the request header. +
    • +
+
+ +
+ + + +

7. Services

+ +

+ This section describes the HTTP services a conformant Traceability API MUST + implement. +

+ +

See the Open API for Interoperable Traceability for the full API definition.

+
+ + +

8. 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. +

+

8.1 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. +

+

8.1.1 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. +

+
+

8.1.2 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} +

+
+
+
+ +

9. Interoperability Testing

This section is non-normative.

+ +

+ 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. + Please refer to the interoperability + 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. Interchange between all combinations of + participating platforms 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. +

+
+ +

10. OAS Implementation

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

10.1 Code Generation

+

+ The openapi-typescript-codegen project provides + a means for generating typescript clients based on OpenAPI specifications. +

+
+
+ Example 7 + 
# 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. +

+
+ +

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

+
+ +

12. 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. +

+ +

12.1 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. +

+
+ +

12.2 Credential Securing Mechanism

+ +

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

+
+ +

12.3 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. +

+
+ +
+ +

A. Appendix

+ +

A.1 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. +

+
+
+ + + +

B. References

B.1 Normative references

+ +
[BITSTRING-STATUS-LIST]
+ Bitstring Status List v1.0. URL: https://www.w3.org/TR/vc-bitstring-status-list/ +
[did-core]
+ Decentralized Identifiers (DIDs) v1.0. Manu Sporny; Amy Guy; Markus Sabadello; Drummond Reed. W3C. 19 July 2022. W3C Recommendation. URL: https://www.w3.org/TR/did-core/ +
[RFC2119]
+ Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119 +
[rfc3986]
+ Uniform Resource Identifier (URI): Generic Syntax. T. Berners-Lee; R. Fielding; L. Masinter. IETF. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986 +
[rfc4122]
+ A Universally Unique IDentifier (UUID) URN Namespace. P. Leach; M. Mealling; R. Salz. IETF. July 2005. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc4122 +
[RFC7518]
+ JSON Web Algorithms (JWA). M. Jones. IETF. May 2015. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc7518 +
[RFC8174]
+ Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174 +
[rfc9110]
+ HTTP Semantics. R. Fielding, Ed.; M. Nottingham, Ed.; J. Reschke, Ed.. IETF. June 2022. Internet Standard. URL: https://httpwg.org/specs/rfc9110.html +
[URL]
+ URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/ +
[VC-DATA-MODEL]
+ W3C Verifiable Credentials Data Model v2.0. URL: https://www.w3.org/TR/2024/CR-vc-data-model-2.0-20240201/ +
[VC-JOSE-COSE]
+ Securing Verifiable Credentials using JOSE and COSE. URL: https://w3c.github.io/vc-jose-cose/ +
+

B.2 Informative references

+ +
[TRACE-VOCAB]
+ Traceability Vocabulary. URL: https://w3c-ccg.github.io/traceability-vocab/ +
+
\ No newline at end of file diff --git a/docs/spec/index.html b/docs/spec/index.html index ebdd91906..ef7d34375 100644 --- a/docs/spec/index.html +++ b/docs/spec/index.html @@ -259,6 +259,9 @@

+
+
+

Introduction