Supply Chain Integrity, Transparency, and Trust (SCITT) Reference APIs
draft-ietf-scitt-scrapi-11

SCITT                                                        H. Birkholz
Internet-Draft                                            Fraunhofer SIT
Intended status: Standards Track                               J. Geater
Expires: 28 December 2026                       Bowball Technologies Ltd
                                                      A. Delignat-Lavaud
                                                      Microsoft Research
                                                            26 June 2026

 Supply Chain Integrity, Transparency, and Trust (SCITT) Reference APIs
                       draft-ietf-scitt-scrapi-11

Abstract

   This document specifies a REST API with the HTTP resources, request
   and response messages, and error handling needed for an interoperable
   implementation of a SCITT Transparency Service, as defined by the
   Supply Chain Integrity, Transparency, and Trust (SCITT) Architecture.

About This Document

   This note is to be removed before publishing as an RFC.

   Status information for this document may be found at
   https://datatracker.ietf.org/doc/draft-ietf-scitt-scrapi/.

   Discussion of this document takes place on the SCITT Working Group
   mailing list (mailto:scitt@ietf.org), which is archived at
   https://mailarchive.ietf.org/arch/browse/scitt/.  Subscribe at
   https://www.ietf.org/mailman/listinfo/scitt/.

   Source for this draft and an issue tracker can be found at
   https://github.com/ietf-wg-scitt/draft-ietf-scitt-scrapi.

Status of This Memo

   This Internet-Draft is submitted in full conformance with the
   provisions of BCP 78 and BCP 79.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF).  Note that other groups may also distribute
   working documents as Internet-Drafts.  The list of current Internet-
   Drafts is at https://datatracker.ietf.org/drafts/current/.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

Birkholz, et al.        Expires 28 December 2026                [Page 1]
Internet-Draft                   SCRAPI                        June 2026

   This Internet-Draft will expire on 28 December 2026.

Copyright Notice

   Copyright (c) 2026 IETF Trust and the persons identified as the
   document authors.  All rights reserved.

   This document is subject to BCP 78 and the IETF Trust's Legal
   Provisions Relating to IETF Documents (https://trustee.ietf.org/
   license-info) in effect on the date of publication of this document.
   Please review these documents carefully, as they describe your rights
   and restrictions with respect to this document.  Code Components
   extracted from this document must include Revised BSD License text as
   described in Section 4.e of the Trust Legal Provisions and are
   provided without warranty as described in the Revised BSD License.

Table of Contents

   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
     1.1.  Scope and Relation to the SCITT Architecture  . . . . . .   3
     1.2.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Resources . . . . . . . . . . . . . . . . . . . . . . . . . .   5
     2.1.  Transparency Service Keys . . . . . . . . . . . . . . . .   6
     2.2.  Individual Transparency Service Key . . . . . . . . . . .   8
     2.3.  Register Signed Statement . . . . . . . . . . . . . . . .  10
       2.3.1.  Status 201 - Registration is successful . . . . . . .  12
       2.3.2.  Status 202 - Registration is running  . . . . . . . .  13
       2.3.3.  Status 400 - Invalid Client Request . . . . . . . . .  13
       2.3.4.  Status 429 - Too Many Requests  . . . . . . . . . . .  15
     2.4.  Resolve Receipt . . . . . . . . . . . . . . . . . . . . .  15
       2.4.1.  Status 200 - OK . . . . . . . . . . . . . . . . . . .  16
       2.4.2.  Status 204 - Registration is running  . . . . . . . .  16
       2.4.3.  Status 404 - Not Found  . . . . . . . . . . . . . . .  17
   3.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  18
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  18
     4.1.  General Scope . . . . . . . . . . . . . . . . . . . . . .  18
     4.2.  Applicable Environment  . . . . . . . . . . . . . . . . .  18
     4.3.  Authentication  . . . . . . . . . . . . . . . . . . . . .  18
     4.4.  Threat Model  . . . . . . . . . . . . . . . . . . . . . .  19
       4.4.1.  In Scope  . . . . . . . . . . . . . . . . . . . . . .  19
       4.4.2.  Out of Scope  . . . . . . . . . . . . . . . . . . . .  20
   5.  Operational Considerations  . . . . . . . . . . . . . . . . .  21
     5.1.  Client Retry Behavior . . . . . . . . . . . . . . . . . .  21
     5.2.  Server-Side Retry Configuration . . . . . . . . . . . . .  22
     5.3.  Rate Limiting . . . . . . . . . . . . . . . . . . . . . .  22
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  22
     6.1.  Well-Known URI for Key Discovery  . . . . . . . . . . . .  22
       6.1.1.  Registration Template . . . . . . . . . . . . . . . .  22

Birkholz, et al.        Expires 28 December 2026                [Page 2]
Internet-Draft                   SCRAPI                        June 2026

   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  22
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  23
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  24
   Contributors  . . . . . . . . . . . . . . . . . . . . . . . . . .  25
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  26

