https://www.ietf.org/archive/id/draft-ietf-scitt-scrapi-01.html#name-status-202-registration-is-

"If 202 is returned, then clients should wait until Registration succeeded or failed by polling the receipt endpoint using the receipt identifier returned in the response."

I understand that to mean "poll the optional interface defined by 2.2.4 Resolve Receipt".

There are some issues with a request model that mixes "poll for operation a (OP A) completion, with do operation b (OP B)"

1. It forces complexity and mixed state handling on the endpoint implementation. It has to both determine if OP A was extant and is now complete, then it has to follow on and do dependent OP B. Mixed state handling can require that single instance has access to two differently provisioned and permissioned data stores.
2. It forces the same authorization & authentication model on both OP A and OP B. (I will raise a seperate issue for another concerne regading the authentication SHOULD for Resolve Receipt)
3. Implementors will likely want different rate limits for those actions. Checking if an extant operation is complete is light weight and can be designed for "polling clients". Producing a receipts, potentially finalising registration, could be a much heavier load. I would want the ability to seperately rate limit that request.

I very much prefered the previous draft's approach of having a distinct endpoint on which to check for the completion of async registration

          I like the guidance we are giving in this area, but we use an example to define the specific error to return.  

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

Must it be 400 or is that a suggestion?

Originally posted by @roywill in #2 (comment)

The optional API endpoints have intent statements that outline the goal of the Endpoints for example 2.2.1 (Issue Signed Statement Endpoint) has this intent statement:

This endpoint enables a Transparency Service to be an issuer of Signed Statements on behalf of authenticated clients. This supports cases where a client lacks the ability to perform complex cryptographic operations, but can be authenticated and report statements and measurements.

Such a statement is currently missing from both:
2.1.1 (Transparency Configuration) and 2.1.2 (Signed Statement Registration).

I am not sure this is within the scope of the formal working group or better as an "outside" community effort, but with the relocation of this draft into the ietf-wg-scitt org and its upload to datatracker, have we considered having a test suite with sample artifacts, signed statements, and transparent statements that conform to the API spec here as a test harness of sorts? I have seen some IETF and other standard bodies groups making such test suites. I am opening this issue here to gauge interest and determine if making it "inline in this repo" is within scope or not.

The key returned in the example is the identifier of the payload or the signed statement as they are the same HASH. If it is the payload, this precludes simultaneously registering two signed statements simultaneously. I suspect you really want to supply a transaction token not reference anything about the signed statement nor the payload.

If it is truly the receipt, then assuming the HASH can be computed of the final receipt seems a cart before horse statement.

Since this section is talking about registration, why is refresh paradigm left dangling at the end. Is it thought to use this same method to ask for a refresh? I can see getting a new receipt, but that may fail due to the time validity of the signed statement. If you expect it to be based on previous data on the log, then it needs to be indexed based on the previous receipt.

In the case of a government end point, why must client authentication be implemented. The signature on the statement is the authentication for the content and is ultimately who is making a reputation statement.

In 2.1.2. Signed Statement Registration

We have "The Registration Policy for the Transparency Service MUST be applied to the payload bytes, before any additional processing is performed"

This appears to rule out implementations which do async processing of registration statements.

I understood that the combined effect, and intent, of

https://www.ietf.org/archive/id/draft-ietf-scitt-architecture-06.html#name-registration 5. & 7. With the subsequent text

"A Transparency Service MUST ensure that a Signed Statement is registered before releasing its Receipt."

Was to enable the implementation to defer application of registration policies until receipt issuance.

I think, if that is consistent with the intent of the authors intent, a specific requirement along the lines of "Registration policies MUST be applied before issuing a Receipt" would be much clearer

APIs which enables users to find a collection of signed statements based on protected, or unprotected header properties

A client may send any known or custom header property, or combination

TODO:

• Better formated example
• Add paging

Collection of Signed Statement Header Properties
REQUEST:

GET /findstatements?issuer=my-identity.me&subject=my-product-id HTTP/1.1
Host: transparency.example
Accept: application/json

RESPONSE:
a paged collection of references to Signed Statements, and the possible payload locations

{
   "signed-statements": [
      {
         "protected-headers": {
            "cwt_claims": {
               "iss": "my-identity.me",
               "sub": "my-product-id"
            },
            "content_type": "application/json",
            "alg": "1",
            "kid": "abc123",
            "location-hint": "service.storage/abc123",
            "detached-hash": "abc123...321cba"
         },
         "unprotected-headers": {
            "registered": "sometime"
         }
      },
      {
         "protected-headers": {
            "cwt_claims": {
               "iss": "my-identity.me",
               "sub": "my-product-id"
            },
            "content_type": "application/spdx+json",
            "alg": "1",
            "kid": "abc123",
            "location-hint": "service.storage/def456",
            "detached-hash": "def246...642fed"
         },
         "unprotected-headers": {
            "registered": "sometime+1"
         }
      }
   ]
}

Would be great to be able to return an object in addition to or instead of a string for errors. Or allow for other properties which would be fully content-typeable to a custom response object within the error response on claim insert failure.

Lack of this prevents an automated conversation to resolve issues with claim insertion. Human readable strings are great, but ideally a human doesn't even get involved and machines can auto remediate issues due to detailed failure reasoning. This way the a human readable string might only be needed after a failed machine driven insert conversation (more than one call response).

• References
  • ietf-scitt/draft-birkholz-scitt-scrapi#4
    • ietf-wg-scitt/draft-ietf-scitt-architecture#62

see https://www.rfc-editor.org/rfc/rfc5134.html

What is the API to poll for complete work? Can the server then stipulate don't ask for a period of n seconds or not?

Opening this issue to explore:

• Does /signed-statements/issue also register the newly signed statement, or return a signed statement to then be submitted via 2.1.2. Signed Statement Registration?
• What are the properties of a Signed Statement, when signed by the Transparency Service?
  • How does the TS represent it has signed on behalf of the service-authenticated user, meaning are we deferring the signing to be a root CA, where the service is maintaining identity documents for the user? Or, is there some on-behalf of flow?

https://www.ietf.org/archive/id/draft-ietf-scitt-scrapi-01.html#name-resolve-receipt

I don't understand why this is desired:

"Authentication SHOULD be implemented for this endpoint"

If the material in a receipt is, or can be, considered private to the issuer, then this should be a MUST.

Instinctively I have always thought of receipts as essentially public documents. Whilst they are revealing, they are designed to be passed on to other parties.

If the intent is to permit implementations to provide for both public and private receipts, I think that model needs to be spelled out explicitly.

It would seem reasonable to me for Resolve Receipt to provide "the defined public aspects of a receipt" when the request was not authenticated. And the possibly sensitive parts otherwise

In practice, there are definitely usecases for obtaining a receipt for a statement issued by a different party. Its not clear at all to me how or if the authentication requirement here interacts with that.

From: 2.1.2. Signed Statement Registration

If registration succeeds the following identifier MAY be used to refer to the Signed Statement that was accepted

From an outside space, the identifier of the receipt is important to be stable. In the context of a ledger, the indexing into the append only log is not discussed to support any indexing other way.

So the identifier for a Signed Statement is interesting but what is the use case.

The Identifier for the payload is super unclear. There can be multiple signed statements against the same payload, and in the case of a "detached" signatures it is unclear if this is referencing the simple HASH of the artifact or the document holding the HASH.

Are we asserting that the authentication identity to the end point is the identity to sign the content with? I think we need to clarify that this can be completely different. I do question why we need to specify a validFrom date?