SCITT Reference APIs Draft-ietf-scitt-scrapi-03
draft-ietf-scitt-scrapi-03
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Active".
|
|
|---|---|---|---|
| Authors | Henk Birkholz , Jon Geater | ||
| Last updated | 2025-01-08 (Latest revision 2024-07-08) | ||
| RFC stream | Internet Engineering Task Force (IETF) | ||
| Formats | |||
| Reviews |
HTTPDIR Early review
(of
-01)
by Darrel Miller
On the right track
HTTPDIR IETF Last Call Review due 2026-04-10
Incomplete
|
||
| Additional resources | Mailing list discussion | ||
| Stream | WG state | WG Document | |
| Document shepherd | (None) | ||
| IESG | IESG state | I-D Exists | |
| Consensus boilerplate | Unknown | ||
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-ietf-scitt-scrapi-03
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]