Early Review of draft-ietf-satp-core-00
review-ietf-satp-core-00-httpdir-early-pardue-2023-04-28-00

# High-level comments and caveats of review

The satp WG appears to be relatively recently formed. It is chartered to
develop standards that address interoperability problems in digital asset
networks. This is a technology domain I am not familiar with, so please excuse
review comments that arise because of that.

draft-ietf-satp-core-00 was only adopted to the WG in April 2023. The position
of "Not ready" is, hopefully, not unexpected at such an early point in the
standardization process. However, what is not clear to me, at the outset nor
after review, is whether the document is based on existing industry practice or
if its more of a greenfield solution that is expected to change a lot during
the process. In part, my lack of clarity on this arises from the document
intended status being marked as Informational, which could imply its based on
some external entities documentation. If that's not the case, perhaps an
intended status of Proposed Standard is more appropriate. Either way, the
specification as written has several aspects that leave important
interoperability questions unanswered. That makes me wonder whether there is
implementation activity ongoing in parallel because there's practical issues
that would have to have been solved in order for the interactions to succeed.

I read the entirety of draft-ietf-satp-core-00 in isolation before looking into
the details of the WG or other related documents. This document defines a
protocol for interactions between a number of actors. It dedicates significant
amounts of text to explain the conceptual model, which was appreciated on first
read through. However, only afterwards did I realise that
draft-ietf-satp-architecture-00 exists - its purpose to define a Secure Asset
Transfer interoperability Architecture. There is significant overlap and
duplication between these documents at it was rather surprising not to even see
the protocol spec refer to its architecture. My recommendation is for the
authors of these specifications to collaborate in order to minimise the
duplication,  with one outcome making the protocol specification clearer to
review.

This is an HTTP directorate review, so that's where I have attempted to focus
my review. The document has editorial nits beyond those already mentioned. I
trust the authors will address these in good time and have omitted them from
the review comments.

# What elements of the protocol are HTTP and what aren't?

The overriding sense I have after reading the document a couple of times is
that it isn't clear where HTTP is used in a conventional sense vs. where pieces
of HTTP are being used as a convenience or a crutch. This plays a significant
part in attempting to review it from an HTTP directorate perspective.

In simple terms, my takeaway is that there are a number of stateful
interactions that involve passing JSON-formatted messages between endpoints.
This is framed as three different APIs (Type-1, Type-2, and Type-3). The
specification details the formats of these messages but I found it confusing
how it is intended for those messages to be exchanged between endpoints. One
interpretation, which seems unlikely, is that this is a new application
protocol entirely and that for each API, it is expected for there to be a TCP
connection with TLS atop, and messages are sent over the wire as a stream of
bytes carrying a textual serialization of JSON messages. However, another
interpretation based on section 4.3 is that these are HTTP-based APIs (named as
REST APIs) and so would operate pretty much in that vein.

If we follow the line of HTTP-based APIs, then it would be reasonable to expect
these JSON messages are exchanged as message content. Where my confusion arises
though is because some messages themselves are defined to carry some HTTP
semantics. For instance, Section 5.2 defines the SATP message format for (I
think) the Type-1 API. It contains an "Action/Response" field, described as
"GET/POST and arguments (or Response Code)". This is simultaneously both
restrictive (constrained methods) and incredibly flexible ("arguments" is not
defined anywhere in the document). Defining the means to express HTTP within
JSON this way raises serious concerns about ambiguity, interoperability and
maintenance. It is unclear if this is an attempt to subset HTTP or to support
the full range of HTTP semantics and their extension points. I'm left wondering
why the Type-1 API doesn't just leave HTTP aspects to HTTP proper, and have the
JSON carry the SAT information that is important. Some examples related to this
API might help clarify how it is intended to be used. Perhaps what you're
trying to define is HTTP message encapsulation, whereby an application sends an
instruction (via HTTP) to the local gateway, which decapsulates it and sends it
onwards to the remote gateway - and vice-versa. If that's the case it would be
clearer to say so. And it raises the question about whether you should be
defining your own encapsulation format or seek prior-art in this space.

The other API types don't seem to suffer from similar problems. Section 8.2,
for example, details a Transfer Commence Message, which includes a message type
defined within its own namespace - urn:ietf:satp:msgtype. My reading is that
this is used in API Type-2, the interactions between gateways. The document
illustrates the exchange with an example. This opens other questions, that
affect the whole document, for a few reasons:

* "the client makes the following HTTP request using TLS" - this is common
theme where TLS is mentioned repeatedly. Realistically, the requirement is
probably that interactions need HTTPS, which would allow any suitable version -
HTTP/1.1, HTTP/2, HTTP/3 or whatever might come in the future. This relates to
section 5.6.1, which states "TLS 1.2 or higher MUST be implemented". Requiring
better versions of secure protocol is ok, but there seems a little room for
improvement in this area to make sure it can support breadth and evolution.

* "Authorization: Basic awHCaGRSa3F0MzpnWDFmQmF0M2ZG" - its not clear why this
authorization header is included or how the endpoints arrived at the decision
to use the basic scheme. Is it important?

* "Content-Type: application/x-www-form-urlencoded" - but the POST content is
JSON. Is it really the intention that the SATP messages can be serialized into
either JSON or as query parameters? That's not necessarily a bad thing but it
raises several questions the document should be clearer on. For instance, are
there any interop problems that might arise due to transforms between those
formats?

# Issues within the message formats themselves

I find the "Credential" aspects unclear or underdefined. One message includes a
field called "Credential Profile", elsewhere prose refers to "Credential
Scheme".

"Application Profile" also seems similarly underfined. An example is provided
along with, I presume, example HTTP fields. Its not clear to what parts of the
SAT protocol this would apply. The fields also use an X- prefix, which is
deprecated per RFC 6648.

# Referencing problems

Overall, the document is lacking sufficient references.

There are no internal backward or forward references. For a document that
weighs in at 29 pages, that's going to impact the readability and
comprehension. Some of that problem go away if the authors can dedupulicate
text into the architecture document. However, then there's an even bigger need
to ensure cross-references are in place to aid the reader.

This leads on to the larger problems with the normative and informative
references. There are several normative requirements in the text that relate to
other IETF documents that are not listed as normative references. Most
importantly, from an HTTP perspective, it cites RFC 2616 which is obsolete.
Where HTTP semantics are referenced, RFC 9110 should be used.

RFC 7519 (JSON Web Token) is listed as a normative dependency but doesn't
appear to relate to anything in the text.

# Summary

This seems to be a new draft in a young WG, so it is understandably a bit raw.
There are parts of the document that could make much more clear; I think that
is mostly a straightfoward editorial activity. My comments might be based on
incorrect insights drawn as a result of the current document state. However, if
they remain, there are some fundamental HTTP-related design issues that do need
to be addressed over the long term. For instance, the possibility that this
document is defining a new/custom HTTP encapsulation format is something that
needs deeper discussion and engagement.