SCITT                                                        H. Birkholz
Internet-Draft                                            Fraunhofer SIT
Intended status: Standards Track                               J. Geater
Expires: 12 July 2025                                    DataTrails Inc.
                                                          8 January 2025


            SCITT Reference APIs Draft-ietf-scitt-scrapi-03
                       draft-ietf-scitt-scrapi-03

Abstract

   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

   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 & Geater         Expires 12 July 2025                  [Page 1]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   This Internet-Draft will expire on 12 July 2025.

Copyright Notice

   Copyright (c) 2025 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.  Terminology . . . . . . . . . . . . . . . . . . . . . . .   4
   2.  Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . .   4
     2.1.  Mandatory . . . . . . . . . . . . . . . . . . . . . . . .   5
       2.1.1.  Transparency Configuration  . . . . . . . . . . . . .   5
       2.1.2.  Register Signed Statement . . . . . . . . . . . . . .   6
       2.1.3.  Check Registration  . . . . . . . . . . . . . . . . .  11
       2.1.4.  Resolve Receipt . . . . . . . . . . . . . . . . . . .  13
     2.2.  Optional Endpoints  . . . . . . . . . . . . . . . . . . .  14
       2.2.1.  Resolve Signed Statement  . . . . . . . . . . . . . .  15
       2.2.2.  Exchange Receipt  . . . . . . . . . . . . . . . . . .  16
       2.2.3.  Resolve Issuer  . . . . . . . . . . . . . . . . . . .  17
       2.2.4.  Request Nonce . . . . . . . . . . . . . . . . . . . .  18
   3.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  19
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .  19
     4.1.  General Scope . . . . . . . . . . . . . . . . . . . . . .  19
     4.2.  Applicable Environment  . . . . . . . . . . . . . . . . .  19
     4.3.  User-host Authentication  . . . . . . . . . . . . . . . .  19
     4.4.  Primary Threats . . . . . . . . . . . . . . . . . . . . .  20
       4.4.1.  In Scope  . . . . . . . . . . . . . . . . . . . . . .  20
       4.4.2.  Out of Scope  . . . . . . . . . . . . . . . . . . . .  21
   5.  TODO  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  22
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  22
     6.1.  URN Sub-namespace for SCITT (urn:ietf:params:scitt) . . .  22
     6.2.  Well-Known URI for Issuers  . . . . . . . . . . . . . . .  22
     6.3.  Well-Known URI for Transparency Configuration . . . . . .  22
     6.4.  Media Type Registration . . . . . . . . . . . . . . . . .  23
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  24
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  24
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  25



Birkholz & Geater         Expires 12 July 2025                  [Page 2]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   Contributors  . . . . . . . . . . . . . . . . . . . . . . . . . .  25
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  25

1.  Introduction

   The SCITT Architecture [I-D.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

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

   *  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







Birkholz & Geater         Expires 12 July 2025                  [Page 3]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


1.1.  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", "Append-Only Log" and "Registration Policy" as defined in
   [I-D.ietf-scitt-architecture].

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

2.  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 an HTTP 4xx or 5xx status code, and the body SHOULD be a
   Concise Problem Details object [RFC9290] 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.

   *  instance: A URN 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:".

   *  response-code: The HTTP error response code relating to this
      error.

   TODO: RESOLVE this dangling media-type

   application/concise-problem-details+cbor



Birkholz & Geater         Expires 12 July 2025                  [Page 4]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   NOTE: SCRAPI is not a CoAP API.  Nonetheless Constrained Problem
   Details objects [RFC9290] 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 [RFC8792]

   Examples of errors may include:

   {
     / title /         -1: \
               "Bad Signature Algorithm",
     / detail /        -2: \
               "Signing algorithm 'WalnutDSA' not supported",
     / instance /      -3: \
               "urn:ietf:params:scitt:error:badSignatureAlgorithm",
     / response-code / -4: 400,
   }

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

2.1.  Mandatory

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

2.1.1.  Transparency Configuration

   This endpoint is used to discover the capabilities and current
   configuration of a transparency service implementing this
   specification.




Birkholz & Geater         Expires 12 July 2025                  [Page 5]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   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/cose

Response:

HTTP/1.1 200 Ok
Content-Type: application/cose

Payload (in CBOR diagnostic notation)

18([                   ; COSE_Sign1 structure with tag 18
    h'44A123BEEFFACE', ; Protected header (example bytes)
    {},                ; Unprotected header
    {                  ; Payload - CBOR map
        "issuer": "https://transparency.example",
        "base_url": "https://transparency.example/v1/scrapi",
        "oidc_auth_endpoint": "https://transparency.example/auth",
        "registration_policy": "https://transparency.example/statements/\
urn:ietf:params:scitt:statement:sha-256:base64url:5i6UeRzg1...qnGmr1o"
    },
    h'ABCDEF1234567890ABCDEF1234567890'  ; Signature
])

   Responses to this message are vendor-specific.  Fields that are not
   understood MUST be ignored.

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



Birkholz & Geater         Expires 12 July 2025                  [Page 6]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   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:

2.1.2.1.  Status 201 - Registration is successful

   If the Transparency Service is able to mint receipts within a
   reasonable time, it may return the receipt 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)






