Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

First tranche of CBOR All The Things #38

Merged
merged 14 commits into from
Nov 19, 2024
Merged

First tranche of CBOR All The Things #38

Changes from 2 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
83b0c77
First tranche of CBOR All The Things
Nov 3, 2024
be74955
Fixup RFC references
Nov 3, 2024
a23d3e2
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
14e4458
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
0ac078d
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
a2b340b
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
7b8663d
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
841734a
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
e122b97
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
179c92b
Update draft-ietf-scitt-scrapi.md
JAG-UK Nov 4, 2024
393feea
Add minimal config example
Nov 4, 2024
e363258
A few small nits from the hackathon
Nov 5, 2024
54545f6
Update draft-ietf-scitt-scrapi.md
SteveLasker Nov 12, 2024
3742cc4
Update draft-ietf-scitt-scrapi.md
SteveLasker Nov 19, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
182 changes: 84 additions & 98 deletions draft-ietf-scitt-scrapi.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,6 +51,7 @@ normative:
RFC8615:
RFC9052:
RFC9110:
RFC9290:
RFC9457:
IANA.params:

Expand Down Expand Up @@ -104,21 +105,29 @@ NOTE: '\' line wrapping per {{RFC8792}} in HTTP examples.

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 ({{RFC9457}}) containing:
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:

- type: A URI reference identifying the problem.
- 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 to enable 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:".

- 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.
- response-code: The HTTP error response code relating to this error.

Error responses SHOULD be sent with the `Content-Type: application/problem+cbor` HTTP header.
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

Error responses SHOULD be sent with the `Content-Type: application/problem+json` HTTP header.
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.

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

~~~json
~~~cddl
SteveLasker marked this conversation as resolved.
Show resolved Hide resolved
{
"type": "urn:ietf:params:scitt:error:badSignatureAlgorithm",
"detail": "Signing algorithm not support"
/ title / -1: "Bad Signature Algorithm",
/ detail / -2: "Signing algorithm 'WalnutDSA' not supported.",
/ instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm",
/ response-code / -4: 400,
}
~~~

Expand All @@ -128,7 +137,8 @@ The one exception is the "malformed" error type, which indicates that the Transp
- 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 {{RFC9110}} in order to request a minimum time for the client to wait before retrying the request.

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.

## Mandatory
Expand All @@ -147,54 +157,19 @@ Request:

GET /.well-known/transparency-configuration HTTP/1.1
Host: transparency.example
Accept: application/json
Accept: application/cose
~~~

Response:

~~~ http-message
HTTP/1.1 200 Ok
Content-Type: application/json

{
"issuer": "https://transparency.example",
"registration_endpoint": "https://transparency.example/entries",
"nonce_endpoint": "https://transparency.example/nonce",

"registration_policy": \
"https://transparency.example\
/statements/urn:ietf:params:scitt:statement\
:sha-256:base64url:5i6UeRzg1...qnGmr1o",
Content-Type: application/cose

"supported_signature_algorithms": ["ES256"],
"jwks": {
"keys": [
{
"kid": "urn:ietf:params:oauth:\
jwk-thumbprint:sha-256:DgyowWs04gfVRim5i1WlQ-HFFFKI6Ltqulj1rXPagRo",
"alg": "ES256",
"use": "sig",
"kty": "EC",
"crv": "P-256",
"x": "p-kZ4uOASt9IjQRTrWikGnlbGb-z3LU1ltwRjZaOS9w",
"y": "ymXE1yltJPXgjQSRe9NweN3TLlSUALYZTzy83NVfdg0"
},
{
"kid": "urn:ietf:params:oauth:\
jwk-thumbprint:sha-256:4Fzx5HO1W0ob9CZNc3RJx28Ixpgy9JAFM8jyXKW0ClE",
"alg": "HPKE-Base-P256-SHA256-AES128GCM",
"use": "enc",
"kty": "EC",
"crv": "P-256",
"x": "Vreuil95vzR6ixutgBBf2ota-rj97MvKfuJWB4qqp5w",
"y": "NkUTeaoNlLRRsVRxHGDA-RsA0ex2tSpcd3G-4SmKXbs"
}
]
}
}
<Binary payload>
~~~

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

### Register Signed Statement
Expand Down Expand Up @@ -274,7 +249,7 @@ Location: https://transparency.example/receipts\
/urn:ietf:params:scitt:signed-statement\
:sha-256:base64url:5i6UeRzg1...qnGmr1o

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

{
Expand All @@ -292,55 +267,68 @@ If 202 is returned, then clients should wait until Registration succeeded or fai

#### Status 400 - Invalid Client Request

One of the following errors:
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
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:signed-statement:algorithm-not-supported",
"detail": \
"Signed Statement contained an algorithm that is not supported."
/ title / -1: "Bad Signature Algorithm",
/ detail / -2: "Signed Statement contained an algorithm that is not supported",
/ instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm",
/ response-code / -4: 400,
}
~~~

~~~
HTTP/1.1 400 Bad Request
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:signed-statement:payload-missing",
"detail": \
"Signed Statement payload must be attached (must be present)"
/ 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",
/ response-code / -4: 400,
}
~~~

~~~
HTTP/1.1 400 Bad Request
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:signed-statement:payload-forbidden",
"detail": \
"Signed Statement payload must be detached (must not be present)"
/ title / -1: "Payload Missing",
/ detail / -2: "Signed Statement payload must be 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
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:signed-statement:rejected-by-registration-policy",
"detail": \
"Signed Statement not accepted by the current Registration Policy"
/ 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
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:signed-statement:confirmation-missing",
"detail": \
"Signed Statement did not contain proof of possession"
/ 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,
}
~~~

TODO: other error codes

## Optional Endpoints

The following HTTP endpoints are optional to implement.
Expand Down Expand Up @@ -437,28 +425,6 @@ Payload (in CBOR diagnostic notation)
])
~~~

### Resolve Statement

Authentication SHOULD be implemented for this endpoint.

This endpoint enables Transparency Service APIs to act like Artifact Repositories, and serve `payload` values directly, instead of indirectly through Receipts.

Request:

~~~ http-message
GET /statements/urn...qnGmr1o HTTP/1.1
Host: transparency.example
Accept: application/pdf
~~~

Response:

~~~ http-message
HTTP/1.1 200 Ok
Content-Type: application/pdf
Payload (pdf bytes)
~~~

### Resolve Signed Statement

Authentication SHOULD be implemented for this endpoint.
Expand All @@ -475,6 +441,10 @@ Accept: application/cose

Response:

One of the following:

#### Status 200 - Success

~~~ http-message
HTTP/1.1 200 Ok
Content-Type: application/cose
Expand All @@ -489,6 +459,22 @@ Payload (in CBOR diagnostic notation)
])
~~~

#### 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
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
/ 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,
}
~~~

### Resolve Receipt

Authentication SHOULD be implemented for this endpoint.
Expand Down Expand Up @@ -544,13 +530,13 @@ If the Signed Statement requested is neither registered in the log nor subject t

~~~
HTTP/1.1 404 Not Found
Content-Type: application/json
Content-Type: application/problem+cbor
JAG-UK marked this conversation as resolved.
Show resolved Hide resolved

{
"type": "urn:ietf:params:scitt:error\
:receipt:not-found",
"detail": \
"Signed Statement not known to this Transparency Service."
/ title / -1: "Not Found",
/ detail / -2: "Signed Statement not known to this Transparency Service",
/ instance / -3: "urn:ietf:params:scitt:error:receipt:not-found",
/ response-code / -4: 400,
}
~~~

Expand Down
Loading