1.  Introduction

   The Supply Chain Integrity, Transparency, and Trust (SCITT)
   Architecture [I-D.draft-ietf-scitt-architecture] defines the core
   objects, identifiers and workflows necessary to interact with a SCITT
   Transparency Service:

   *  Signed Statements

   *  Receipts

   *  Transparent Statements

   *  Registration Policies

   SCITT Reference APIs (SCRAPI) defines HTTP resources for a
   Transparency Service using COSE ([RFC9052]).

1.1.  Scope and Relation to the SCITT Architecture

   The SCITT Architecture [I-D.draft-ietf-scitt-architecture] specifies
   the conceptual roles, message structures, and workflows of a
   Transparency Service, but does not define a concrete protocol by
   which clients interact with that service.  This document specifies
   one such concrete protocol: an HTTP-based REST API that realizes
   those interactions in an interoperable way.  References in this
   specification to "normative requirements of the SCITT Architecture"
   are to the requirements expressed using BCP 14 keywords [RFC2119]
   [RFC8174] in [I-D.draft-ietf-scitt-architecture] that pertain to the
   externally observable behavior of a Transparency Service, such as the
   registration of Signed Statements, the issuance and validation of
   Receipts, and the publication of the keys used to verify Receipts.

   In particular, this document defines HTTP resources that satisfy the
   requirements in the following sections of
   [I-D.draft-ietf-scitt-architecture]:

   *  Registration of Signed Statements (Section 6.3 of
      [I-D.draft-ietf-scitt-architecture]), realized by the Signed
      Statement registration resources defined in Section 2.3 and
      Section 2.4.

Birkholz, et al.        Expires 28 December 2026                [Page 3]
Internet-Draft                   SCRAPI                        June 2026

   *  Issuance of Receipts and construction of Transparent Statements
      (Section 7 of [I-D.draft-ietf-scitt-architecture]), realized by
      the Receipt resolution resource defined in Section 2.4.

   *  Discovery of the Transparency Service verification keys used by
      Verifiers to validate Receipts (Section 5.1.2 and Section 9.4 of
      [I-D.draft-ietf-scitt-architecture]), realized by the resource
      defined in Section 2.1.

   The mandatory-to-implement resources listed above are sufficient for
   an interoperable Transparency Service.

   The following aspects of [I-D.draft-ietf-scitt-architecture] are
   intentionally out of scope for this document and are not covered by
   this API:

   *  The internal structure and operation of the Transparency Service's
      Verifiable Data Structure (Section 5.1.3 of
      [I-D.draft-ietf-scitt-architecture]).

   *  The contents and evaluation of Registration Policies
      (Section 5.1.1 of [I-D.draft-ietf-scitt-architecture]); this
      document only defines how the outcome of a policy decision is
      communicated to clients.

   *  The format and semantics of Signed Statements, Receipts, and
      Transparent Statements themselves, which are defined in
      [I-D.draft-ietf-scitt-architecture] and the COSE specifications
      referenced therein.

   *  Transports other than HTTP, and bindings of these resources to
      other application protocols.

1.2.  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 [RFC2119] [RFC8174] 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
   [I-D.draft-ietf-scitt-architecture].

   This specification uses "payload" as defined in [RFC9052].

Birkholz, et al.        Expires 28 December 2026                [Page 4]
Internet-Draft                   SCRAPI                        June 2026

2.  Resources

   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 MUST be a
   Concise Problem Details object (application/concise-problem-
   details+cbor) [RFC9290].

   The Concise Problem Details object MUST contain the following fields:

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

   As specified by Section 2 of [RFC9290], the title and detail values
   use oltext, which is either an unadorned CBOR text string (text) or a
   language-tagged text string (tag38).  When a language needs to be
   identified explicitly, tag38 carries a BCP 47 language tag as
   described in Appendix A of [RFC9290].  If no explicit or implicit
   language context is available, unadorned text is interpreted with the
   language tag en.

   SCRAPI is not a CoAP API, but Constrained Problem Details objects
   [RFC9290] provide a useful encoding for problem details and avoid the
   need to mix CBOR and JSON in resource or client implementations.

   Examples of errors may include:

   NOTE: '\' line wrapping per RFC 8792

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

Birkholz, et al.        Expires 28 December 2026                [Page 5]
Internet-Draft                   SCRAPI                        June 2026

   NOTE: '\' line wrapping per RFC 8792

   {
     / title /         -1: \
               "Malformed request",
     / detail /        -2: \
               "The request could not be parsed"
   }

   Per the guidance in Section 4.6 of [RFC9205], the specific HTTP
   status codes shown in the examples throughout this document are
   illustrative.  Status codes can be generated by generic HTTP
   components (caches, intermediaries, captive portals, gateways, etc.)
   that are not part of the Transparency Service, and the set of
   registered HTTP status codes can be extended over time.  Clients MUST
   therefore be prepared to handle any HTTP status code by falling back
   to the generic class semantics (1xx, 2xx, 3xx, 4xx, or 5xx) of the
   response when a more specific code is not recognized, and MUST rely
   on the Concise Problem Details [RFC9290] object (when present) rather
   than the status code alone to determine the application-level cause
   of an error.

   Clients handle 5xx responses as defined in Section 15.6 of [RFC9110]
   and Section 9.2.2 of [RFC9110].

   Note that in the case of any error response, the Transparency Service
   MAY include a Retry-After header field per [RFC9110] 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.

   The following subsections specify the HTTP resources required for
   conformance, as listed in Section 1.

