]> Fraunhofer SIT

Rheinstrasse 75 Darmstadt 64295 Germany henk.birkholz@sit.fraunhofer.de

Transmute

orie@transmute.industries

DataTrails Inc.

United States jon.geater@datatrails.ai

Security SCITT Internet-Draft This document describes a REST API that supports the normative requirements of the SCITT Architecture . Optional key discovery and query interfaces are provided to support interoperability issues with Decentralized Identifiers, X509 Certificates and Artifact Reposistories. About This Document Status information for this document may be found at . Discussion of this document takes place on the SCITT Working Group mailing list (), which is archived at . Subscribe at . Source for this draft and an issue tracker can be found at .

Introduction The SCITT Architecture defines the core operations necessary to support supply chain transparency using COSE (CBOR Object Signing and Encryption).

• Issuance of Signed Statements
• Verification of Signed Statements
• Registration of Signed Statements
• Issuance of Receipts
• Verification of Receipts
• Production of Transparent Statements
• Verification of Transparent Statements

In addition to defining concrete HTTP endpoints for these operations, this specification defines support for the following endpoints which support these operations:

• Resolving Verification Keys for Issuers
• Retrieving Receipts Asynchronously
• Retrieving Signed Statements from an Artifact Repository
• Retrieving Statements from an Artifact Repository

Terminology The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 when, and only when, they appear in all capitals, as shown here. This specification uses the terms "Signed Statement", "Receipt", "Transparent Statement", "Artifact Repositories", "Transparency Service", "Append-Only Log" and "Registration Policy" as defined in . This specification uses "payload" as defined in .

Endpoints Authentication is out of scope for this document. If Authentication is not implemented, rate limiting or other denial of service mititations MUST be applied to enable anonymous access. NOTE: '' line wrapping per RFC 8792 in HTTP examples. All messages are sent as HTTP GET or POST requests. If the Transparency Service cannot process a client's request, it MUST return an HTTP 4xx or 5xx status code, and the body SHOULD be a JSON problem details object () containing:

• type: A URI reference identifying the problem. To facilitate automated response to errors, this document defines a set of standard tokens for use in the type field within the URN namespace of: "urn:ietf:params:scitt:error:".
• detail: A human-readable string describing the error that prevented the Transparency Service from processing the request, ideally with sufficient detail to enable the error to be rectified.

Error responses SHOULD be sent with the Content-Type: application/problem+json HTTP header. As an example, submitting a Signed Statement with an unsupported signature algorithm would return a 400 Bad Request status code and the following body: Most error types are specific to the type of request and are defined in the respective subsections below. The one exception is the "malformed" error type, which indicates that the Transparency Service could not parse the client's request because it did not comply with this document:

• Error code: malformed (The request could not be parsed).

Clients SHOULD treat 500 and 503 HTTP status code responses as transient failures and MAY retry the same request without modification at a later date. Note that in the case of a 503 response, the Transparency Service MAY include a Retry-After header field per in order to request a minimum time for the client to wait before retrying the request. In the absence of this header field, this document does not specify a minimum.

Mandatory The following HTTP endpoints are mandatory to implement to enable conformance to this specification.

Transparency Configuration Authentication SHOULD NOT be implemented for this endpoint. This endpoint is used to discovery the capabilites of a transparency service implementing this specification. Request: Response: Additional fields may be present. Fields that are not understood MUST be ignored.

Signed Statement Registration Authentication MUST be implemented for this endpoint. The following is a non-normative example of a HTTP request to register a Signed Statement: Request: The Registration Policy for the Transparency Service MUST be applied to the payload bytes, before any additional processing is performed. If the payload is detached, the Transparency Service depends on the authentication context of the client in the Registration Policy. If the payload is attached, the Transparency Service depends on both the authentication context of the client, and the verification of the Signed Statement in the Registration Policy. The details of Registration Policy are out of scope for this document. If registration succeeds the following identifier MAY be used to refer to the Signed Statement that was accepted: urn:ietf:params:scitt:signed-statement:sha-256:base64url:5i6UeRzg1...qnGmr1o If the payload was attached, or otherwise communicated to the Transparency Service, the following identifier MAY be used to refer to the payload of the Signed Statement: urn:ietf:params:scitt:statement:sha-256:base64url:5i6UeRzg1...qnGmr1o Response: One of the following:

Status 201 - Registration is successful The response contains the Receipt for the Signed Statement. Fresh receipts may be requested through the resource identified in the Location header.

Status 202 - Registration is running { "receipt": "urn:ietf:params:scitt:receipt\ :sha-256:base64url:5i6UeRzg1...qnGmr1o", } ]]> The response contains a reference to the receipt which will eventually be available for the Signed Statement. If 202 is returned, then clients should wait until Registration succeeded or failed by polling the receipt endpoint using the receipt identifier returned in the response.

Status 400 - Invalid Client Request One of the following errors: TODO: other error codes

Optional Endpoints The following HTTP endpoints are optional to implement.

Issue Statement Authentication MUST be implemented for this endpoint. This endpoint enables a Transparency Service to be an issuer of Signed Statements on behalf of authenticated clients. This supports cases where a client lacks the ability to perform complex cryptographic operations, but can be authenticated and report statements and measurements. Request: Response:

Resolve Statement Authentication SHOULD be implemented for this endpoint. This endpoint enables Transparency Service APIs to act like Artifact Repositories, and serve payload values directly, instead of indirectly through Receipts. Request: Response:

Resolve Signed Statement Authentication SHOULD be implemented for this endpoint. This endpoint enables Transparency Service APIs to act like Artifact Repositories, and serve Signed Statements directly, instead of indirectly through Receipts. Request: Response:

Resolve Receipt Authentication SHOULD be implemented for this endpoint. Request: Response: If the Signed Statement requested is already included in the Append-Only Log: If the Signed Statement requested is not yet included in the Append-Only Log: { "receipt": "urn:ietf:params:scitt:receipt\ :sha-256:base64url:5i6UeRzg1...qnGmr1o", } ]]> Additional eventually consistent operation details MAY be present. Support for eventually consistent Receipts is implementation specific, and out of scope for this specification.

Resolve Issuer This endpoint is inspired by . Authentication SHOULD NOT be implemented for this endpoint. This endpoint is used to discover verification keys, which is the reason that authentication is not required. The following is a non-normative example of a HTTP request for the Issuer Metadata configuration when iss is set to https://transparency.example/tenant/1234: Request: Response:

Request Nonce This endpoint in inspired by . Authentication SHOULD NOT be implemented for this endpoint. This endpoint is used to demonstrate proof of posession, which is the reason that authentication is not required. Client holding signed statements that require demonstrating proof of possession MUST use this endpoint to obtain a nonce. Request: Response:

Resolve Issuer DID This endpoint enables the use of the DID Web Decentralized Identifier Method, as an alternative expression of the Issuer Metadata endpoint. This endpoint is DEPRECATED. The following is a non-normative example of a HTTP request for the Issuer Metadata configuration when iss is set to did:web:transparency.example:tenant:1234: Request: Response:

Privacy Considerations TODO

Security Considerations TODO TODO: Consider negotiation for receipt as "JSON" or "YAML". TODO: Consider impact of media type on "Data URIs" and QR Codes.

IANA Considerations

URN Sub-namespace for SCITT (urn:ietf:params:scitt) IANA is requested to register the URN sub-namespace urn:ietf:params:scitt in the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" Registry , following the template in :

Well-Known URI for Issuers The following value is requested to be registered in the "Well-Known URIs" registry (using the template from ): URI suffix: issuer Change controller: IETF Specification document(s): RFCthis. Related information: N/A

Well-Known URI for Transparency Configuration The following value is requested to be registered in the "Well-Known URIs" registry (using the template from ): URI suffix: transparency-configuration Change controller: IETF Specification document(s): RFCthis. Related information: N/A TODO: Register them from here.

Media Type Registration This section requests registration of the "application/scitt.receipt+cose" media type in the "Media Types" registry in the manner described in . To indicate that the content is a SCITT Receipt:

• Type name: application
• Subtype name: scitt.receipt+cose
• Required parameters: n/a
• Optional parameters: n/a
• Encoding considerations: TODO
• Security considerations: TODO
• Interoperability considerations: n/a
• Published specification: this specification
• Applications that use this media type: TBD
• Fragment identifier considerations: n/a
• Additional information:
  • Magic number(s): n/a
  • File extension(s): n/a
  • Macintosh file type code(s): n/a
• Person & email address to contact for further information: TODO
• Intended usage: COMMON
• Restrictions on usage: none
• Author: TODO
• Change Controller: IESG
• Provisional registration? No

References Normative References Concise Binary Object Representation (CBOR) is a data format designed for small code size and small message size. There is a need to be able to define basic security services for this data format. This document defines the CBOR Object Signing and Encryption (COSE) protocol. This specification describes how to create and process signatures, message authentication codes, and encryption using CBOR for serialization. This specification additionally describes how to represent cryptographic keys using CBOR. This document, along with RFC 9053, obsoletes RFC 8152. This document defines a "problem detail" as a way to carry machine- readable details of errors in a HTTP response to avoid the need to define new error response formats for HTTP APIs. The Hypertext Transfer Protocol (HTTP) is a stateless \%application- level protocol for distributed, collaborative, hypertext information systems. This document defines the semantics of HTTP/1.1 messages, as expressed by request methods, request header fields, response status codes, and response header fields, along with the payload of messages (metadata and body content) and mechanisms for content negotiation. This document describes a new sub-delegation for the 'ietf' URN namespace for registered protocol items. The 'ietf' URN namespace is defined in RFC 2648 as a root for persistent URIs that refer to IETF- defined resources. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. [STANDARDS-TRACK] IANA Fraunhofer SIT Microsoft Research Microsoft Research ARM DataTrails Traceability of physical and digital Artifacts in supply chains is a long-standing, but increasingly serious security concern. The rise in popularity of verifiable data structures as a mechanism to make actors more accountable for breaching their compliance promises has found some successful applications to specific use cases (such as the supply chain for digital certificates), but lacks a generic and scalable architecture that can address a wider range of use cases. This document defines a generic, interoperable and scalable architecture to enable transparency across any supply chain with minimum adoption barriers. It provides flexibility, enabling interoperability across different implementations of Transparency Services with various auditing and compliance requirements. Issuers can register their Signed Statements on any Transparency Service, with the guarantee that all Consumers will be able to verify them. In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. Informative References Independent Transmute This document defines the Nonce Endpoint for OAuth 2.0 implementations [RFC6749]. It details how an Authorization Server generates and issues opaque Nonces and how a client can learn about this endpoint to obtain a Nonce generated by the Authorization Server. MATTR Authlete Inc. Ping Identity This specification describes data formats as well as validation and processing rules to express Verifiable Credentials with JSON payloads with and without selective disclosure based on the SD-JWT [I-D.ietf-oauth-selective-disclosure-jwt] format. This second document defines the general structure of the MIME media typing system and defines an initial set of media types. [STANDARDS-TRACK] This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice.