Fraunhofer SIT

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

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 with X.509 Certificates, alternative methods commonly used to support public key discovery and Artifact Repositories. 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 objects, identifiers and workflows necessary to interact with a SCITT Transparency Service:

• Signed Statements
• Receipts
• Transparent Statements
• Registration Policies

SCRAPI defines the operations necessary to support supply chain transparency using COSE :

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

In addition to these operational HTTP endpoints, this specification defines supporting endpoints:

• 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" and "Registration Policy" as defined in . This specification uses "payload" as defined in .

Endpoints Authentication is out of scope for this document. Implementations MAY authenticate clients, for example authorization or preventing denial of service attacks. If Authentication is not implemented, rate limiting or other denial of service mitigation MUST be implemented. All messages are sent as HTTP GET or POST requests. If the Transparency Service cannot process a client's request, it MUST return either:

1. an HTTP 3xx code, indicating to the client additional action they must take to complete the request, such as follow a redirection, or
2. an HTTP 4xx or 5xx status code, and the body SHOULD be a Concise Problem Details object containing:

• title: A human-readable string identifying the error that prevented the Transparency Service from processing the request, ideally short and suitable for inclusion in log messages.
• detail: A human-readable string describing the error in more depth, ideally with sufficient detail enabling the error to be rectified.

TODO: RESOLVE this dangling media-type application/concise-problem-details+cbor NOTE: SCRAPI is not a CoAP API. Nonetheless Constrained Problem Details objects provide a useful CBOR encoding for problem details and avoids the need for mixing CBOR and JSON in endpoint implementations. NOTE: Examples use '\' line wrapping per Examples of errors may include: { / title / -1: \ "Bad Signature Algorithm", / detail / -2: \ "Signing algorithm 'WalnutDSA' not supported" } 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 any error 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 This endpoint is used to discover the capabilities and current configuration of a transparency service implementing this specification. The Transparency Service responds with a CBOR map of configuration elements. These elements are Transparency-Service specific. Contents of bodies are informative examples only. Request: GET /.well-known/transparency-configuration HTTP/1.1 Host: transparency.example Accept: application/cbor Response: HTTP/1.1 200 Ok Content-Type: application/cbor Payload (in CBOR diagnostic notation) { "issuer": "https://transparency.example", "jwks_uri": "https://transparency.example/jwks" } Responses to this message are vendor-specific. Fields that are not understood MUST be ignored.

Register Signed Statement See notes on detached payloads below. This endpoint instructs a Transparency Service to register a Signed Statement on its log. Since log implementations may take many seconds or longer to reach finality, this API provides an asynchronous mode that returns a locator that can be used to check the registration's status asynchronously. The following is a non-normative example of an HTTP request to register a Signed Statement: Request: POST /entries HTTP/1.1 Host: transparency.example Accept: application/cbor Accept: application/cose Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) If the payload is detached, the Transparency Service depends on the client's authentication context in the Registration Policy. If the payload is attached, the Transparency Service depends on both the client's authentication context (if present) and the verification of the Signed Statement in the Registration Policy. The Registration Policy for the Transparency Service MUST be applied before any additional processing. The details of Registration Policies are out of scope for this document. Response: One of the following:

Status 201 - Registration is successful If the Transparency Service is able to produce a Receipt within a reasonable time, it MAY return it directly. Along with the receipt the Transparency Service MAY return a locator in the HTTP response Location header, provided the locator is a valid URL. HTTP/1.1 201 Created Location: https://transparency.example/entries\ /67ed41f1de6a...cfc158694ed0befe Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) The response contains the Receipt for the Signed Statement. Fresh Receipts may be requested through the resource identified in the Location header.

Status 303 - Registration is running In cases where the registration request is accepted but the Transparency Service is not able to produce a Receipt in a reasonable time, it MAY return a locator for the registration operation, as in this non-normative example: HTTP/1.1 303 See Other Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose Content-Length: 0 Retry-After: <seconds> The location MAY be temporary, and the service may not serve a relevant response at this Location after a reasonable delay. The Transparency Service MAY include a Retry-After header in the HTTP response to help with polling.

Query Registration Status This endpoint lets a client query a Transparency Service for the registration status of a payload they have submitted earlier, and for which they have received a 303 or 302 - Registration is running response. Request: GET /entries/67ed...befe HTTP/1.1 Host: transparency.example Accept: application/cbor Accept: application/cose Content-Type: application/cose Response: One of the following:

Status 302 - Registration is running Registration requests MAY fail, in which case the Location MAY return an error when queried. If the client requests (GET) the location when the registration is still in progress, the TS MAY return a 302 Found, as in this non-normative example: HTTP/1.1 302 Found Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose Content-Length: 0 Retry-After: <seconds> The location MAY be temporary, and the service may not serve a relevant response at this Location after a reasonable delay. The Transparency Service MAY include a Retry-After header in the HTTP response to help with polling.