2.1.  Transparency Service Keys

   This resource, located at /.well-known/scitt-keys (registered in
   accordance with [RFC8615]; see Section 6.1), is used to discover the
   public keys that can be used by relying parties to verify Receipts
   issued by the Transparency Service.

   Clients interact with this resource by issuing an HTTP GET request,
   and MUST include Accept: application/cbor in the request.  The
   Transparency Service MUST respond with a COSE Key Set, as defined in
   Section 7 of [RFC9052], serialized as application/cbor.

   Request:

Birkholz, et al.        Expires 28 December 2026                [Page 6]
Internet-Draft                   SCRAPI                        June 2026

   GET /.well-known/scitt-keys HTTP/1.1
   Host: transparency.example
   Accept: application/cbor

   Response:

   HTTP/1.1 200 OK
   Content-Type: application/cbor

   Body (in CBOR diagnostic notation)

   [
     {
       -1:1,
       -2:h'65eda5a1...9c08551d',
       -3:h'1e52ed75...0084d19c',
       1:2,
       2:'kid1'
     },
     {
       -1:1,
       -2:h'bac5b11c...d6a09eff',
       -3:h'20138bf8...bbfc117e',
       1:2,
       2:'kid2'
     }
   ]

   The Transparency Service MAY stop returning keys it no longer uses to
   issue Receipts from that resource, following a reasonable delay.  A
   delay is considered reasonable if it is sufficient for relying
   parties to have obtained the key needed to verify any previously
   issued Receipt.  Consistent with key management best practices
   described in [NIST.SP.800-57pt1r5] (Section 5.3.4, which
   distinguishes the originator-usage period during which a private key
   is used to apply cryptographic protection from the recipient-usage
   period during which the corresponding public key is used to verify
   that protection), retired public keys used for signing SHOULD remain
   available for verification for as long as any Receipts signed with
   them may still need to be verified, unless an alternative key
   archival or distribution mechanism preserves verifiability for
   relying parties.  Retaining retired keys has operational
   implications: the Transparency Service is responsible for storing
   those keys (and their associated metadata, such as kid values and
   validity periods) securely and continuously, and for serving them via
   the Individual Transparency Service Key resource (see Section 2.2)
   for the entire retention period.  If retired public keys are not
   retained, Receipts issued under those keys can no longer be verified

Birkholz, et al.        Expires 28 December 2026                [Page 7]
Internet-Draft                   SCRAPI                        June 2026

   by relying parties using only the Transparency Service's published
   key material, which may break the verifiability of previously issued
   Receipts and disrupt downstream consumers that depend on long-term
   verification.

   A Transparency Service MAY include the Expires header field, as
   defined in Section 5.3 of [RFC9111], in responses returned by this
   resource and by the Individual Transparency Service Key resource
   (Section 2.2) to indicate how long clients may cache the returned
   keys.  A Transparency Service MAY use the Cache-Control header field
   with the max-age directive, as defined in Section 5.2.2.1 of
   [RFC9111], for the same purpose; when both are present, Cache-
   Control: max-age takes precedence per Section 4.2.1 of [RFC9111].
   The cache lifetime indicated by these headers is a hint about server
   availability and does not constrain client retention.  A relying
   party that holds a Receipt MUST retain the verification key for as
   long as it may need to verify that Receipt, independent of any cache
   lifetime indicated by the Transparency Service.

   The presence of these headers does not constitute a guarantee of key
   availability.  A Transparency Service may still need to retire a key
   before any indicated cache lifetime has elapsed, for example in
   response to suspected compromise or cryptographic algorithm
   deprecation.  In such cases, a relying party that holds a Receipt
   signed with a retired key can request a fresh Receipt for the same
   Signed Statement at the same position in the Verifiable Data
   Structure, signed with a current key.

2.2.  Individual Transparency Service Key

   This sub-resource, located at /.well-known/scitt-keys/{kid_value}, is
   used to resolve a single public key, from a kid value contained in a
   Receipt previously issued by the Transparency Service.

   Clients interact with this sub-resource by issuing an HTTP GET
   request, and MUST include Accept: application/cbor in the request.
   The Transparency Service MUST respond with a single COSE Key, as
   defined in Section 7 of [RFC9052], serialized as application/cbor, or
   a 404 status if no matching key is found.

   Request:

   GET /.well-known/scitt-keys/{kid_value} HTTP/1.1
   Host: transparency.example
   Accept: application/cbor

   Response:

