SCITT Reference APIs
draft-ietf-scitt-scrapi-00

SCITT                                                        H. Birkholz
Internet-Draft                                            Fraunhofer SIT
Intended status: Standards Track                               O. Steele
Expires: 28 July 2024                                          Transmute
                                                               J. Geater
                                                         DataTrails Inc.
                                                         25 January 2024

                          SCITT Reference APIs
                       draft-ietf-scitt-scrapi-00

Abstract

   This document defines the SCITT REST API, an http interface to
   transparency services, supporting the primary operations needed to
   implement the SCITT Architecture [I-D.draft-ietf-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 July 2024                  [Page 1]
Internet-Draft                   SCRAPI                     January 2024

   This Internet-Draft will expire on 28 July 2024.

Copyright Notice

   Copyright (c) 2024 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.  Requirements Notation . . . . . . . . . . . . . . . . . .   3
   2.  Relation to Identity  . . . . . . . . . . . . . . . . . . . .   3
     2.1.  Authenticating Clients  . . . . . . . . . . . . . . . . .   3
     2.2.  Discovering Federation  . . . . . . . . . . . . . . . . .   3
     2.3.  Discovering Feeds . . . . . . . . . . . . . . . . . . . .   3
   3.  SCITT Reference REST API  . . . . . . . . . . . . . . . . . .   3
     3.1.  Key Binding Confirmation  . . . . . . . . . . . . . . . .   3
       3.1.1.  Challenge Endpoint  . . . . . . . . . . . . . . . . .   5
       3.1.2.  Registration Endpoint . . . . . . . . . . . . . . . .   5
     3.2.  Messages  . . . . . . . . . . . . . . . . . . . . . . . .   6
       3.2.1.  Register Signed Statement . . . . . . . . . . . . . .   7
       3.2.2.  Retrieve Operation Status . . . . . . . . . . . . . .   8
       3.2.3.  Retrieve Signed Statement . . . . . . . . . . . . . .   9
       3.2.4.  Retrieve Registration Receipt . . . . . . . . . . . .   9
   4.  Privacy Considerations  . . . . . . . . . . . . . . . . . . .  10
   5.  Security Considerations . . . . . . . . . . . . . . . . . . .  10
   6.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  10
     6.1.  URN Sub-namespace for SCITT (urn:ietf:params:scitt) . . .  10
     6.2.  Media Types . . . . . . . . . . . . . . . . . . . . . . .  10
     6.3.  Well Known URIs . . . . . . . . . . . . . . . . . . . . .  10
     6.4.  Media Type Registration . . . . . . . . . . . . . . . . .  11
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .  12
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .  12
     7.2.  Informative References  . . . . . . . . . . . . . . . . .  12
   Appendix A.  Attic  . . . . . . . . . . . . . . . . . . . . . . .  13
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  13

Birkholz, et al.          Expires 28 July 2024                  [Page 2]
Internet-Draft                   SCRAPI                     January 2024

1.  Introduction

   This API definition MAY be exposed externally as part of a suite of
   APIs, or be encapsulated internally and exposed indirectly via
   proprietary APIs.

1.1.  Requirements Notation

   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.

2.  Relation to Identity

   The SCITT REST API is designed to support identifier systems that are
   currently relevant to supply chains, including DID, x509 and PGP.

   In order to support these systems, the API must be aware of specific
   header parameters, in particular, kid, x5u and x5c.

   The API enables implementers to deploy interoperable URIs for
   disclosing information feeds related to supply chain actors, and
   artifacts accessible via transparency services.

2.1.  Authenticating Clients

   TBD (comments on OAuth / Client Attestation).

2.2.  Discovering Federation

   TBD (comments on GAIN / OIDC).

2.3.  Discovering Feeds

   TBD (comments on URLs / QR Codes).

3.  SCITT Reference REST API

3.1.  Key Binding Confirmation

   In cases where a signed statement is issued by one party and
   registered by another, there is a need to prove possession of key
   material and detect tampering while authenticating both parties.

Birkholz, et al.          Expires 28 July 2024                  [Page 3]
Internet-Draft                   SCRAPI                     January 2024

   Typically a nonce would be chosen by the transparency service and the
   second party would sign over the nonce, when registering the first
   issuer's signed statement.

   In order to avoid interactivity and improve interoperability,
   document describes a non-exclusive, but mandatory to support,
   confirmation scheme

   In this scheme the verifier's challenge is a recent Unix timestamp,
   the presenting party need not request this information from the
   transparency service.

   Here is an example key binding token that can be paired with the
   confirmation claim in a signed statement:

   {
     "iat": 1698077790,
     "aud": "https://transparency.example",
     "nonce": "1698077790"
   }

   When applying registration policies to signed statements with
   confirmation, the transparency service acts as a verifier, and
   performs the following checks:

   1.  verify the integrity of the issuer's signed statement

   2.  confirm the verified content meets the registration policy for
       the transparency service.

   3.  verify the key binding token, using the confirmation claim in the
       verified issuer signed statement

   4.  ensure the key binding token has a nonce that is a string
       representation of a recent Unix timestamp

   The exact window of validity for proving possession is a
   configuration detail of the transparency service.  Unix timestamps
   are used so that only a losely synchronised notion of time need be
   assumed and there is no requirement to account for timezones.

   If the confirmation key is stolen, the attacker can produce key
   binding tokens from that point forward in time.  In an interactive
   confirmation schema, the transparency service can force the
   confirmation key holder to produce a signature over a nonce that is
   not guessable, and this prevents certain attacks related to the
   duration of access to a signing capability and other timing details.
   However, the cost of coordinating with the transparency service,

Birkholz, et al.          Expires 28 July 2024                  [Page 4]
Internet-Draft                   SCRAPI                     January 2024

   coupled with the purpose of registering with a transparency service
   (to obtain a receipt, proving a signed statement was acceptable at a
   point in time) justify specifying the recent timestamp nonce as a
   mandatory to implement context binding.

   In the case that a SCITT transparency service wants to support
   challenges (nonces) that are context binding, the transparency
   service can expose a "challenge token endpoint".

   This endpoint can process request parameters, and issuer a challenge
   token, that future registrations can use to bind to the original
   request.  This interaction model works well for scenarios where
   requirements for a given registration might change over time, but it
   is important for the registering party to commit to acceptable values
   at the time that a signed statement is registered.  These endpoints
   are optional to implement.

3.1.1.  Challenge Endpoint

3.1.1.1.  Request

   GET https://transparency.example/registration/challenge

3.1.1.2.  Response

   *  Header: Content-Type: application/json

   *  (Optional) Header: Retry-After: <seconds>

   *  Query: ?intention={todo}

   *  Body: { "token": "JWT | SD-JWT | base64url( CWT | SD-CWT )>" }

3.1.2.  Registration Endpoint

3.1.2.1.  Request

   POST https://transparency.example/registration

   Headers:

   *  Content-Type: application/cose

   Body: SCITT COSE_Sign1 message

Birkholz, et al.          Expires 28 July 2024                  [Page 5]
Internet-Draft                   SCRAPI                     January 2024

   Note: that the challenge token MUST be present and integrity
   protected when submitting signed statements to this endpoint.  Note:
   this endpoint is a duplicate of POST https://transparency.example/
   entries

3.2.  Messages

   All messages are sent as HTTP GET or POST requests.

   If the Transparency Service cannot process a client's request, it
   MUST return an HTTP 4xx or 5xx status code, and the body SHOULD be a
   JSON problem details object ([RFC7807]) containing:

   *  type: A URI reference identifying the problem.  To facilitate
      automated response to errors, this document defines a set of
      standard tokens for use in the type field within the URN namespace
      of: "urn:ietf:params:scitt:error:".

   *  detail: A human-readable string describing the error that
      prevented the Transparency Service from processing the request,
      ideally with sufficient detail to enable the error to be
      rectified.

   Error responses SHOULD be sent with the Content-Type: application/
   problem+json HTTP header.

   As an example, submitting a Signed Statement with an unsupported
   signature algorithm would return a 400 Bad Request status code and
   the following body:

   {
     "type": "urn:ietf:params:scitt:error:badSignatureAlgorithm",
     "detail": "Signing algorithm not support"
   }

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

Birkholz, et al.          Expires 28 July 2024                  [Page 6]
Internet-Draft                   SCRAPI                     January 2024

   Clients SHOULD treat 500 and 503 HTTP status code responses as
   transient failures and MAY retry the same request without
   modification at a later date.  Note that in the case of a 503
   response, the Transparency Service MAY include a Retry-After header
   field per [RFC7231] 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.

3.2.1.  Register Signed Statement

3.2.1.1.  Request

   POST https://transparency.example/entries

   Headers:

   *  Content-Type: application/cose

   Body: SCITT COSE_Sign1 message

3.2.1.2.  Response

   One of the following:

   *  Status 201 - Registration is successful.

      -  Header Location: <Base URL>/entries/<Entry ID>

      -  Header Content-Type: application/json

      -  Body { "entryId": "<Entry ID"> }

   *  Status 202 - Registration is running.

      -  Header Location: <Base URL>/operations/<Operation ID>

      -  Header Content-Type: application/json

      -  (Optional) Header: Retry-After: <seconds>

      -  Body { "operationId": "<Operation ID>", "status": "running" }

   *  Status 400 - Registration was unsuccessful due to invalid input.

      -  Error code badSignatureAlgorithm

      -  TBD: more error codes to be defined

Birkholz, et al.          Expires 28 July 2024                  [Page 7]
Internet-Draft                   SCRAPI                     January 2024

   If 202 is returned, then clients should wait until Registration
   succeeded or failed by polling the Registration status using the
   Operation ID returned in the response.  Clients should always obtain
   a Receipt as a proof that Registration has succeeded.

3.2.2.  Retrieve Operation Status

3.2.2.1.  Request

   GET https://transparency.example/operations/{operation_id}

3.2.2.2.  Response

   One of the following:

   *  Status 200 - Registration is running

      -  Header: Content-Type: application/json

      -  (Optional) Header: Retry-After: <seconds>

      -  Body: { "operationId": "<Operation ID>", "status": "running" }

   *  Status 200 - Registration was successful

      -  Header: Location: <Base URL>/entries/<Entry ID>

      -  Header: Content-Type: application/json

      -  Body: { "operationId": "<Operation ID>", "status": "succeeded",
         "entryId": "<Entry ID>" }

   *  Status 200 - Registration failed

      -  Header Content-Type: application/json

      -  Body: { "operationId": "<Operation ID>", "status": "failed",
         "error": { "type": "<type>", "detail": "<detail>" } }

      -  Error code: badSignatureAlgorithm

   *  Status 404 - Unknown Operation ID

      -  Error code: operationNotFound

      -  This can happen if the operation ID has expired and been
         deleted.

Birkholz, et al.          Expires 28 July 2024                  [Page 8]
Internet-Draft                   SCRAPI                     January 2024

   If an operation failed, then error details SHOULD be embedded as a
   JSON problem details object in the "error" field.

   If an operation ID is invalid (i.e., it does not correspond to any
   submit operation), a service may return either a 404 or a running
   status.  This is because differentiating between the two may not be
   possible in an eventually consistent system.

3.2.3.  Retrieve Signed Statement

3.2.3.1.  Request

   GET https://transparency.example/entries/{entry_id}

   Query parameters:

   *  (Optional) embedReceipt=true

   If the query parameter embedReceipt=true is provided, then the Signed
   Statement is returned with the corresponding Registration Receipt
   embedded in the COSE unprotected header.

3.2.3.2.  Response

   One of the following:

   *  Status 200.

      -  Header: Content-Type: application/cose

      -  Body: COSE_Sign1

   *  Status 404 - Entry not found.

      -  Error code: entryNotFound

3.2.4.  Retrieve Registration Receipt

3.2.4.1.  Request

   GET https://transparency.example/entries/{entry_id}/receipt

3.2.4.2.  Response

   One of the following:

   *  Status 200.

Birkholz, et al.          Expires 28 July 2024                  [Page 9]
Internet-Draft                   SCRAPI                     January 2024

      -  Header: Content-Type: application/cbor

      -  Body: SCITT_Receipt

   *  Status 404 - Entry not found.

      -  Error code: entryNotFound

   The retrieved Receipt may be embedded in the corresponding COSE_Sign1
   document in the unprotected header.

4.  Privacy Considerations

   TODO

5.  Security Considerations

   TODO

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

   TODO: Register them from here.

6.3.  Well Known URIs

   For discovering scitt configuration.

   TODO: Register them from here.

Birkholz, et al.          Expires 28 July 2024                 [Page 10]
Internet-Draft                   SCRAPI                     January 2024

6.4.  Media Type Registration

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

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

   To indicate that the content is a SCITT Receipt:

   *  Type name: application

   *  Subtype name: 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

Birkholz, et al.          Expires 28 July 2024                 [Page 11]
Internet-Draft                   SCRAPI                     January 2024

   *  Provisional registration?  No

7.  References

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-04, 23
              October 2023, <https://datatracker.ietf.org/doc/html/
              draft-ietf-scitt-architecture-04>.

   [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://doi.org/10.17487/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://doi.org/10.17487/RFC3553>.

   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
              DOI 10.17487/RFC7231, June 2014,
              <https://doi.org/10.17487/RFC7231>.

   [RFC7807]  Nottingham, M. and E. Wilde, "Problem Details for HTTP
              APIs", RFC 7807, DOI 10.17487/RFC7807, March 2016,
              <https://doi.org/10.17487/RFC7807>.

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

7.2.  Informative References

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

Birkholz, et al.          Expires 28 July 2024                 [Page 12]
Internet-Draft                   SCRAPI                     January 2024

   [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://doi.org/10.17487/RFC6838>.

Appendix A.  Attic

   Not ready to throw texts blocks here into the trash bin yet.

Authors' Addresses

   Henk Birkholz
   Fraunhofer SIT
   Rheinstrasse 75
   64295 Darmstadt
   Germany
   Email: henk.birkholz@sit.fraunhofer.de

   Orie Steele
   Transmute
   Email: orie@transmute.industries

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

Birkholz, et al.          Expires 28 July 2024                 [Page 13]