Birkholz & Geater         Expires 12 July 2025                  [Page 7]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   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.

2.1.2.2.  Status 202 - Registration is running

   In cases where the registration request is accepted but the
   Transparency Service is not able to mint Receipts in a reasonable
   time, it returns a locator for the registration operation and a
   status code indicating the status of the operation, as in this non-
   normative example:

   {
     / locator / "OperationID": "67f89d5f0042e3ad42...35a1f190",
     / status /  "Status": "running",
   }

   Status must be one of the following:

   *  "running" - the operation is still in progress

   *  "succeeded" - the operation succeeded and the Receipt is ready

   OperationID is Transparency Service-specific and MUST not be used for
   querying status in any Transparency Service other than the one that
   returned it.

   If the OperationID is a valid URL, it MAY be included as a Location
   header in the HTTP response.

   Transparency Services do not guarantee the retention of operation IDs
   for the entirety of their lifecycle.  A Transparency MAY delete
   operation records, and some operation ID lookups MAY return error
   404, even though they were valid in the past.  The length of validity
   of the OperationID is Transparency Service specific.  Still, the
   Transparency Service MUST maintain a record of every running or
   successful operation until at least one client has fetched the
   completed Receipt.

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



Birkholz & Geater         Expires 12 July 2025                  [Page 8]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   HTTP/1.1 202 Accepted

   Location: https://transparency.example/operations/67f8...f190

   Content-Type: application/cbor
   Retry-After: <seconds>

   {
     / locator / "OperationID": "67f89d5f0042e3ad42...35a1f190",
     / status /  "Status": "running",
   }

   The response contains an ID referencing the running operation for
   Signed Statement Registration.

   If 202 is returned, then clients should wait until Registration
   succeeded or failed by polling the Check Operation endpoint using the
   OperationID returned in the response.

2.1.2.3.  Status 400 - Invalid Client Request

   The following expected errors are defined.  Implementations MAY
   return other errors, so long as they are valid [RFC9290] 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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:badSignatureAlgorithm",
     / response-code / -4: 400,
   }

   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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:signed-statement:\
             confirmation-missing",



Birkholz & Geater         Expires 12 July 2025                  [Page 9]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


     / response-code / -4: 400,
   }

   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)",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:signed-statement:\
             payload-missing",
     / response-code / -4: 400,
   }

   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)",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:signed-statement:\
             payload-forbidden",
     / response-code / -4: 400,
   }

   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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:signed-statement:\
             rejected-by-registration-policy",
     / response-code / -4: 400,
   }




Birkholz & Geater         Expires 12 July 2025                 [Page 10]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


2.1.3.  Check Registration

   Authentication MAY be implemented for this endpoint.

   This endpoint is used to check the progress of a long-running
   registration.

   The following is a non-normative example of an HTTP request for the
   status of a running registration:

   Request:

   GET /operations/67f89d5f0042e3ad42...35a1f190, HTTP/1.1
   Host: transparency.example
   Accept: application/cbor

   Response:

   One of the following:

2.1.3.1.  Status 200 - Operation complete

   _Success case_

   If the operation is complete and it _succeeded_, the Transparency
   Service returns a status of "succeeded" along with a locator that can
   fetch the Receipt.

   EntryID is Transparency Service specific and MUST not be used for
   fetching Receipts in any Transparency Service other than the one that
   returned it.

   If the EntryID is a valid URL, it MAY be included as a Location
   header in the HTTP response.

   HTTP/1.1 200 Ok

   Location: https://transparency.example/entries/67ed...befe

   Content-Type: application/cbor

   {
     / locator / "EntryID": "67f89d5f0042e3ad42...35a1f190",
     / status /  "Status": "succeeded",
   }

   _Failure case_




Birkholz & Geater         Expires 12 July 2025                 [Page 11]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   If the operation is complete and it _failed_, the Transparency
   Service returns a status of "failed" and an optional [RFC9290]
   Concise Problem Details object to explain the failure.

   HTTP/1.1 200 Ok

   Content-Type: application/cbor

   {
     / status / "Status": "failed",
     / error /  "Error": {
       / title /         -1: \
               "Bad Signature Algorithm",
       / detail /        -2: \
               "Signed Statement contained a non supported algorithm",
       / instance /      -3: \
               "urn:ietf:params:scitt:error:badSignatureAlgorithm",
     }
   }

2.1.3.2.  Status 202 - Registration is (still) running

   HTTP/1.1 202 Accepted

   Location: https://transparency.example/operations/67f8...f190

   Retry-After: <seconds>

   If 202 is returned, then clients should continue polling the Check
   Operation endpoint using the operation identifier.

2.1.3.3.  Status 400 - Invalid Client Request

   The following expected errors are defined.  Implementations MAY
   return other errors, so long as they are valid [RFC9290] 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",
     / instance /      -3: "urn:ietf:params:scitt:error:invalidRequest",
     / response-code / -4: 400,
   }






Birkholz & Geater         Expires 12 July 2025                 [Page 12]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


2.1.3.4.  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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:notFound",
     / response-code / -4: 404,
   }

2.1.3.5.  Status 429

   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.",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:tooManyRequests",
     / response-code / -4: 429,
   }

2.1.4.  Resolve Receipt

   Authentication SHOULD be implemented for this endpoint.

   Request:








Birkholz & Geater         Expires 12 July 2025                 [Page 13]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


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

   Response:

2.1.4.1.  Status 200

   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          /
   ])

2.1.4.2.  Status 404

   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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:receipt:not-found",
     / response-code / -4: 404,
   }

2.2.  Optional Endpoints

   The following HTTP endpoints are optional to implement.






Birkholz & Geater         Expires 12 July 2025                 [Page 14]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


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

2.2.1.1.  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          /
   ])

2.2.1.2.  Status 404 - Not Found

   The following expected errors are defined.  Implementations MAY
   return other errors, so long as they are valid [RFC9290] 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",
     / instance /      -3: \
             "urn:ietf:params:scitt:error:notFound",
     / response-code / -4: 404,





Birkholz & Geater         Expires 12 July 2025                 [Page 15]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


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

2.2.2.  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          /
   ])

2.2.2.1.  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)








Birkholz & Geater         Expires 12 July 2025                 [Page 16]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   18([                            / COSE Sign1         /
     h'a1013822',                  / Protected Header   /
     {},                           / Unprotected Header /
     null,                         / Detached Payload   /
     h'269cd68f4211dffc...0dcb29c' / Signature          /
   ])

2.2.3.  Resolve Issuer

   This endpoint is inspired by [I-D.ietf-oauth-sd-jwt-vc].

   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:



































Birkholz & Geater         Expires 12 July 2025                 [Page 17]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


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

2.2.4.  Request Nonce

   This endpoint in inspired by
   [I-D.draft-demarco-oauth-nonce-endpoint].

   Authentication SHOULD NOT be implemented for this endpoint.  This
   endpoint is used to demonstrate proof of possession, 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.




Birkholz & Geater         Expires 12 July 2025                 [Page 18]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   Request:

   GET /nonce HTTP/1.1
   Host: transparency.example
   Accept: application/json

   Response:

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

   {
     "nonce": "d2JhY2NhbG91cmVqdWFuZGFt"
   }