Birkholz, et al.        Expires 28 December 2026                [Page 8]
Internet-Draft                   SCRAPI                        June 2026

   HTTP/1.1 200 OK
   Content-Type: application/cbor

   Body (in CBOR diagnostic notation)

   {
     -1:1,
     -2:h'bac5b11c...d6a09eff',
     -3:h'20138bf8...bbfc117e',
     1:2,
     2:'kid_value'
   }

   The following expected error is defined for the condition described
   below.  When this condition is encountered, an implementation MUST
   return an error response that is a valid [RFC9290] object.
   Implementations SHOULD use the error defined below, unless another
   valid [RFC9290] error better describes the condition:

   HTTP/1.1 404 Not Found
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: "No such key",
     / detail /        -2: "No key could be found for this kid value"
   }

   To avoid requiring clients to infer an encoding convention from any
   particular kid value, the base64url form is always valid.  For every
   kid value used by the service, this resource MUST accept the
   base64url encoding of the kid value, without padding, as {kid_value}.
   If a kid value is safe for use as a URI path segment without percent-
   encoding, this resource MUST also accept the kid value itself as
   {kid_value}. Both forms, when present, identify the same key.  A
   Transparency Service MUST NOT use kid values whose raw and base64url
   forms would make the same URL identify different keys.

   Section 2 of [RFC7515] specifies Base64Url encoding as follows:

   "Base64 encoding using the URL- and filename-safe character set
   defined in Section 5 of RFC 4648 [RFC4648], with all trailing '='
   characters omitted and without the inclusion of any line breaks,
   whitespace, or other additional characters.  Note that the base64url
   encoding of the empty octet sequence is the empty string.  (See
   Appendix C of [RFC7515] for notes on implementing base64url encoding
   without padding.)"

Birkholz, et al.        Expires 28 December 2026                [Page 9]
Internet-Draft                   SCRAPI                        June 2026

   It is RECOMMENDED to use COSE Key Thumbprint, as defined in [RFC9679]
   as the mechanism to assign a kid to Transparency Service keys.
   [RFC9679] provides a well-specified, canonical method to
   deterministically derive a unique kid value directly from the COSE
   Key itself.  Using this mechanism offers several benefits to
   implementers:

   *  it ensures that the kid is uniquely and reproducibly bound to the
      key material,

   *  it removes the need for an out-of-band identifier assignment
      process,

   *  it enables independent parties to compute and verify the same kid
      for a given key, which simplifies key discovery and reduces the
      risk of kid collisions across Transparency Services.

2.3.  Register Signed Statement

   This resource 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 for the eventual Receipt
   resource, which the client can poll to retrieve the Receipt once
   registration completes.

   The following is a non-normative example of an HTTP request to
   register a Signed Statement:

   Request:

Birkholz, et al.        Expires 28 December 2026               [Page 10]
Internet-Draft                   SCRAPI                        June 2026

   POST /entries HTTP/1.1
   Host: transparency.example
   Accept: application/cbor
   Accept: application/cose
   Content-Type: application/cose

   Body (in CBOR diagnostic notation)

   18([ / COSE Sign1           /
     <<{
       / signature alg         / 1:  -35, # ES384
       / key identifier        / 4:   h'75726e3a...32636573',
       / cose sign1 type       / 16:  "application/example+cose",
       / payload-hash-alg      / 258: -16, # sha-256
       / preimage-content-type / 259: "application/spdx+json",
       / payload-location      / 260: "https://.../manifest.json",
       / CWT Claims            / 15: {
         / Issuer  / 1: "vendor.example",
         / Subject / 2: "vendor.product.example",
       }
     }>>,                          / Protected Header   /
     {},                           / Unprotected Header /
     / Payload, sha-256 digest of file stored at payload-location /
     h'935b5a91...e18a588a',
     h'269cd68f4211dffc...0dcb29c' / Signature /
   ])

   A Transparency Service depends on 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.

   Signed Statements MAY use detached payloads, as described in
   [I-D.draft-ietf-scitt-architecture].  When a Signed Statement is
   submitted with a detached payload, the Transparency Service still
   requires access to the payload content in order to verify the
   signature as part of applying the Registration Policy.  The mechanism
   by which the payload is made available to the Transparency Service is
   implementation-specific.

   Response:

   One of the following:

Birkholz, et al.        Expires 28 December 2026               [Page 11]
Internet-Draft                   SCRAPI                        June 2026

