Internet-Draft SCRAPI December 2023
Birkholz, et al. Expires 7 June 2024 [Page]
Workgroup:
TBD
Internet-Draft:
draft-birkholz-scitt-scrapi-latest
Published:
Intended Status:
Standards Track
Expires:
Authors:
H. Birkholz
Fraunhofer SIT
O. Steele
Transmute
J. Geater
DataTrails Inc.

SCITT Reference APIs

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

Discussion Venues

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

Source for this draft and an issue tracker can be found at https://github.com/ietf-scitt/draft-birkholz-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."

This Internet-Draft will expire on 7 June 2024.

▲

Table of Contents

1. Introduction

This API definition MAY be exposed externally as part of a suite of APIs, or be encapsulated internally and exposed indirectly via proprietart 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. 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": "The Statement was signed with an unsupported algorithm"
}

Most error types are specific to the type of request and are defined in the respective subsections below. The one exception is the "malformed" error type, which indicates that the Transparency Service could not parse the client's request because it did not comply with this document:

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

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

3.1.1.1. Request 
POST <Base URL>/entries

Headers:

  • Content-Type: application/cose

Body: SCITT COSE_Sign1 message

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

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.1.2. Retrieve Operation Status

3.1.2.1. Request 
GET <Base URL>/operations/<Operation ID>
3.1.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.

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.1.3. Retrieve Signed Statement

3.1.3.1. Request 
GET <Base URL>/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.1.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.1.4. Retrieve Registration Receipt

3.1.4.1. Request 
GET <Base URL>/entries/<Entry ID>/receipt
3.1.4.2. Response

One of the following:

  • Status 200.

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

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

  • 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, , <https://datatracker.ietf.org/doc/html/draft-ietf-scitt-architecture-04>.
[IANA.params]
IANA, "Uniform Resource Name (URN) Namespace for IETF Use", <http://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, , <https://www.rfc-editor.org/rfc/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, , <https://www.rfc-editor.org/rfc/rfc3553>.
[RFC7231]
Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, , <https://www.rfc-editor.org/rfc/rfc7231>.
[RFC7807]
Nottingham, M. and E. Wilde, "Problem Details for HTTP APIs", RFC 7807, DOI 10.17487/RFC7807, , <https://www.rfc-editor.org/rfc/rfc7807>.
[RFC8174]
Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/rfc/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, , <https://www.rfc-editor.org/rfc/rfc2046>.
[RFC6838]
Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, DOI 10.17487/RFC6838, , <https://www.rfc-editor.org/rfc/rfc6838>.

Appendix A. Attic

Not ready to throw these texts into the trash bin yet.

Authors' Addresses

Henk Birkholz
Fraunhofer SIT
Rheinstrasse 75
64295 Darmstadt
Germany
Orie Steele
Transmute
Jon Geater
DataTrails Inc.
United States