Status 200 - Asynchronous registration is successful Along with the receipt the Transparency Service MAY return a locator in the HTTP response Location header, provided the locator is a valid URL. HTTP/1.1 200 OK Location: https://transparency.example/entries\ /67ed41f1de6a...cfc158694ed0befe Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) The response contains the Receipt for the Signed Statement. Fresh Receipts may be requested through the resource identified in the Location header. As an example, a successful asynchronous follows the following sequence: TS Client <-- 303 Location: .../entries/tmp123 --- TS May happen zero or more times: Client --- GET .../entries/tmp123 --> TS Client <-- 302 Location: .../entries/tmp123 --- TS Finally: Client --- GET .../entries/tmp123 --> TS Client <-- 200 (Transparent Statement) --- TS Location: .../entries/final123 ]]>

Status 400 - Invalid Client Request The following expected errors are defined. Implementations MAY return other errors, so long as they are valid objects. HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: \ "Bad Signature Algorithm", / detail / -2: \ "Signed Statement contained a non supported algorithm" } HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: "\ Confirmation Missing", / detail / -2: \ "Signed Statement did not contain proof of possession" } HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: \ "Payload Missing", / detail / -2: \ "Signed Statement payload must be attached \ (must be present)" } HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: \ "Payload Forbidden", / detail / -2: \ "Signed Statement payload must be detached \ (must not be present)" } HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: \ "Rejected", / detail / -2: \ "Signed Statement not accepted by the current\ Registration Policy" }

Status 400 - Invalid Client Request The following expected errors are defined. Implementations MAY return other errors, so long as they are valid objects. HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { / title / -1: "Invalid locator", / detail / -2: "Operation locator is not in a valid form" }

Status 404 - Operation Not Found If no record of the specified running operation is found, the Transparency Service returns a 404 response. HTTP/1.1 404 Not Found application/concise-problem-details+cbor { / title / -1: \ "Operation Not Found", / detail / -2: \ "No running operation was found matching the requested ID" }

Status 429 - Too Many Requests If a client is polling for an in-progress registration too frequently then the Transparency Service MAY, in addition to implementing rate limiting, return a 429 response: HTTP/1.1 429 Too Many Requests Content-Type: application/concise-problem-details+cbor Retry-After: <seconds> { / title / -1: \ "Too Many Requests", / detail / -2: \ "Only <number> requests per <period> are allowed." }

Resolve Receipt Authentication SHOULD be implemented for this endpoint. Request: GET entries/67ed41f1de6a...cfc158694ed0befe HTTP/1.1 Host: transparency.example Accept: application/cose Response:

Status 200 - OK If the Receipt is found: HTTP/1.1 200 Ok Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ])

Status 404 - Not Found If there is no Receipt found for the specified EntryID the Transparency Service returns a 404 response: HTTP/1.1 404 Not Found application/concise-problem-details+cbor { / title / -1: \ "Not Found", / detail / -2: \ "Receipt with entry ID <id> not known \ to this Transparency Service" }

Optional Endpoints The following HTTP endpoints are optional to implement.

Resolve Signed Statement This endpoint enables Transparency Service APIs to act like Artifact Repositories, and serve Signed Statements directly, instead of indirectly through Receipts. Request: GET /signed-statements/9e4f...688a HTTP/1.1 Host: transparency.example Accept: application/cose Response: One of the following:

Status 200 - Success HTTP/1.1 200 Ok Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ])

Status 404 - Not Found The following expected errors are defined. Implementations MAY return other errors, so long as they are valid objects. HTTP/1.1 404 Not Found application/concise-problem-details+cbor { / title / -1: \ "Not Found", / detail / -2: \ "No Signed Statement found with the specified ID"

Eventual Consistency For all responses additional eventually consistent operation details MAY be present. Support for eventually consistent Receipts is implementation specific, and out of scope for this specification.

Exchange Receipt This endpoint is used to exchange old or expiring Receipts for fresh ones. The iat, exp and kid claims can change each time a Receipt is exchanged. This means that fresh Receipts can have more recent issued at times, further in the future expiration times, and be signed with new signature algorithms. Request: POST /exchange/receipt HTTP/1.1 Host: transparency.example Accept: application/cose Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ])

Status 200 A new Receipt: HTTP/1.1 200 Ok Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ])