2.3.1.  Status 201 - Registration is successful

   If the Transparency Service is able to produce a Receipt within a
   reasonable time, it MAY return it directly.

   HTTP/1.1 201 Created
   Location: https://transparency.example/entries/67ed...befe
   Content-Type: application/cose

   Body (in CBOR diagnostic notation)

   / cose-sign1 / 18([
     / protected   / <<{
       / key / 4 : "mxA4KiOkQFZ-dkLebSo3mLOEPR7rN8XtxkJe45xuyJk",
       / algorithm / 1 : -7,  # ES256
       / vds       / 395 : 1, # RFC9162 SHA-256
       / claims / 15 : {
         / issuer  / 1 : "https://blue.notary.example",
         / subject / 2 : "https://green.software.example/cli@v1.2.3",
       },
     }>>,
     / unprotected / {
       / proofs / 396 : {
         / inclusion / -1 : [
           <<[
             / size / 9, / leaf / 8,
             / inclusion path /
             h'7558a95f...e02e35d6'
           ]>>
         ],
       },
     },
     / payload     / null,
     / signature   / h'02d227ed...ccd3774f'
   ])

   The response contains the Receipt for the Signed Statement.  The
   response MUST contain a Location header field whose value is the URL
   of the Receipt resource (see Section 2.4).  Fresh Receipts may be
   requested through the resource identified in the Location header.

   Transparency Services that support both synchronous and asynchronous
   registration MUST return the same Location URL for the same
   registered Signed Statement regardless of which registration mode was
   used.

Birkholz, et al.        Expires 28 December 2026               [Page 12]
Internet-Draft                   SCRAPI                        June 2026

2.3.2.  Status 202 - 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 returns a 202 Accepted response, as in this non-normative
   example:

   HTTP/1.1 202 Accepted
   Location: https://transparency.example/entries/67ed...befe
   Content-Length: 0
   Retry-After: <seconds>

   The response MUST contain a Location header field whose value is the
   URL of the eventual Receipt resource (see Section 2.4).  The client
   polls this resource to retrieve the Receipt once registration
   completes.

   The Transparency Service MAY include a Retry-After header in the HTTP
   response to help with polling.

2.3.3.  Status 400 - Invalid Client Request

   The following expected errors are defined for the conditions
   described below.  When such a condition is encountered, an
   implementation MUST return an error response that is a valid
   [RFC9290] object.  Implementations SHOULD use the corresponding error
   defined below, unless another valid [RFC9290] error better describes
   the condition.

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 400 Bad Request
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: \
             "Bad Signature Algorithm",
     / detail /        -2: \
             "Signed Statement contained a non-supported algorithm"
   }

Birkholz, et al.        Expires 28 December 2026               [Page 13]
Internet-Draft                   SCRAPI                        June 2026

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 400 Bad Request
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: "\
             Confirmation Missing",
     / detail /        -2: \
             "Signed Statement did not contain proof of possession"
   }

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 400 Bad Request
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: \
             "Payload Missing",
     / detail /        -2: \
             "Signed Statement payload must be present"
   }

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 400 Bad Request
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: \
             "Rejected",
     / detail /        -2: \
             "Signed Statement not accepted by the current\
             Registration Policy"
   }

   HTTP/1.1 400 Bad Request
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: "Invalid locator",
     / detail /        -2: "Operation locator is not in a valid form"
   }

Birkholz, et al.        Expires 28 December 2026               [Page 14]
Internet-Draft                   SCRAPI                        June 2026

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

   NOTE: '\' line wrapping per RFC 8792

   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."
   }

2.4.  Resolve Receipt

   This resource resolves the Receipt for a given EntryID.  It is the
   resource identified by the Location header returned in the 202
   Accepted response to an asynchronous registration request (see
   Section 2.3), and may also be used at any later time to obtain a
   fresh Receipt for a previously registered Signed Statement.

   A client polls this resource to obtain the Receipt.  The response is
   one of:

   *  200, once registration is complete and the Receipt is available;

   *  204, while registration is still in progress; or

   *  404, if no Receipt exists for the EntryID, including when
      registration has failed.

   Request:

   GET /entries/67ed41f1de6a...cfc158694ed0befe HTTP/1.1
   Host: transparency.example
   Accept: application/cose

   Response:

   One of the following:

Birkholz, et al.        Expires 28 December 2026               [Page 15]
Internet-Draft                   SCRAPI                        June 2026

2.4.1.  Status 200 - OK

   If the Receipt is found:

   HTTP/1.1 200 OK
   Location: https://transparency.example/entries/67ed...befe
   Content-Type: application/cose

   Body (in CBOR diagnostic notation)

   / cose-sign1 / 18([
     / protected   / <<{
       / key / 4 : "mxA4KiOkQFZ-dkLebSo3mLOEPR7rN8XtxkJe45xuyJk",
       / algorithm / 1 : -7,  # ES256
       / vds       / 395 : 1, # RFC9162 SHA-256
       / claims / 15 : {
         / issuer  / 1 : "https://blue.notary.example",
         / subject / 2 : "https://green.software.example/cli@v1.2.3",
       },
     }>>,
     / unprotected / {
       / proofs / 396 : {
         / inclusion / -1 : [
           <<[
             / size / 9, / leaf / 8,
             / inclusion path /
             h'7558a95f...e02e35d6'
           ]>>
         ],
       },
     },
     / payload     / null,
     / signature   / h'02d227ed...ccd3774f'
   ])