3.  Privacy Considerations

   TODO

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.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 of 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.  User-host Authentication

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



Birkholz & Geater         Expires 12 July 2025                 [Page 19]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   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.

4.4.  Primary Threats

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.

   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.






Birkholz & Geater         Expires 12 July 2025                 [Page 20]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   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.

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

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



Birkholz & Geater         Expires 12 July 2025                 [Page 21]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


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.

5.  TODO

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

6.  IANA Considerations

6.1.  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 [IANA.params], following the
   template in [RFC3553]:

      Registry name:     scitt

                         Specification: [RFCthis] Repository:
                         http://www.iana.org/assignments/scitt Index
                         value: No transformation needed.

6.2.  Well-Known URI for Issuers

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

   URI suffix: issuer Change controller: IETF Specification document(s):
   RFCthis.  Related information: N/A

6.3.  Well-Known URI for Transparency Configuration

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

   URI suffix: transparency-configuration Change controller: IETF
   Specification document(s): RFCthis.  Related information: N/A

   TODO: Register them from here.







Birkholz & Geater         Expires 12 July 2025                 [Page 22]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


6.4.  Media Type Registration

   This section requests registration of the "application/
   scitt.receipt+cose" media type [RFC2046] in the "Media Types"
   registry in the manner described in [RFC6838].

   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




Birkholz & Geater         Expires 12 July 2025                 [Page 23]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


7.  References

7.1.  Normative References

   [I-D.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-10, 13
              November 2024, <https://datatracker.ietf.org/doc/html/
              draft-ietf-scitt-architecture-10>.

   [IANA.params]
              IANA, "Uniform Resource Name (URN) Namespace for IETF
              Use", <https://www.iana.org/assignments/params>.

   [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/info/rfc2119>.

   [RFC3553]  Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
              IETF URN Sub-namespace for Registered Protocol
              Parameters", BCP 73, RFC 3553, DOI 10.17487/RFC3553, June
              2003, <https://www.rfc-editor.org/info/rfc3553>.

   [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/info/rfc8174>.

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

   [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/info/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/info/rfc9110>.

   [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/info/rfc9290>.



Birkholz & Geater         Expires 12 July 2025                 [Page 24]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


7.2.  Informative References

   [I-D.demarco-oauth-nonce-endpoint]
              De Marco, G. and O. Steele, "OAuth 2.0 Nonce Endpoint",
              Work in Progress, Internet-Draft, draft-demarco-oauth-
              nonce-endpoint-00, 6 February 2024,
              <https://datatracker.ietf.org/doc/html/draft-demarco-
              oauth-nonce-endpoint-00>.

   [I-D.ietf-oauth-sd-jwt-vc]
              Terbu, O., Fett, D., and B. Campbell, "SD-JWT-based
              Verifiable Credentials (SD-JWT VC)", Work in Progress,
              Internet-Draft, draft-ietf-oauth-sd-jwt-vc-08, 3 December
              2024, <https://datatracker.ietf.org/doc/html/draft-ietf-
              oauth-sd-jwt-vc-08>.

   [RFC2046]  Freed, N. and N. Borenstein, "Multipurpose Internet Mail
              Extensions (MIME) Part Two: Media Types", RFC 2046,
              DOI 10.17487/RFC2046, November 1996,
              <https://www.rfc-editor.org/info/rfc2046>.

   [RFC6838]  Freed, N., Klensin, J., and T. Hansen, "Media Type
              Specifications and Registration Procedures", BCP 13,
              RFC 6838, DOI 10.17487/RFC6838, January 2013,
              <https://www.rfc-editor.org/info/rfc6838>.

   [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/info/rfc8792>.

Contributors

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

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

Authors' Addresses

   Henk Birkholz
   Fraunhofer SIT
   Rheinstrasse 75
   64295 Darmstadt
   Germany



Birkholz & Geater         Expires 12 July 2025                 [Page 25]

Internet-Draft  SCITT Reference APIs Draft-ietf-scitt-sc    January 2025


   Email: henk.birkholz@sit.fraunhofer.de


   Jon Geater
   DataTrails Inc.
   United States
   Email: jon.geater@datatrails.ai












































Birkholz & Geater         Expires 12 July 2025                 [Page 26]