[Teep] [Hackathon 2/3] Implementation experience with error handling in TEEP-over-HTTP

[Ken Takayama <[e-mail]>]

Dear TEEP WG,

While implementing a TAM that operates over TEEP-over-HTTP for the
IETF 124 hackathon (and continuing the work toward IETF 125),
I encountered several practical questions related to how error
handling is expected to work in real deployments.

Based on this implementation experience, I would like to share
some observations and implementation patterns that we found useful
when interpreting the current specifications.

The goal of sharing this information is not to suggest protocol
changes, but to document practical implementation experience that
may be helpful for others building systems based on the TEEP
specifications.

Our TAM implementation is available at:
https://github.com/kentakayama/AttesTAM


----------------------------------------------------------------------
Implementation experience
----------------------------------------------------------------------

While implementing a TAM that operates over TEEP-over-HTTP,
I sometimes found it difficult to determine how error handling
was expected to work in practice.

Section 7.1 of the TEEP Protocol already provides some guidance:

"When the ProcessTeepMessage API is invoked, the TAM first does
validation as specified in Section 4.1.2, and drops the message if
it is not valid. It may also do additional implementation specific
actions such as logging the results or attempting to update the
TEEP Agent to a version that does not send invalid messages."

This text clearly indicates that implementations have flexibility
in how they react to invalid messages.

However, during implementation we found that it was often necessary
to define an internal "error taxonomy" mapping concrete failure
conditions to protocol behavior and existing err-code s.

During this process we observed that TEEP provides several mechanisms
that can be used when handling errors, including:

- returning an Update message with an err-code
- retrying the exchange with a new QueryRequest
- sending a SUIT Manifest as part of an Update message
- simply dropping the message

This flexibility is useful, but it can also make it less obvious
which mechanism should be preferred in different situations.

As a result, some implementations may end up handling certain
conditions at the HTTP layer rather than within the TEEP protocol.

Our interpretation of the overall design philosophy of TEEP is that,
whenever possible, protocol-level errors are preferably handled
within the TEEP protocol itself.


----------------------------------------------------------------------
Implementation note: handling protocol-level errors
----------------------------------------------------------------------

During implementation we found it useful to follow an approximate
order of preference when handling protocol-level errors.

One possible implementation pattern was the following:

1. Report the error using a TEEP Update message containing an
   appropriate err-code (and optionally err-msg).

2. If the error condition is temporary, retry the exchange by
   sending another QueryRequest with a new token or challenge.
   Implementations may wish to apply rate limiting when retrying
   exchanges.

3. If the error cannot be handled safely, simply drop the message.
   This behavior is already described in Section 7.1 of the TEEP
   Protocol.

4. Only when the TAM has high confidence that a corrective action
   is appropriate should it attempt recovery actions that modify
   the state of the TEEP Agent, such as sending a SUIT Manifest.

In practice we found it helpful to avoid automatically triggering
device-management operations in response to protocol errors,
since such operations may be destructive or irreversible.


----------------------------------------------------------------------
Implementation note: interaction with HTTP error handling
----------------------------------------------------------------------

When implementing TEEP-over-HTTP, it is also necessary to decide
how HTTP-level error responses should be used.

In our implementation we interpreted the specifications as implying
that most protocol-related errors should preferably be handled
within the TEEP protocol itself, for example by returning an
Update message with an appropriate err-code.

Using HTTP client error responses such as 400 Bad Request,
401 Unauthorized, or 403 Forbidden for protocol-level errors
can be less informative for the TEEP Agent than returning a
protocol-level error response.

The TEEP Protocol also describes the behavior of "dropping"
invalid messages. In the context of TEEP-over-HTTP, we interpreted
this as completing the HTTP exchange without returning a TEEP
message (for example by returning HTTP 204 No Content).

This interpretation may also explain why the current draft
primarily discusses HTTP 5xx responses when describing error
handling behavior.


However, there are still situations where HTTP-level error
responses can be useful, particularly when the request cannot
be processed before TEEP protocol handling begins.

Examples include:

405 Method Not Allowed
  when a request other than POST is received at the TAM endpoint

413 Payload Too Large
  when the request body exceeds limits enforced by the HTTP server

415 Unsupported Media Type
  when the Content-Type or Accept headers are inappropriate
  (already mentioned in Section 6.1)

429 Too Many Requests
  to mitigate excessive retries, loops, or denial-of-service
  conditions


In addition, we were aware that the current draft already mentions
HTTP 5xx responses for situations where the TEEP/HTTP server cannot
obtain a response from the TAM.

In our implementation we therefore decided to use HTTP 5xx responses
specifically for TAM-side failures.

For deployments using the Background Check Model, this includes
situations where the TAM cannot reach the Verifier service.
In such cases our implementation returns:

503 Service Unavailable

to indicate that the request could not be processed because a
required backend service was temporarily unavailable.

For other unexpected failures inside the TAM, we return:

500 Internal Server Error

These choices are implementation-specific but may be useful examples
for others implementing TEEP-over-HTTP systems.

----------------------------------------------------------------------
Conclusion
----------------------------------------------------------------------

The observations above reflect only our implementation experience
while building a TEEP-over-HTTP TAM.

Different deployments may choose different approaches depending
on their architecture and operational requirements.

I hope that sharing this implementation experience may be useful
for others implementing TEEP-based systems.

Best regards,
Ken