From 7e934bdee644f4952bd897bb14bd74c2a88cd6a6 Mon Sep 17 00:00:00 2001 From: Jon Geater Date: Tue, 3 Dec 2024 17:14:12 +0100 Subject: [PATCH 01/24] Refactor all the RegisterSignedStatement workflows Signed-off-by: JAG-UK --- draft-ietf-scitt-scrapi.md | 388 ++++++++++++++++++++++++++----------- 1 file changed, 270 insertions(+), 118 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 7854993..3fd05d6 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -126,7 +126,7 @@ NOTE: SCRAPI is not a CoAP API. Nonetheless Constrained Problem Details objects As an example, submitting a Signed Statement with an unsupported signature algorithm would return a `400 Bad Request` status code and the following body: -~~~cbor-diag +~~~ cbor-diag { / title / -1: "Bad Signature Algorithm", / detail / -2: "Signing algorithm 'WalnutDSA' not supported.", @@ -198,16 +198,22 @@ Fields that are not understood MUST be ignored. Authentication MAY be implemented for this endpoint. See notes on detached payloads below. -This endpoint is used to register a Signed Statement with a Transparency Service. +This endpoint is used to instruct a Transparency Service to register a +Signed Statement on its log. Since typical log implementations take +many seconds or even longer to reach finality this API has an +asynchronous mode which returns a locator which can be used to check +the status of the registration asynchronously. -The following is a non-normative example of a HTTP request to register a Signed Statement: +The following is a non-normative example of a HTTP request to register +a Signed Statement: Request: ~~~http POST /entries HTTP/1.1 Host: transparency.example -Accept: application/json +Accept: application/cbor +Accept: application/cose Content-Type: application/cose Payload (in CBOR diagnostic notation) @@ -219,32 +225,34 @@ Payload (in CBOR diagnostic notation) ]) ~~~ -The Registration Policy for the Transparency Service MUST be applied to the payload bytes, before any additional processing is performed. +The Registration Policy for the Transparency Service MUST be applied +before any additional processing is performed. -If the `payload` is detached, the Transparency Service depends on the authentication context of the client in the Registration Policy. -If the `payload` is attached, the Transparency Service depends on both the authentication context of the client (if present), and the verification of the Signed Statement in the Registration Policy. +If the `payload` is detached, the Transparency Service depends on the +authentication context of the client in the Registration Policy. +If the `payload` is attached, the Transparency Service depends on both +the authentication context of the client (if present), and the +verification of the Signed Statement in the Registration Policy. The details of Registration Policy are out of scope for this document. -If registration succeeds the following identifier MAY be used to refer to the Signed Statement that was accepted: - -`urn:ietf:params:scitt:signed-statement:sha-256:base64url:5i6UeRzg1...qnGmr1o` - -If the `payload` was attached, or otherwise communicated to the Transparency Service, the following identifier MAY be used to refer to the `payload` of the Signed Statement: - -`urn:ietf:params:scitt:statement:sha-256:base64url:5i6UeRzg1...qnGmr1o` - Response: One of the following: #### Status 201 - Registration is successful +In cases where the Transparency Service is able to mint receipts in 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-message -HTTP/1.1 201 Ok +HTTP/1.1 201 Created -Location: https://transparency.example/receipts\ -/urn:ietf:params:scitt:signed-statement\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o +Location: https://transparency.example/entries\ +/67ed41f1de6a...cfc158694ed0befe Content-Type: application/cose @@ -259,32 +267,66 @@ Payload (in CBOR diagnostic notation) ~~~ The response contains the Receipt for the Signed Statement. -Fresh receipts may be requested through the resource identified in the Location header. +Fresh Receipts may be requested through the resource identified in the Location header. #### 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: + +~~~ cbor-diag +{ + / 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 MAY clean up old operation records to manage +practical implementation concerns. The length of validity of the +`OperationID` is Transparency Service specific but at minimum +the Transparency Service MUST maintain a record of every running or +succeeded 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. + ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/receipts\ -/urn:ietf:params:scitt:signed-statement\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o +Location: https://transparency.example/operations\ +/67f89d5f0042e3ad42...35a1f190 Content-Type: application/cbor Retry-After: { - - "identifier": "urn:ietf:params:scitt:receipt\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o", - + / locator / "OperationID": "67f89d5f0042e3ad42...35a1f190", + / status / "Status": "running", } ~~~ -The response contains a reference to the receipt which will eventually be available for the Signed Statement. +The response contains a reference to the running operation which is +attempting to Register the Signed Statement. -If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Resolve Receipt endpoint using the identifier returned in the response. +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. #### Status 400 - Invalid Client Request @@ -350,6 +392,196 @@ application/concise-problem-details+cbor } ~~~ +### 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 a HTTP request the status of a +running registration: + +Request: + +~~~ http-message +GET /operations/67f89d5f0042e3ad42...35a1f190, HTTP/1.1 +Host: transparency.example +Accept: application/cbor +~~~ + +Response: + +One of the following: + +#### 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 which +can be used to 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-message +HTTP/1.1 200 Ok + +Location: https://transparency.example/entries\ +/67ed41f1de6a...cfc158694ed0befe + +Content-Type: application/cbor + +{ + / locator / "EntryID": "67f89d5f0042e3ad42...35a1f190", + / status / "Status": "succeeded", +} +~~~ + +_Failure case_ + +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-message +HTTP/1.1 200 Ok + +Content-Type: application/cbor + +{ + / status / "Status": "failed", + / error / "Error": { + / title / -1: "Bad Signature Algorithm", + / detail / -2: "Signed Statement contained an algorithm that is not supported", + / instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm", + } +} +~~~ + +#### Status 202 - Registration is (still) running + +~~~ http-message +HTTP/1.1 202 Accepted + +Location: https://transparency.example/operations\ +/67f89d5f0042e3ad42...35a1f190 + +Retry-After: + +~~~ + +If 202 is returned, then clients should continue polling the Check +Operation endpoint using the operation identifier. + +#### 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, +} +~~~ + +#### 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, +} +~~~ + +#### 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: + +{ + / title / -1: "Too Many Requests", + / detail / -2: "Only requests per are allowed.", + / instance / -3: "urn:ietf:params:scitt:error:tooManyRequests", + / response-code / -4: 429, +} +~~~ + +### Resolve Receipt + +Authentication SHOULD be implemented for this endpoint. + +Request: + +~~~ http-message +GET entries/67ed41f1de6a...cfc158694ed0befe HTTP/1.1 +Host: transparency.example +Accept: application/cose +~~~ + +Response: + +#### Status 200 + +If the Receipt is found: + +~~~ http-message +HTTP/1.1 200 Ok +Location: https://transparency.example/entries\ +/67ed41f1de6a...cfc158694ed0befe +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 / +]) +~~~ + +#### 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 not known to this Transparency Service", + / instance / -3: "urn:ietf:params:scitt:error:receipt:not-found", + / response-code / -4: 404, +} +~~~ + ## Optional Endpoints The following HTTP endpoints are optional to implement. @@ -455,7 +687,7 @@ This endpoint enables Transparency Service APIs to act like Artifact Repositorie Request: ~~~ http-message -GET /signed-statements/urn...qnGmr1o HTTP/1.1 +GET /signed-statements/9e4f5206fe4bf...ba742bd688a HTTP/1.1 Host: transparency.example Accept: application/cose ~~~ @@ -496,88 +728,6 @@ application/concise-problem-details+cbor } ~~~ -### Resolve Receipt - -Authentication SHOULD be implemented for this endpoint. - -Request: - -~~~ http-message -GET /receipts/urn...qnGmr1o HTTP/1.1 -Host: transparency.example -Accept: application/cose -~~~ - -Response: - -#### Status 200 - -If the Signed Statement requested is already included in the Append-Only Log: - -~~~ http-message -HTTP/1.1 200 Ok -Location: https://transparency.example/receipts/urn...qnGmr1o -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 / -]) -~~~ - -#### Status 202 - -If registration of the Signed Statement requested is in progress but not yet included in the Append-Only Log: - -~~~ http-message -HTTP/1.1 202 Ok -Location: https://transparency.example/receipts/urn...qnGmr1o -Content-Type: application/json -Retry-After: - -{ - "receipt": "urn:ietf:params:scitt:receipt\ - :sha-256:base64url:5i6UeRzg1...qnGmr1o", -} -~~~ - -#### Status 404 - -If the Signed Statement requested is neither registered in the log nor subject to an in-progress registration: - -~~~ -HTTP/1.1 404 Not Found -application/concise-problem-details+cbor - -{ - / 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, -} -~~~ - -#### 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/json -Retry-After: - -{ - "type": "urn:ietf:params:scitt:error\ - :receipt:too-many-requests", - "detail": \ - "Too Many Requests. Only requests per are allowed." -} -~~~ - #### Eventual Consistency For all responses additional eventually consistent operation details MAY be present. @@ -585,11 +735,11 @@ Support for eventually consistent Receipts is implementation specific, and out o ### Exchange Receipt -This endpoint is used to exchange old or expiring receipts for fresh ones. +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. +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. +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. Authentication SHOULD be implemented for this endpoint. @@ -612,11 +762,13 @@ Payload (in CBOR diagnostic notation) #### Status 200 -A new receipt: +A new Receipt: ~~~ http-message HTTP/1.1 200 Ok -Location: https://transparency.example/receipts/urn...qnGmr1o +Location: https://transparency.example/entries\ +/67ed41f1de6a...cfc158694ed0befe + Content-Type: application/cose Payload (in CBOR diagnostic notation) @@ -806,7 +958,7 @@ Thus, any message deletion attack must occur prior to registration else it is in # TODO -TODO: Consider negotiation for receipt as "JSON" or "YAML". +TODO: Consider negotiation for Receipt as "JSON" or "YAML". TODO: Consider impact of media type on "Data URIs" and QR Codes. # IANA Considerations From 166bbbeecc166e573cc6e2eecb5355a968f742b2 Mon Sep 17 00:00:00 2001 From: Jon Geater Date: Tue, 10 Dec 2024 16:22:50 +0100 Subject: [PATCH 02/24] Re-order RP language following review Signed-off-by: JAG-UK --- draft-ietf-scitt-scrapi.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 3fd05d6..e992031 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -225,9 +225,6 @@ Payload (in CBOR diagnostic notation) ]) ~~~ -The Registration Policy for the Transparency Service MUST be applied -before any additional processing is performed. - If the `payload` is detached, the Transparency Service depends on the authentication context of the client in the Registration Policy. If the `payload` is attached, the Transparency Service depends on both @@ -235,6 +232,9 @@ the authentication context of the client (if present), and the verification of the Signed Statement in the Registration Policy. The details of Registration Policy are out of scope for this document. +The Registration Policy for the Transparency Service MUST be applied +before any additional processing is performed. + Response: One of the following: From 0b44e5cf508ca5c8d66ed7f2fe6c48c2acac26ef Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:38:49 -0800 Subject: [PATCH 03/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index e992031..3a92b19 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -204,8 +204,7 @@ many seconds or even longer to reach finality this API has an asynchronous mode which returns a locator which can be used to check the status of the registration asynchronously. -The following is a non-normative example of a HTTP request to register -a Signed Statement: +The following is a non-normative example of an HTTP request to register a Signed Statement: Request: From 3031e17b4cf92a64c9ace0c540e5d092b481e206 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:40:33 -0800 Subject: [PATCH 04/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 3a92b19..7ba8b63 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -224,11 +224,8 @@ Payload (in CBOR diagnostic notation) ]) ~~~ -If the `payload` is detached, the Transparency Service depends on the -authentication context of the client in the Registration Policy. -If the `payload` is attached, the Transparency Service depends on both -the authentication context of the client (if present), and the -verification of the Signed Statement in the Registration Policy. +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 details of Registration Policy are out of scope for this document. The Registration Policy for the Transparency Service MUST be applied From 52e73fe4e7a63b8682ff03139a58375eb56c8e27 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:40:56 -0800 Subject: [PATCH 05/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 7ba8b63..6064dcd 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -198,11 +198,8 @@ Fields that are not understood MUST be ignored. Authentication MAY be implemented for this endpoint. See notes on detached payloads below. -This endpoint is used to instruct a Transparency Service to register a -Signed Statement on its log. Since typical log implementations take -many seconds or even longer to reach finality this API has an -asynchronous mode which returns a locator which can be used to check -the status of the registration asynchronously. +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: From 9d33dcce981b20e699f6f4133ee24403e08f7a3e Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:47:46 -0800 Subject: [PATCH 06/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 1 - 1 file changed, 1 deletion(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 6064dcd..c5ab1bd 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -223,7 +223,6 @@ Payload (in CBOR diagnostic notation) 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 details of Registration Policy are out of scope for this document. The Registration Policy for the Transparency Service MUST be applied before any additional processing is performed. From 7bafe931fbe8c464715c89337e654e619dd9a565 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:49:31 -0800 Subject: [PATCH 07/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index c5ab1bd..a26937b 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -263,10 +263,7 @@ Fresh Receipts may be requested through the resource identified in the Location #### 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 +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: ~~~ cbor-diag From 495340762b5c5b7af9da2ca93b7439e71fea581c Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:49:54 -0800 Subject: [PATCH 08/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index a26937b..ef683d0 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -281,8 +281,7 @@ example: 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. +If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. Transparency Services MAY clean up old operation records to manage practical implementation concerns. The length of validity of the From 888975c5477eb14755f102664f972664dcefad55 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:52:40 -0800 Subject: [PATCH 09/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index ef683d0..90177ef 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -283,15 +283,10 @@ returned it. If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. -Transparency Services MAY clean up old operation records to manage -practical implementation concerns. The length of validity of the -`OperationID` is Transparency Service specific but at minimum -the Transparency Service MUST maintain a record of every running or -succeeded 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. +Transparency Services MAY clean up old operation records to manage practical implementation concerns. +The length of validity of the `OperationID` is Transparency Service specific but at minimum, 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. ~~~ http-message HTTP/1.1 202 Accepted From a588ccaab05506639e5e99dc578cb6bdf62ae95b Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:53:18 -0800 Subject: [PATCH 10/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 90177ef..de515cd 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -224,8 +224,8 @@ Payload (in CBOR diagnostic notation) 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 is performed. +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: From 485a0a2c31e5561550249c94762639c11910fe16 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:53:50 -0800 Subject: [PATCH 11/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index de515cd..4020e2d 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -233,12 +233,9 @@ One of the following: #### Status 201 - Registration is successful -In cases where the Transparency Service is able to mint receipts in a -reasonable time, it may return the receipt directly. +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. +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-message HTTP/1.1 201 Created From ed298406b55edd8f9632592af007c04f62672be3 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 10:54:28 -0800 Subject: [PATCH 12/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 4020e2d..e32d31e 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -260,8 +260,7 @@ Fresh Receipts may be requested through the resource identified in the Location #### 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: +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: ~~~ cbor-diag { From 22d46685dba74e8b770caf84cd4048a601f2c29b Mon Sep 17 00:00:00 2001 From: steve lasker Date: Tue, 31 Dec 2024 11:44:05 -0800 Subject: [PATCH 13/24] MD and idnits formatting changes Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 218 +++++++++++++++++++++---------------- 1 file changed, 125 insertions(+), 93 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index e32d31e..e03f41a 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -128,9 +128,12 @@ As an example, submitting a Signed Statement with an unsupported signature algor ~~~ cbor-diag { - / title / -1: "Bad Signature Algorithm", - / detail / -2: "Signing algorithm 'WalnutDSA' not supported.", - / instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm", + / title / -1: \ + "Bad Signature Algorithm", + / detail / -2: \ + "Signing algorithm 'WalnutDSA' not supported.", + / instance / -3: \ + "urn:ietf:params:scitt:error:badSignatureAlgorithm", / response-code / -4: 400, } ~~~ @@ -155,14 +158,14 @@ Authentication SHOULD NOT be implemented for this endpoint. This endpoint is used to discover the capabilities and current configuration of a transparency service implementing this specification. -The Transparency Service responds with a dictionary of configuration elements. These elements are Transparency-Service specific. +The Transparency Service responds with a dictionary of configuration elements. +These elements are Transparency-Service specific. Contents of bodies are informative examples only. Request: ~~~ http-message - GET /.well-known/transparency-configuration HTTP/1.1 Host: transparency.example Accept: application/cose @@ -176,17 +179,17 @@ 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 dict - "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 placeholder +18([ ; COSE_Sign1 structure with tag 18 + h'44A123BEEFFACE', ; Protected header (example bytes) + {}, ; Unprotected header + { ; Payload - CBOR dict + "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:5i6U...mr1o" + }, + h'ABCDEF1234567890ABCDEF1234567890' ; Signature placeholder ]) ~~~ @@ -270,8 +273,9 @@ In cases where the registration request is accepted but the Transparency Service ~~~ `Status` must be one of the following: -* "running" - the operation is still in progress -* "succeeded" - the operation succeeded and the Receipt is ready + +- "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 @@ -297,7 +301,6 @@ Retry-After: / locator / "OperationID": "67f89d5f0042e3ad42...35a1f190", / status / "Status": "running", } - ~~~ The response contains a reference to the running operation which is @@ -309,64 +312,87 @@ succeeded or failed by polling the Check Operation endpoint using the #### Status 400 - Invalid Client Request -The following expected errors are defined. Implementations MAY return other errors, so long as they are valid {{RFC9290}} objects. +The following expected errors are defined. +Implementations MAY return other errors, so long as they are valid {{RFC9290}} objects. -~~~ +~~~ http-message HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { - / title / -1: "Bad Signature Algorithm", - / detail / -2: "Signed Statement contained an algorithm that is not supported", - / instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm", + / 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-message 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", + / 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-message HTTP/1.1 400 Bad Request application/concise-problem-details+cbor { - / 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", + / 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-message 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", + / 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-message 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", + / 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, } ~~~ @@ -377,8 +403,7 @@ 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 a HTTP request the status of a -running registration: +The following is a non-normative example of an HTTP request for the status of a running registration: Request: @@ -396,16 +421,11 @@ One of the following: _Success case_ -If the operation is complete and it _succeeded_, the Transparency -Service returns a `status` of "succeeded" along with a locator which -can be used to fetch the Receipt. +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. +`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. +If the `EntryID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. ~~~ http-message HTTP/1.1 200 Ok @@ -423,9 +443,7 @@ Content-Type: application/cbor _Failure case_ -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. +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-message HTTP/1.1 200 Ok @@ -435,9 +453,12 @@ Content-Type: application/cbor { / status / "Status": "failed", / error / "Error": { - / title / -1: "Bad Signature Algorithm", - / detail / -2: "Signed Statement contained an algorithm that is not supported", - / instance / -3: "urn:ietf:params:scitt:error:badSignatureAlgorithm", + / title / -1: \ + "Bad Signature Algorithm", + / detail / -2: \ + "Signed Statement contained a non supported algorithm", + / instance / -3: \ + "urn:ietf:params:scitt:error:badSignatureAlgorithm", } } ~~~ @@ -451,18 +472,16 @@ Location: https://transparency.example/operations\ /67f89d5f0042e3ad42...35a1f190 Retry-After: - ~~~ -If 202 is returned, then clients should continue polling the Check -Operation endpoint using the operation identifier. +If 202 is returned, then clients should continue polling the Check Operation endpoint using the operation identifier. #### Status 400 - Invalid Client Request -The following expected errors are defined. Implementations MAY return -other errors, so long as they are valid {{RFC9290}} objects. +The following expected errors are defined. +Implementations MAY return other errors, so long as they are valid {{RFC9290}} objects. -~~~ +~~~ http-message HTTP/1.1 400 Bad Request application/concise-problem-details+cbor @@ -479,33 +498,37 @@ application/concise-problem-details+cbor If no record of the specified running operation is found, the Transparency Service returns a 404 response. -~~~ +~~~ http-message 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", + / 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, } ~~~ #### 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: +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-message HTTP/1.1 429 Too Many Requests Content-Type: application/concise-problem-details+cbor Retry-After: { - / title / -1: "Too Many Requests", - / detail / -2: "Only requests per are allowed.", - / instance / -3: "urn:ietf:params:scitt:error:tooManyRequests", + / title / -1: \ + "Too Many Requests", + / detail / -2: \ + "Only requests per are allowed.", + / instance / -3: \ + "urn:ietf:params:scitt:error:tooManyRequests", / response-code / -4: 429, } ~~~ @@ -549,14 +572,18 @@ Payload (in CBOR diagnostic notation) If there is no Receipt found for the specified `EntryID` the Transparency Service returns a 404 response: -~~~ +~~~ http-message HTTP/1.1 404 Not Found application/concise-problem-details+cbor { - / title / -1: "Not Found", - / detail / -2: "Receipt with entry ID not known to this Transparency Service", - / instance / -3: "urn:ietf:params:scitt:error:receipt:not-found", + / title / -1: \ + "Not Found", + / detail / -2: \ + "Receipt with entry ID not known \ + to this Transparency Service", + / instance / -3: \ + "urn:ietf:params:scitt:error:receipt:not-found", / response-code / -4: 404, } ~~~ @@ -574,7 +601,7 @@ This supports cases where a client lacks the ability to perform complex cryptogr Request: -~~~http +~~~ http-message POST /signed-statements/issue HTTP/1.1 Host: transparency.example Accept: application/json @@ -586,11 +613,13 @@ Payload "dataLicense": "CC0-1.0", "SPDXID": "SPDXRef-DOCUMENT", "name": "cli-app 0.1.2", - "documentNamespace": "https://spdx.org/spdxdocs/sbom-tool-2.2.7-38f61e97-e53c-46ef-a37d-62.../cli-app/0.1.2/0d06adf8a36...", + "documentNamespace": \ + "https://spdx.org/spdxdocs/\ + sbom-tool-2.2.7-38f6.../cli-app/0.1.2/0d06...", "creationInfo": { "created": "2024-08-16T21:44:54Z", "creators": [ - "Organization: contoso" + "Organization: acme" ] }, "files": [ @@ -613,10 +642,11 @@ Payload { "referenceCategory": "PACKAGE-MANAGER", "referenceType": "purl", - "referenceLocator": "pkg:swid/contoso/spdx.org/cli-app@0.1.2?tag_id=ac073d0f-0aa7-4d27-87fa-7f..." + "referenceLocator": \ + "pkg:swid/acme/spdx.org/cli-app@0.1.2?tag_id=ac07..." } ], - "supplier": "Organization: contoso", + "supplier": "Organization: acme", "hasFiles": [ "SPDXRef-File--..." ] @@ -693,16 +723,20 @@ 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. +The following expected errors are defined. +Implementations MAY return other errors, so long as they are valid {{RFC9290}} objects. -~~~ +~~~ http-message 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", + / 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, } ~~~ @@ -771,7 +805,6 @@ The following is a non-normative example of a HTTP request for the Issuer Metada Request: ~~~ http-message - GET /.well-known/issuer/tenant/1234 HTTP/1.1 Host: transparency.example Accept: application/json @@ -789,7 +822,7 @@ Content-Type: application/json "keys": [ { "kid": "urn:ietf:params:oauth\ -:jwk-thumbprint:sha-256:DgyowWs04gfVRim5i1WlQ-HFFFKI6Ltqulj1rXPagRo", + :jwk-thumbprint:sha-256:Dgyo...agRo", "alg": "ES256", "use": "sig", "kty": "EC", @@ -799,7 +832,7 @@ Content-Type: application/json }, { "kid": "urn:ietf:params:oauth\ -:jwk-thumbprint:sha-256:4Fzx5HO1W0ob9CZNc3RJx28Ixpgy9JAFM8jyXKW0ClE", + :jwk-thumbprint:sha-256:4Fzx...0ClE", "alg": "HPKE-Base-P256-SHA256-AES128GCM", "use": "enc", "kty": "EC", @@ -823,7 +856,6 @@ Client holding signed statements that require demonstrating proof of possession Request: ~~~ http-message - GET /nonce HTTP/1.1 Host: transparency.example Accept: application/json @@ -925,7 +957,7 @@ Transparency Services MAY also implement additional protections such as anomaly #### 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. +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. @@ -946,7 +978,7 @@ TODO: Consider impact of media type on "Data URIs" and QR Codes. 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}}: -~~~output +~~~ output Registry name: scitt Specification: [RFCthis] Repository: http://www.iana.org/assignments/scitt From 2f97c5834b4e32bfbbabb3405e114c15b57314c9 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Tue, 31 Dec 2024 11:48:08 -0800 Subject: [PATCH 14/24] MD wrapping Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 13 ++++--------- 1 file changed, 4 insertions(+), 9 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index e03f41a..29ffde3 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -303,12 +303,9 @@ Retry-After: } ~~~ -The response contains a reference to the running operation which is -attempting to Register the Signed Statement. +The response contains a reference to the running operation which is attempting to Register the Signed Statement. -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. +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. #### Status 400 - Invalid Client Request @@ -495,8 +492,7 @@ application/concise-problem-details+cbor #### Status 404 - Operation Not Found -If no record of the specified running operation is found, the -Transparency Service returns a 404 response. +If no record of the specified running operation is found, the Transparency Service returns a 404 response. ~~~ http-message HTTP/1.1 404 Not Found @@ -569,8 +565,7 @@ Payload (in CBOR diagnostic notation) #### Status 404 -If there is no Receipt found for the specified `EntryID` the -Transparency Service returns a 404 response: +If there is no Receipt found for the specified `EntryID` the Transparency Service returns a 404 response: ~~~ http-message HTTP/1.1 404 Not Found From 23df7c93064a9d1b9d27929de382b3f1c4e9f5a1 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 12:37:14 -0800 Subject: [PATCH 15/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 29ffde3..a6e0ec3 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -284,7 +284,7 @@ returned it. If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. Transparency Services MAY clean up old operation records to manage practical implementation concerns. -The length of validity of the `OperationID` is Transparency Service specific but at minimum, the Transparency Service MUST maintain a record of every running or successful operation until at least one client has fetched the completed Receipt. +The length of validity of the `OperationID` is Transparency Service specific, but at a minimum, 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. From 65c0497b68861348dcb0eecbc9d11ca6bf498bba Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 12:40:34 -0800 Subject: [PATCH 16/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index a6e0ec3..33b7d57 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -291,8 +291,7 @@ The Transparency Service MAY include a `Retry-After` header in the HTTP response ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations\ -/67f89d5f0042e3ad42...35a1f190 +Location: https://transparency.example/operations/67f8...f190 Content-Type: application/cbor Retry-After: From a2fc1a9f9421d28ed8ffeb93094a7d5eed27bc09 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 31 Dec 2024 12:40:48 -0800 Subject: [PATCH 17/24] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 33b7d57..0438267 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -277,9 +277,7 @@ In cases where the registration request is accepted but the Transparency Service - "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. +`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. From 391c954860c4d4922664b08ff41c04e1eb9b11af Mon Sep 17 00:00:00 2001 From: steve lasker Date: Tue, 31 Dec 2024 13:33:23 -0800 Subject: [PATCH 18/24] A few more shortened uris Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 14 +++++--------- 1 file changed, 5 insertions(+), 9 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 0438267..654a89f 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -424,8 +424,7 @@ If the `EntryID` is a valid URL, it MAY be included as a `Location` header in th ~~~ http-message HTTP/1.1 200 Ok -Location: https://transparency.example/entries\ -/67ed41f1de6a...cfc158694ed0befe +Location: https://transparency.example/entries/67ed...befe Content-Type: application/cbor @@ -462,8 +461,7 @@ Content-Type: application/cbor ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations\ -/67f89d5f0042e3ad42...35a1f190 +Location: https://transparency.example/operations/67f8...f190 Retry-After: ~~~ @@ -546,8 +544,7 @@ If the Receipt is found: ~~~ http-message HTTP/1.1 200 Ok -Location: https://transparency.example/entries\ -/67ed41f1de6a...cfc158694ed0befe +Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose Payload (in CBOR diagnostic notation) @@ -688,7 +685,7 @@ This endpoint enables Transparency Service APIs to act like Artifact Repositorie Request: ~~~ http-message -GET /signed-statements/9e4f5206fe4bf...ba742bd688a HTTP/1.1 +GET /signed-statements/9e4f...688a HTTP/1.1 Host: transparency.example Accept: application/cose ~~~ @@ -771,8 +768,7 @@ A new Receipt: ~~~ http-message HTTP/1.1 200 Ok -Location: https://transparency.example/entries\ -/67ed41f1de6a...cfc158694ed0befe +Location: https://transparency.example/entries/67ed...befe Content-Type: application/cose From 7824536281dcc5fd78885b2a31c20dc344df3dd2 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 2 Jan 2025 09:48:29 -0800 Subject: [PATCH 19/24] Update draft-ietf-scitt-scrapi.md Co-authored-by: A.J. Stein (Unofficial) --- draft-ietf-scitt-scrapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 654a89f..235a97b 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -281,7 +281,7 @@ In cases where the registration request is accepted but the Transparency Service If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. -Transparency Services MAY clean up old operation records to manage practical implementation concerns. +Transparency Services do not guarantee retention of operation IDs for a period of time or the entirety of its lifecycle. A Transparency MAY delete operation records and some operation IDs lookups MAY return error XYZ at one time even though they were valid in the past. The length of validity of the `OperationID` is Transparency Service specific, but at a minimum, 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. From 2987f70ad64b41095450bbbf5e26be4e41237300 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Thu, 2 Jan 2025 09:56:55 -0800 Subject: [PATCH 20/24] Update draft-ietf-scitt-scrapi.md Co-authored-by: A.J. Stein (Unofficial) --- draft-ietf-scitt-scrapi.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 235a97b..5b3c210 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -300,7 +300,7 @@ Retry-After: } ~~~ -The response contains a reference to the running operation which is attempting to Register the Signed Statement. +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. From dab6d692960465939fb771853dd91fc9b7b24d77 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 3 Jan 2025 09:42:45 -0800 Subject: [PATCH 21/24] Merge cleanup from github UX Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 19 +------------------ 1 file changed, 1 insertion(+), 18 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 1afd459..bdb6258 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -60,6 +60,7 @@ normative: IANA.params: informative: + I-D.draft-demarco-oauth-nonce-endpoint: Nonce-Endpoint I-D.draft-ietf-oauth-sd-jwt-vc: SD-JWT-VC RFC2046: RFC6838: @@ -734,24 +735,6 @@ application/concise-problem-details+cbor / response-code / -4: 404, ~~~ -#### 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/json -Retry-After: - -{ - "type": "urn:ietf:params:scitt:error\ - :receipt:too-many-requests", - "detail": \ - "Too Many Requests.\ - Only requests per are allowed." -} -~~~ - #### Eventual Consistency For all responses additional eventually consistent operation details MAY be present. From 45ca4d6b1cdd15671f7a8615d1c37470542660bd Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 3 Jan 2025 09:45:54 -0800 Subject: [PATCH 22/24] Merge cleanup from github UX Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index bdb6258..f5318b1 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -289,7 +289,8 @@ In cases where the registration request is accepted but the Transparency Service If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. -Transparency Services do not guarantee retention of operation IDs for a period of time or the entirety of its lifecycle. A Transparency MAY delete operation records and some operation IDs lookups MAY return error XYZ at one time even though they were valid in the past. +Transparency Services do not guarantee retention of operation IDs for a period of time or the entirety of its lifecycle. +A Transparency MAY delete operation records and some operation IDs lookups MAY return error XYZ at one time even though they were valid in the past. The length of validity of the `OperationID` is Transparency Service specific, but at a minimum, 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. From a69ee7123dd003344866cdc690620f30e74d2a90 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 3 Jan 2025 10:03:15 -0800 Subject: [PATCH 23/24] Change CBOR Dict reference to CBOR map Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index f5318b1..56f9dce 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -167,7 +167,7 @@ The following HTTP endpoints are mandatory to implement to enable conformance to This endpoint is used to discover the capabilities and current configuration of a transparency service implementing this specification. -The Transparency Service responds with a dictionary of configuration elements. +The Transparency Service responds with a CBOR map of configuration elements. These elements are Transparency-Service specific. Contents of bodies are informative examples only. @@ -191,7 +191,7 @@ Payload (in CBOR diagnostic notation) 18([ ; COSE_Sign1 structure with tag 18 h'44A123BEEFFACE', ; Protected header (example bytes) {}, ; Unprotected header - { ; Payload - CBOR dict + { ; Payload - CBOR map "issuer": "https://transparency.example", "base_url": "https://transparency.example/v1/scrapi", "oidc_auth_endpoint": "https://transparency.example/auth", From 9c8fd24422e0b45b1c64197259f0accfb589f194 Mon Sep 17 00:00:00 2001 From: steve lasker Date: Fri, 3 Jan 2025 10:08:54 -0800 Subject: [PATCH 24/24] Finish up tweak to A.J.'s suggestion after merging main Signed-off-by: steve lasker --- draft-ietf-scitt-scrapi.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 56f9dce..175385a 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -289,9 +289,10 @@ In cases where the registration request is accepted but the Transparency Service If the `OperationID` is a valid URL, it MAY be included as a `Location` header in the HTTP response. -Transparency Services do not guarantee retention of operation IDs for a period of time or the entirety of its lifecycle. -A Transparency MAY delete operation records and some operation IDs lookups MAY return error XYZ at one time even though they were valid in the past. -The length of validity of the `OperationID` is Transparency Service specific, but at a minimum, the Transparency Service MUST maintain a record of every running or successful operation until at least one client has fetched the completed Receipt. +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.