2.4.2.  Status 204 - Registration is running

   If the registration identified by the EntryID is still in progress,
   the Transparency Service returns a 204 No Content response, as in
   this non-normative example:

   HTTP/1.1 204 No Content
   Retry-After: <seconds>
   Cache-Control: no-store

Birkholz, et al.        Expires 28 December 2026               [Page 16]
Internet-Draft                   SCRAPI                        June 2026

   The Transparency Service SHOULD include a Retry-After header in the
   HTTP response to help with polling.  Because a 204 response is
   transient and the resource is expected to return a Receipt once
   registration completes, the Transparency Service SHOULD set Cache-
   Control: no-store to prevent caching of the in-progress response.

2.4.3.  Status 404 - Not Found

   If there is no Receipt found for the specified EntryID the
   Transparency Service MUST respond with a 4xx-class status code
   (typically 404 Not Found) and a Concise Problem Details [RFC9290]
   object as in the following example:

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 404 Not Found
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: \
             "Not Found",
     / detail /        -2: \
             "Receipt with entry ID <id> not known \
             to this Transparency Service"
   }

   A 404 response is also returned when an asynchronous registration has
   failed and no Receipt will be produced.  In that case, the
   Transparency Service MAY enrich the Concise Problem Details object
   with application-specific detail explaining why registration did not
   complete, as in this non-normative example:

   NOTE: '\' line wrapping per RFC 8792

   HTTP/1.1 404 Not Found
   Content-Type: application/concise-problem-details+cbor

   {
     / title /         -1: \
             "Registration Failed",
     / detail /        -2: \
             "Signed Statement with entry ID <id> could not \
             be persisted to the log"
   }

   As an example, a successful asynchronous registration followed by
   Receipt resolution follows this sequence:

Birkholz, et al.        Expires 28 December 2026               [Page 17]
Internet-Draft                   SCRAPI                        June 2026

   Initial exchange:

   Client --- POST /entries (Signed Statement) --> TS
   Client <-- 202 Location: .../entries/123     --- TS

   May happen zero or more times:

   Client --- GET .../entries/123              --> TS
   Client <-- 204 Retry-After: <seconds>       --- TS

   Finally:

   Client --- GET .../entries/123              --> TS
   Client <-- 200 (Receipt)                    --- TS

3.  Privacy Considerations

   The privacy considerations section of
   [I-D.draft-ietf-scitt-architecture] applies to this document.

4.  Security Considerations

4.1.  General Scope

   This document describes the interoperable API for client calls to,
   and implementations of, a Transparency Service as specified in
   [I-D.draft-ietf-scitt-architecture].  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 for this document.

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

4.3.  Authentication

   Authentication is out of scope for this document.  Implementations
   MAY authenticate clients, for example for the purposes of
   authorization or preventing denial-of-service attacks.  If
   Authentication is not implemented, rate limiting or other denial-of-
   service mitigations MUST be implemented.

Birkholz, et al.        Expires 28 December 2026               [Page 18]
Internet-Draft                   SCRAPI                        June 2026

4.4.  Threat Model

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

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

   The impact of DoS attacks can be detected by a 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, a DoS
   attack cannot cause the silent loss of a registration.  However, this
   relies on clients actively checking for Receipts and does not prevent
   the disruption itself.

   Clients to Transparency Services that need to detect delayed or lost
   registrations MUST 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 MUST follow
   general good practice around defending against network attacks such
   as flooding, including defenses such as rate limiting.

Birkholz, et al.        Expires 28 December 2026               [Page 19]
Internet-Draft                   SCRAPI                        June 2026

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

4.4.1.3.  Message Modification Attacks

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

4.4.1.4.  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 and impersonation.

4.4.2.  Out of Scope

4.4.2.1.  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 be 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 MUST be
   added to the protected header signed by the Issuer.  The iat claim in
   a CWT_Claims header parameter ([RFC9597]) MUST be used when the
   Issuer provides the timestamp themselves.  The COSE header parameters
   defined in [RFC9921] for including [RFC3161] timestamp tokens or a
   similar mechanic, for example an Epoch Marker
   [I-D.ietf-rats-epoch-markers] Claim in the 'CWT_Claims' header
   parameter, SHOULD be used, where a timestamp from a third party is
   required, unless another protected-header mechanism is specified by
   the applicable profile.  Other mechanisms for including timestamps in
   the protected header MAY also be used.

Birkholz, et al.        Expires 28 December 2026               [Page 20]
Internet-Draft                   SCRAPI                        June 2026

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

4.4.2.3.  Use of Unauthenticated HTTP Metadata

   Implementations that serve multiple application profiles MAY use
   unauthenticated HTTP-layer signals, such as request headers or
   distinct registration endpoints, to route incoming Signed Statements
   to profile-specific processing.

   However, these signals are not signed, are not committed to the
   Verifiable Data Structure, and cannot be replayed by Auditors.

   Implementations MUST NOT use unauthenticated signals as authoritative
   inputs to the registration decision.

   Implementations that use such signals for early dispatch MUST ensure
   that any processing decisions that affect the outcome of registration
   are fully determined by authenticated inputs, or are otherwise
   captured in the Verifiable Data Structure, such that the registration
   process remains deterministic and replayable by Auditors.

   The authoritative identification of the application profile is
   carried within the protected header or payload of the Signed
   Statement, and MUST be verified after signature authentication.

