SCITT Reference APIs

2.1.2.1. Status 201 - Registration is successful

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.¶

2.1.2.2. Status 202 - Registration is running

HTTP/1.1 202 Ok

Location: https://transparency.example/receipts\
/urn:ietf:params:scitt:signed-statement\
:sha-256:base64url:5i6UeRzg1...qnGmr1o

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

{

  "receipt": "urn:ietf:params:scitt:receipt\
:sha-256:base64url:5i6UeRzg1...qnGmr1o",

}

The response contains a reference to the receipt 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 receipt endpoint using the receipt identifier returned in the response.¶

2.1.2.3. Status 400 - Invalid Client Request

One of the following errors:¶

{
  "type": "urn:ietf:params:scitt:error\
:signed-statement:algorithm-not-supported",
  "detail": \
"Signed Statement contained an algorithm that is not supported."
}

{
  "type": "urn:ietf:params:scitt:error\
:signed-statement:payload-missing",
  "detail": \
"Signed Statement payload must be attached (must be present)"
}

{
  "type": "urn:ietf:params:scitt:error\
:signed-statement:payload-forbidden",
  "detail": \
"Signed Statement payload must be detached (must not be present)"
}

{
  "type": "urn:ietf:params:scitt:error\
:signed-statement:rejected-by-registration-policy",
  "detail": \
"Signed Statement not accepted by the current Registration Policy"
}

{
  "type": "urn:ietf:params:scitt:error\
:signed-statement:confirmation-missing",
  "detail": \
"Signed Statement did not contain proof of possession"
}

TODO: other error codes¶

4.4.1.1. Denial of service attacks

While denial of service attacks are very hard to defend against completely, and Transparency Services are unlikely to be in the critical path of any safety-liable operation, any attack which could cause the silent failure of Signed Statement registration, for example, should be considered in scope.¶

In principle DoS attacks are easily mitigated by the client checking that the Transparency Service has registered any submitted Signed Statement and returned a Receipt. Since verification of Receipts does not require the involvement of the Transparency Service DoS attacks are not a major issue.¶

Clients to Transparency Services SHOULD ensure that Receipts are available for their registered Statements, either on a periodic or needs-must basis, depending on the use case.¶

Beyond this, implementers of Transparency Services SHOULD implement general good practice around network attacks, flooding, rate limiting etc.¶

4.4.1.2. Eavesdropping

Since the purpose of this API is to ultimately put the message payloads on a Transparency Log there is limited risk to eavesdropping. Nonetheless transparency may mean 'within a limited community' rather than 'in full public', so implementers MUST add protections against man-in-the-middle and network eavesdropping, such as TLS.¶

4.4.1.3. Message modification attacks

While most relevant modification attacks are mitigated by the use of the Issuer signature on the Signed Statement, the Issue Statement endpoint presents an opportunity for manipulation of messages and misrepresentation of Issuer intent that could mislead later Verifiers.¶

Transparency Services offering the Issue Statement endpoint MUST require authentication and transport-level security for that endpoint, MUST NOT modify anything in the message to be signed, and MUST take steps to ensure that the party calling the endpoint is authorized to register statements on behalf of the specified Issuer.¶

4.4.1.4. Message insertion attacks

While most relevant insertion attacks are mitigated by the use of the Issuer signature on the Signed Statement, the Issue Statement endpoint presents an opportunity for insertion of messages and misrepresentation of Issuer intent that could mislead later Verifiers. There are 2 most likely avenues to this attack:¶

• Stolen client endpoint authentication credentials¶

• Stolen or misused Issuer keys held in the Transparency Service on behalf of clients¶

Clients relying on the Issue Statement endpoint SHOULD take steps to ensure their endpoint authentication credentials are securely stored and can be rotated and/or revoked in the case of a breach.¶

Transparency Services offering the Issue Statement endpoint MUST require authentication and transport-level security for that endpoint, and MUST enable the rotation and revocation of those credentials.¶

Transparency Services offering the Issue Statement endpoint MUST take careful steps in both design and operation of their software stack to prevent the theft or inappropriate use of the Issuer keys they use to sign Statements on behalf of Issuers, such as HSMs for storage and least-privilege, regularly refreshed access controls for use.¶

Transparency Services MAY also implement additional protections such as anomaly detection or rate limiting in order to mitigate the impact of any breach.¶

4.4.2.1. Replay attacks

Replay attacks are not particularly concerning for SCITT or SCRAPI: once a statement is made, it is intended to be immutable and non-repudiable, so making it twice should not lead to any particular issues. There could be issues at the payload level (for instance, the statement "it is raining" may true when first submitted but not when replayed), but being payload-agnostic implementations of SCITT services cannot be required to worry about that.¶

If the semantic content of the payload are time dependent and susceptible to replay attacks in this way then timestamps MAY be added to the payload signed by the Issuer.¶

4.4.2.2. Message deletion attacks

Once registered with a Transparency Service, Registered Signed Statements cannot be deleted. Thus, any message deletion attack must occur prior to registration else it is indistinguishable from a man-in-the-middle or denial-of-service attack on this interface.¶