Resolve Issuer This endpoint is inspired by . 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: GET /.well-known/issuer/tenant/1234 HTTP/1.1 Host: transparency.example Accept: application/json Response: HTTP/1.1 200 Ok Content-Type: application/json { "issuer": "https://transparency.example/tenant/1234", "jwks": { "keys": [ { "kid": "urn:ietf:params:oauth\ :jwk-thumbprint:sha-256:Dgyo...agRo", "alg": "ES256", "use": "sig", "kty": "EC", "crv": "P-256", "x": "p-kZ4uOASt9IjQRTrWikGnlbGb-z3LU1ltwRjZaOS9w", "y": "ymXE1yltJPXgjQSRe9NweN3TLlSUALYZTzy83NVfdg0" }, { "kid": "urn:ietf:params:oauth\ :jwk-thumbprint:sha-256:4Fzx...0ClE", "alg": "HPKE-Base-P256-SHA256-AES128GCM", "use": "enc", "kty": "EC", "crv": "P-256", "x": "Vreuil95vzR6ixutgBBf2ota-rj97MvKfuJWB4qqp5w", "y": "NkUTeaoNlLRRsVRxHGDA-RsA0ex2tSpcd3G-4SmKXbs" } ] } }

Privacy Considerations TODO

Security Considerations

General Scope This document describes the interoperable API for client calls to, and implementations of, a Transparency Service as specified in . As such the security considerations in this section are concerned only with security considerations that are relevant at that implementation layer. All questions of security of the related COSE formats, algorithm choices, cryptographic envelopes,verifiable data structures and the like are handled elsewhere and out of scope of this document.

Applicable Environment SCITT is concerned with issues of cross-boundary supply-chain-wide data integrity and as such must assume a very wide range of deployment environments. Thus, no assumptions can be made about the security of the computing environment in which any client implementation of this specification runs.

User-host Authentication defines 2 distinct roles that require authentication: Issuers who sign Statements, and clients that submit API calls on behalf of Issuers. While Issuer authentication and signing of Statements is very important for the trustworthiness of systems implementing the SCITT building blocks, it is out of scope of this document. This document is only concerned with authentication of API clients. For those endpoints that require client authentication, Transparency Services MUST support at least one of the following options:

• HTTP Authorization header with a JWT
• domain-bound API key
• TLS client authentication

Where authentication methods rely on long term secrets, both clients and Transparency Services implementing this specification SHOULD allow for the revocation and rolling of authentication secrets.

Primary Threats

In Scope The most serious threats to implementations on Transparency Services are ones that would cause the failure of their main promises, to wit:

• Threats to strong identification, for example representing the Statements from one issuer as those of another
• Threats to payload integrity, for example changing the contents of a Signed Statement before making it transparent
• Threats to non-equivocation, for example attacks that would enable the presentation or verification of divergent proofs for the same Statement payload

Denial of Service Attacks While denial of service attacks are very hard to defend against completely, and Transparency Services are unlikely to be in the critical path of any safety-liable operation, any attack which could cause the silent failure of Signed Statement registration, for example, should be considered in scope. In principle DoS attacks are easily mitigated by the client checking that the Transparency Service has registered any submitted Signed Statement and returned a Receipt. Since verification of Receipts does not require the involvement of the Transparency Service DoS attacks are not a major issue. Clients to Transparency Services SHOULD ensure that Receipts are available for their registered Statements, either on a periodic or needs-must basis, depending on the use case. Beyond this, implementers of Transparency Services SHOULD implement general good practice around network attacks, flooding, rate limiting etc.

Eavesdropping Since the purpose of this API is to ultimately put the message payloads on a Transparency Log there is limited risk to eavesdropping. Nonetheless transparency may mean 'within a limited community' rather than 'in full public', so implementers MUST add protections against man-in-the-middle and network eavesdropping, such as TLS.

Message Modification Attacks Modification attacks are mitigated by the use of the Issuer signature on the Signed Statement.

Message Insertion Attacks Insertion attacks are mitigated by the use of the Issuer signature on the Signed Statement, therefore care must be taken in the protection of Issuer keys and credentials to avoid theft Issuer and impersonation. Transparency Services MAY also implement additional protections such as anomaly detection or rate limiting in order to mitigate the impact of any breach.

Out of Scope

Replay Attacks Replay attacks are not particularly concerning for SCITT or SCRAPI: Once a statement is made, it is intended to be immutable and non-repudiable, so making it twice should not lead to any particular issues. There could be issues at the payload level (for instance, the statement "it is raining" may true when first submitted but not when replayed), but being payload-agnostic implementations of SCITT services cannot be required to worry about that. If the semantic content of the payload are time dependent and susceptible to replay attacks in this way then timestamps MAY be added to the protected header signed by the Issuer.

Message Deletion Attacks Once registered with a Transparency Service, Registered Signed Statements cannot be deleted. Thus, any message deletion attack must occur prior to registration else it is indistinguishable from a man-in-the-middle or denial-of-service attack on this interface.

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

IANA Considerations

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 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 any Relying Parties will be able to verify them. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. 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. The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This document defines a concise "problem detail" as a way to carry machine-readable details of errors in a Representational State Transfer (REST) response to avoid the need to define new error response formats for REST APIs for constrained environments. The format is inspired by, but intended to be more concise than, the problem details for HTTP APIs defined in RFC 7807. 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 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. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content.

Contributors Transmute

United States orie@transmute.industries

Orie contributed examples, text, and URN structure to early version of this draft.