5.  Operational Considerations

5.1.  Client Retry Behavior

   Aggressive client retry or polling behavior can significantly impact
   a Transparency Service, increasing load and, in extreme cases,
   amplifying transient failures into sustained outages.

   Clients that retry a request MUST honor any Retry-After header field
   (defined in Section 10.2.3 of [RFC9110]) returned by the Transparency
   Service, treating it as a minimum interval before retrying.  In its
   absence, clients that retry a request MUST apply exponential backoff
   with jitter, cap the total number of retries, and avoid synchronizing
   retries across clients.

Birkholz, et al.        Expires 28 December 2026               [Page 21]
Internet-Draft                   SCRAPI                        June 2026

5.2.  Server-Side Retry Configuration

   Operators SHOULD configure a minimum retry interval appropriate for
   the expected registration latency and service capacity, and SHOULD
   communicate it to clients via the Retry-After header on relevant
   responses (e.g., 202, 204, 429, 503), unless the service does not
   support client polling or retries for those responses.  The interval
   should account for worst-case registration time, sustainable request
   volume, and intermediary behavior.

5.3.  Rate Limiting

   As noted in Section 4.3 and Section 4.4.1.1, rate limiting or other
   denial-of-service mitigations are required.  The specific per-client
   policy is implementation dependent and typically varies with whether
   and how clients are authenticated (e.g., per-identity for
   authenticated clients versus per source IP for unauthenticated
   clients), the cost of the operation, and the deployment environment.

   When a client exceeds the configured rate limit, the Transparency
   Service MUST return a 429 response (see Section 2.3.4) including a
   Retry-After header field.

6.  IANA Considerations

6.1.  Well-Known URI for Key Discovery

   IANA is requested to register the /.well-known/scitt-keys URI in the
   "Well-Known URIs" registry defined in [RFC8615].  The normative
   behavior of this resource and its /{kid_value} sub-resource is
   specified in Section 2.1 and Section 2.2.

6.1.1.  Registration Template

   The following value is requested to be registered in the "Well-Known
   URIs" registry (using the template from [RFC8615]):

   *  URI suffix: scitt-keys

   *  Change controller: IETF

   *  Specification document(s): RFCthis

   *  Status: Permanent

   *  Related information: [I-D.draft-ietf-scitt-architecture]

7.  References

Birkholz, et al.        Expires 28 December 2026               [Page 22]
Internet-Draft                   SCRAPI                        June 2026

7.1.  Normative References

   [I-D.draft-ietf-scitt-architecture]
              Birkholz, H., Delignat-Lavaud, A., Fournet, C., Deshpande,
              Y., and S. Lasker, "An Architecture for Trustworthy and
              Transparent Digital Supply Chains", Work in Progress,
              Internet-Draft, draft-ietf-scitt-architecture-22, 10
              October 2025, <https://datatracker.ietf.org/doc/html/
              draft-ietf-scitt-architecture-22>.

   [NIST.SP.800-57pt1r5]
              Barker, E., "Recommendation for Key Management: Part 1 -
              General", NIST Special Publication 800-57 Part 1 Revision
              5, May 2020,
              <https://doi.org/10.6028/NIST.SP.800-57pt1r5>.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119,
              DOI 10.17487/RFC2119, March 1997,
              <https://www.rfc-editor.org/rfc/rfc2119>.

   [RFC3161]  Adams, C., Cain, P., Pinkas, D., and R. Zuccherato,
              "Internet X.509 Public Key Infrastructure Time-Stamp
              Protocol (TSP)", RFC 3161, DOI 10.17487/RFC3161, August
              2001, <https://www.rfc-editor.org/rfc/rfc3161>.

   [RFC4648]  Josefsson, S., "The Base16, Base32, and Base64 Data
              Encodings", RFC 4648, DOI 10.17487/RFC4648, October 2006,
              <https://www.rfc-editor.org/rfc/rfc4648>.

   [RFC7515]  Jones, M., Bradley, J., and N. Sakimura, "JSON Web
              Signature (JWS)", RFC 7515, DOI 10.17487/RFC7515, May
              2015, <https://www.rfc-editor.org/rfc/rfc7515>.

   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
              May 2017, <https://www.rfc-editor.org/rfc/rfc8174>.

   [RFC8615]  Nottingham, M., "Well-Known Uniform Resource Identifiers
              (URIs)", RFC 8615, DOI 10.17487/RFC8615, May 2019,
              <https://www.rfc-editor.org/rfc/rfc8615>.

   [RFC8792]  Watsen, K., Auerswald, E., Farrel, A., and Q. Wu,
              "Handling Long Lines in Content of Internet-Drafts and
              RFCs", RFC 8792, DOI 10.17487/RFC8792, June 2020,
              <https://www.rfc-editor.org/rfc/rfc8792>.

