From 885132f66aeff25b21711aa5db70a65fb6bb5740 Mon Sep 17 00:00:00 2001 From: Jon Geater Date: Tue, 10 Sep 2024 14:57:41 +0100 Subject: [PATCH 1/5] Add 'chck operation' endpoint Fixes #23 Signed-off-by: Jon Geater --- draft-ietf-scitt-scrapi.md | 96 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 91 insertions(+), 5 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 5912eaa..80abfab 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -270,8 +270,8 @@ Fresh receipts may be requested through the resource identified in the Location ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/receipts\ -/urn:ietf:params:scitt:signed-statement\ +Location: https://transparency.example/operations\ +/urn:ietf:params:scitt:lro\ :sha-256:base64url:5i6UeRzg1...qnGmr1o Content-Type: application/json @@ -279,16 +279,16 @@ Retry-After: { - "identifier": "urn:ietf:params:scitt:receipt\ + "identifier": "urn:ietf:params:scitt:lro\ :sha-256:base64url:5i6UeRzg1...qnGmr1o", } ~~~ -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 will eventually be available for 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 identifier returned in the response. #### Status 400 - Invalid Client Request @@ -341,6 +341,92 @@ One of the following errors: TODO: other error codes +### Check Registration + +Authentication MAY be implemented for this endpoint. + +This endpoint is used to check on 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 +GET /operations/urn:ietf:params:scitt:lro:sha-256:base64url:5i6UeRzg1...qnGmr1o", HTTP/1.1 +Host: transparency.example +Accept: application/json +~~~ + +Response: + +One of the following: + +#### Status 201 - Registration is successful + +~~~ http-message +HTTP/1.1 201 Ok + +Location: https://transparency.example/receipts\ +/urn:ietf:params:scitt:signed-statement\ +:sha-256:base64url:5i6UeRzg1...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 / +]) +~~~ + +The response contains the Receipt for the Signed Statement. +Fresh receipts may be requested through the resource identified in the Location header. + +The Transparency Service MUST maintain a record of every operation until at least one client has fetched the completed receipt. + +The Transparency Service MAY maintain a record of the operation beyond the first successful fetch of the completed receipt. + +#### Status 202 - Registration is (still) running + +~~~ http-message +HTTP/1.1 202 Accepted + +Location: https://transparency.example/operations\ +/urn:ietf:params:scitt:lro\ +:sha-256:base64url:5i6UeRzg1...qnGmr1o + +Content-Type: application/json +Retry-After: + +{ + + "identifier": "urn:ietf:params:scitt:lro\ +:sha-256:base64url:5i6UeRzg1...qnGmr1o", + +} + +~~~ + +The response contains a reference to the running operation which will eventually be available for the Signed Statement. + +If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Check Operation endpoint using the identifier returned in the response. + +#### Status 404 - Operation not found + +~~~ +{ + "type": "urn:ietf:params:scitt:error\ +:lro:not-found", + "detail": \ +"A registration operation with this identifier was not found." +} +~~~ + +No additional reason codes will be given. The identifier may have been valid at a point in time but since redeemed and forgotten; or it may have never existed on this transparency service. + ## Optional Endpoints The following HTTP endpoints are optional to implement. From 4b2586f003d663826021f06a2c5defc55d6817bb Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 10 Sep 2024 07:37:42 -0700 Subject: [PATCH 2/5] Update draft-ietf-scitt-scrapi.md --- 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 80abfab..f591b7d 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -425,7 +425,8 @@ If 202 is returned, then clients should wait until Registration succeeded or fai } ~~~ -No additional reason codes will be given. The identifier may have been valid at a point in time but since redeemed and forgotten; or it may have never existed on this transparency service. +No additional reason codes will be given. +The identifier may have been valid at a point in time but since redeemed and forgotten; or it may have never existed on this Transparency Service. ## Optional Endpoints From ac9af8226c057b38fdeefba712350afeca45f023 Mon Sep 17 00:00:00 2001 From: Steve Lasker Date: Tue, 10 Sep 2024 07:53:17 -0700 Subject: [PATCH 3/5] Update draft-ietf-scitt-scrapi.md --- draft-ietf-scitt-scrapi.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index f591b7d..8e67440 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -398,16 +398,8 @@ Location: https://transparency.example/operations\ /urn:ietf:params:scitt:lro\ :sha-256:base64url:5i6UeRzg1...qnGmr1o -Content-Type: application/json Retry-After: -{ - - "identifier": "urn:ietf:params:scitt:lro\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o", - -} - ~~~ The response contains a reference to the running operation which will eventually be available for the Signed Statement. From 5b74d67ef22c39d59b5bb0c35537cf69d79feee3 Mon Sep 17 00:00:00 2001 From: Jon Geater Date: Tue, 17 Sep 2024 14:53:27 +0100 Subject: [PATCH 4/5] Replace complex identifier with a req ID for LRO Signed-off-by: Jon Geater --- draft-ietf-scitt-scrapi.md | 30 +++++++++++++----------------- 1 file changed, 13 insertions(+), 17 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 8e67440..2d54de2 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -217,7 +217,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {}, / Unprotected Header / + {'request_id': '0123abcd'}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -229,6 +229,8 @@ If the `payload` is detached, the Transparency Service depends on the authentica 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. +The `Unprotected Header` may contain a `request_id` which, if provided, is used for querying long running registrations later. + 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` @@ -256,7 +258,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {}, / Unprotected Header / + {"request_id": "0123abcd"}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -270,24 +272,22 @@ Fresh receipts may be requested through the resource identified in the Location ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations\ -/urn:ietf:params:scitt:lro\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o +Location: https://transparency.example/operations/0123abcd Content-Type: application/json Retry-After: { - - "identifier": "urn:ietf:params:scitt:lro\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o", - + "request_id": "0123abcd", } ~~~ The response contains a reference to the running operation which will eventually be available for the Signed Statement. +If the client supplied a `request_id` then the Transparency Service MUST return the same request_id in the response. +If the client did not supply a `request_id` then the Transparency Service MUST return a locally unique request_id which can be used in subsequent calls to the Check Registration endpoint. + If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Check Operation endpoint using the identifier returned in the response. #### Status 400 - Invalid Client Request @@ -339,8 +339,6 @@ One of the following errors: } ~~~ -TODO: other error codes - ### Check Registration Authentication MAY be implemented for this endpoint. @@ -352,7 +350,7 @@ The following is a non-normative example of a HTTP request the status of a runni Request: ~~~http -GET /operations/urn:ietf:params:scitt:lro:sha-256:base64url:5i6UeRzg1...qnGmr1o", HTTP/1.1 +GET /operations/0123abcd, HTTP/1.1 Host: transparency.example Accept: application/json ~~~ @@ -376,7 +374,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {}, / Unprotected Header / + {"request_id": "0123abcd"}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -394,9 +392,7 @@ The Transparency Service MAY maintain a record of the operation beyond the first ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations\ -/urn:ietf:params:scitt:lro\ -:sha-256:base64url:5i6UeRzg1...qnGmr1o +Location: https://transparency.example/operations/0123abcd Retry-After: @@ -635,7 +631,7 @@ Content-Type: application/json #### 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 asking for receipts too frequently then the Transparency Service MAY, in addition to implementing rate-limiting, return a 429 response: ~~~ HTTP/1.1 429 Too Many Requests From 9ea4f0783945f703898320239fcb9abe642a98a2 Mon Sep 17 00:00:00 2001 From: Jon Geater Date: Tue, 24 Sep 2024 15:07:06 +0200 Subject: [PATCH 5/5] Revert "Replace complex identifier with a req ID for LRO" This reverts commit 5b74d67ef22c39d59b5bb0c35537cf69d79feee3. --- draft-ietf-scitt-scrapi.md | 30 +++++++++++++++++------------- 1 file changed, 17 insertions(+), 13 deletions(-) diff --git a/draft-ietf-scitt-scrapi.md b/draft-ietf-scitt-scrapi.md index 2d54de2..8e67440 100644 --- a/draft-ietf-scitt-scrapi.md +++ b/draft-ietf-scitt-scrapi.md @@ -217,7 +217,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {'request_id': '0123abcd'}, / Unprotected Header / + {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -229,8 +229,6 @@ If the `payload` is detached, the Transparency Service depends on the authentica 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. -The `Unprotected Header` may contain a `request_id` which, if provided, is used for querying long running registrations later. - 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` @@ -258,7 +256,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {"request_id": "0123abcd"}, / Unprotected Header / + {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -272,22 +270,24 @@ Fresh receipts may be requested through the resource identified in the Location ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations/0123abcd +Location: https://transparency.example/operations\ +/urn:ietf:params:scitt:lro\ +:sha-256:base64url:5i6UeRzg1...qnGmr1o Content-Type: application/json Retry-After: { - "request_id": "0123abcd", + + "identifier": "urn:ietf:params:scitt:lro\ +:sha-256:base64url:5i6UeRzg1...qnGmr1o", + } ~~~ The response contains a reference to the running operation which will eventually be available for the Signed Statement. -If the client supplied a `request_id` then the Transparency Service MUST return the same request_id in the response. -If the client did not supply a `request_id` then the Transparency Service MUST return a locally unique request_id which can be used in subsequent calls to the Check Registration endpoint. - If 202 is returned, then clients should wait until Registration succeeded or failed by polling the Check Operation endpoint using the identifier returned in the response. #### Status 400 - Invalid Client Request @@ -339,6 +339,8 @@ One of the following errors: } ~~~ +TODO: other error codes + ### Check Registration Authentication MAY be implemented for this endpoint. @@ -350,7 +352,7 @@ The following is a non-normative example of a HTTP request the status of a runni Request: ~~~http -GET /operations/0123abcd, HTTP/1.1 +GET /operations/urn:ietf:params:scitt:lro:sha-256:base64url:5i6UeRzg1...qnGmr1o", HTTP/1.1 Host: transparency.example Accept: application/json ~~~ @@ -374,7 +376,7 @@ Payload (in CBOR diagnostic notation) 18([ / COSE Sign1 / h'a1013822', / Protected Header / - {"request_id": "0123abcd"}, / Unprotected Header / + {}, / Unprotected Header / null, / Detached Payload / h'269cd68f4211dffc...0dcb29c' / Signature / ]) @@ -392,7 +394,9 @@ The Transparency Service MAY maintain a record of the operation beyond the first ~~~ http-message HTTP/1.1 202 Accepted -Location: https://transparency.example/operations/0123abcd +Location: https://transparency.example/operations\ +/urn:ietf:params:scitt:lro\ +:sha-256:base64url:5i6UeRzg1...qnGmr1o Retry-After: @@ -631,7 +635,7 @@ Content-Type: application/json #### Status 429 -If a client is asking for receipts 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/1.1 429 Too Many Requests