Birkholz, et al.        Expires 28 December 2026               [Page 23]
Internet-Draft                   SCRAPI                        June 2026

   [RFC9052]  Schaad, J., "CBOR Object Signing and Encryption (COSE):
              Structures and Process", STD 96, RFC 9052,
              DOI 10.17487/RFC9052, August 2022,
              <https://www.rfc-editor.org/rfc/rfc9052>.

   [RFC9110]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Semantics", STD 97, RFC 9110,
              DOI 10.17487/RFC9110, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9110>.

   [RFC9111]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
              Ed., "HTTP Caching", STD 98, RFC 9111,
              DOI 10.17487/RFC9111, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9111>.

   [RFC9205]  Nottingham, M., "Building Protocols with HTTP", BCP 56,
              RFC 9205, DOI 10.17487/RFC9205, June 2022,
              <https://www.rfc-editor.org/rfc/rfc9205>.

   [RFC9290]  Fossati, T. and C. Bormann, "Concise Problem Details for
              Constrained Application Protocol (CoAP) APIs", RFC 9290,
              DOI 10.17487/RFC9290, October 2022,
              <https://www.rfc-editor.org/rfc/rfc9290>.

   [RFC9597]  Looker, T. and M.B. Jones, "CBOR Web Token (CWT) Claims in
              COSE Headers", RFC 9597, DOI 10.17487/RFC9597, June 2024,
              <https://www.rfc-editor.org/rfc/rfc9597>.

   [RFC9679]  Isobe, K., Tschofenig, H., and O. Steele, "CBOR Object
              Signing and Encryption (COSE) Key Thumbprint", RFC 9679,
              DOI 10.17487/RFC9679, December 2024,
              <https://www.rfc-editor.org/rfc/rfc9679>.

   [RFC9921]  Birkholz, H., Fossati, T., and M. Riechert, "CBOR Object
              Signing and Encryption (COSE) Header Parameter for
              Timestamp Tokens as Defined in RFC 3161", RFC 9921,
              DOI 10.17487/RFC9921, February 2026,
              <https://www.rfc-editor.org/rfc/rfc9921>.

7.2.  Informative References

   [I-D.ietf-rats-epoch-markers]
              Birkholz, H., Fossati, T., Pan, W., Mihalcea, I., and C.
              Bormann, "Epoch Markers", Work in Progress, Internet-
              Draft, draft-ietf-rats-epoch-markers-04, 18 May 2026,
              <https://datatracker.ietf.org/doc/html/draft-ietf-rats-
              epoch-markers-04>.

Birkholz, et al.        Expires 28 December 2026               [Page 24]
Internet-Draft                   SCRAPI                        June 2026

   [RFC9162]  Laurie, B., Messeri, E., and R. Stradling, "Certificate
              Transparency Version 2.0", RFC 9162, DOI 10.17487/RFC9162,
              December 2021, <https://www.rfc-editor.org/rfc/rfc9162>.

Contributors

   Orie Steele
   Transmute
   United States
   Email: orie@transmute.industries

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

   Amaury Chamayou
   Microsoft
   United Kingdom
   Email: amaury.chamayou@microsoft.com

   Amaury contributed crucial content to ensure interoperability between
   implementations, improve example expressiveness and consistency, as
   well as overall document quality.

   Dick Brooks
   Business Cyber Guardian
   United States
   Email: dick@businesscyberguardian.com

   Dick contributed use cases and helped improve example expressiveness
   and consistency.

   Robert Martin
   MITRE Corporation
   United States
   Email: ramartin@mitre.org

   Bob contributed use cases and helped with authoring and improving the
   document.

   Steve Lasker
   Email: stevenlasker@hotmail.com

Birkholz, et al.        Expires 28 December 2026               [Page 25]
Internet-Draft                   SCRAPI                        June 2026

   Steve contributed architectural insights, particularly around
   asynchronous operations and participated in the initial writing of
   the document.

   Nicole Bates
   Microsoft
   United States
   Email: nicolebates@microsoft.com

   Nicole contributed reviews and edits that improved the quality of the
   text.

   Roy Williams
   United States of America
   Email: roywill@msn.com

   Roy contributed the receipt refresh use case and associated resource
   definition.

Authors' Addresses

   Henk Birkholz
   Fraunhofer SIT
   Rheinstrasse 75
   64295 Darmstadt
   Germany
   Email: henk.birkholz@ietf.contact

   Jon Geater
   Bowball Technologies Ltd
   United Kingdom
   Email: jonathan@bowball-tech.com

   Antoine Delignat-Lavaud
   Microsoft Research
   21 Station Road
   Cambridge
   CB1 2FB
   United Kingdom
   Email: antdl@microsoft.com

Birkholz, et al.        Expires 28 December 2026               [Page 26]