Re: [Sat] my (hats off) review of satp-core-02

[Thomas Hardjono <[e-mail]>]

Hi Wes and folks,

The authors of SATP-Core are going through Wes’ comments and making updates on the draft (in the Gitbub repo).

One of the fundamental questions related to SATP-Core draft concerns which messages/APIs are being described in the Core draft.

In Figure 1 of core-02, there is a diagram that describes the three (3) types of APIs (API1, API2 and API3).

For the gateway-to-gateway interactions for the asset transfer, it is API2 that we are concerned about.

However, in looking at the entire core-02 there are parts which concern API1 and API3. For example, Section 5 talks about the Developer URN, Credential profile, Application profile, etc.

These items are not actually communicated in the payloads between gateway G1 and G2 (in the flows described in Section 7, 8 and 9 of core-02).

My question:  should these items be moved to a different document that would deal with the Application-to-Gateway interaction (via API1) and Gateway-to-ResourceServer (via API3) ?

This approach would allow us to focus the SATP-Core document on messages and payloads that concern only the actual asset transfer interactions.


What do folks think?


PS.  Thank you to Wes for a very extensive review. It really helps.



Best
--thomas




From: sat <[e-mail]> on behalf of Wes Hardaker <[e-mail]>
Date: Friday, January 5, 2024 at 7:15 PM
To: [e-mail] <[e-mail]>
Subject: [Sat] my (hats off) review of satp-core-02

I set out to review the current state of the satp-core document with
an eye on "how close are we".  I took a bunch of notes (and took a lot
longer to write them up, sorry).  The following are my notes and
thoughts, but should be taken as if I'm a regular technical
contributor (IE, my SATP chair hat is OFF) -- thus, feel free to tell
me I'm absolutely wrong on some of these points.

The only real "chair" level comment that I feel obligated to make is
that the model (shown in figure 1 and described in 4.3 talks about the
APIs between the gateways and the clients as being "REST APIs".  This
particular part of the model is out of scope of the current charter,
and thus we shouldn't specify that they must be REST based.  Rather,
they're "implementation dependent" at this point.  You can say they
must be implemented in a way that does not disrupt how the SAT
protocol is expected to function though.

Also, note that we'll need IANA registries for some of these values, as well
as a definition for what it takes to add items to the registry.  I can
certainly help with this as we get closer, but it's worth thinking
about now.  (eg: "application/satres" in an existing table)

Also [I'm coming up with more chair comments as I transcribe my
notes], we shouldn't use existing company names in the examples.
Instead, use strings with "example" in them ("example", "example.com",
"network1.example.com", "example1 network", ...)

------

Note: this was a review of -02 specifically

First and foremost, excellent job getting started on this critical
document for the WG.  There is a lot of material in it, and it's a
good solid base.  Having said that, I do find a number of issues that
would likely come up in interoperability tests due to lack of exacting
detail in how things are defined.  Some of these notes below are
simply nits or suggestions, and others are a bit more critical
(especially with an eye toward interoperability).  The rest of this
will sound rather long and detailed with problems, but first please do
note that it's a great start.  I just got out my red pen for
improvements :-)


General notes:

- One thing I find missing the most is the flow diagram indicating the
  message sequences that are expected between the client gateway  and
  the server gateway.  I know this is being worked on heavily (and is
  near done?) but should be included at least in text, if not in
  graphical form.  Depicting the right sequence from section 7 alone
  could be challenging without it.

- In general the JSON descriptions could use improvements.  The IETF
  requires fairly exacting specifications to ensure everyone encodes
  things in the same way.  I encourage you to look at something like
  RFC8620 as a template (JMAP - the JSON based replacement for IMAP).
  Note in particular how section 1 is laid out that spells out how the
  rest of the document should be interpreted, including how all named
  objects have an associated datatype (eg "UnsignedInt").

More specific:

- I do wonder if "API Type 1" and the new identifier design team's use
  of "type 1" will also confuse people at some point.  Because of this
  it's critical to always have some qualifier in front of the "Type N"
  expressions.

- There is some usage of "flows" (eg 4.4) and other times "phases" (eg
  5.1).  It would be best to be consistent with these.

- Section 4.5 is rather terse and the purpose of it is unclear -- it
  needs an intro at least.  Also "authorisation" is misspelled.

- Section 5.2 indicates that SATP is between "applications (clients)"
  and "gateways (servers)".  This is incorrect as it's only gateway to
  gateway, but one gateway is a client in the protocol when it's used.

- Section 5.2 has a bunch of mandatory fields, some of which contain
  spaces and others don't.  The most confusing being "Action/Response"
  -- is this a json field name?  These don't match the format and
  style of the 7.* names.

- Section 5.2 describes a message format, but it's unclear how this
  meshes with Section 7.*.

- The Version field is a good example of underspecified.  How is this
  encoded?  "(major, minor)", "major.minor", "[major, minor]",
  "{'major': major, 'minor': minor}"?  Also this should define the
  first version to be used (1,0?) for this version of the protocol

- 'Message Type': what are legal values and where are they specified?
  If they're later (eg, 7.*, reference this)

- session ID and transfer-context ID - it would be helpful to know
  whether the client or server will be creating these (or both if
  bidirectional values -- but if so, how does one indicate "yours" and
  "mine").

- The resource URL and developer URN are vague in their definition and
  purpose.  Also, a URN is not an "assertion"  -- maybe "an identifier
  string defined by the developer" or similar

- is the sequence number actually needed?  If so, why (if within an
  encapsulated session over TLS, eg)

- I'd suggest looking at existing javascript frameworks for
  authentication (eg, look at what JOSE did here)

- The Payload for POST, responses and local networks -- how will a
  receiver know how to interpret this?  is this dependent on the
  "mesasge type" field?  If so, say this and reference where the
  definitions are.  Also, it's unclear why "local networks" is in
  here.  If we have message types that can be privately specified,
  then we need to be careful how we say this.

- 5.3.1: why is validation just a MAY? if not at least a SHOULD/MUST?

- 5.3.2: what if the gateway doesn't have a real DNS domain?  (we
  *can* require this, but not everyone may want this requirement)

- 5.3.3: Having this be a alphanumeric or hexidecimal value does not
  work well with interoperability.  How do you know what deadbeef is?
  Even "0xdeadbeef" can technically be either.

- 5.3.4 - this format is specific to the sending network?

- 5.3.5 - it would be good to break this example down into the
  components previously described

- 5.4.5 and 5.3.5: it might be best to move the example into the intro
  for the section

- 5.4.1: "any scheme for identifying gateway owners may be
  implemented" -- this does not bode well for interoperability

- 5.4.1: validate wit the issuing authority -- what authority and how
  will I know what the issuing authority is?

- 5.4.3 put a (OU) after the first usage of "Organizational Unit" so
  that it can be used later in 5.4.4.

- 5.5: this is a bit underspecified and unfinished

- 5.6 needs an intro -- this is also where understanding the full
  sequence of steps becomes critical

- 5.6.1: you should specify the minimum version of TLS and leave it at
  that -- the TLS specs already talk about downgrade resistance, etc.
  Just say "TLS 1.3" and be done :-)

- error handling is more generally needed as well.  I know this is
  being worked on, but if nothing else describe at a high level what
  happens when you fail to parse a message and what happens if you
  can't act on it (abort and close the session, eg).  More likely, "if
  after point X" may do something different because the asset was
  burned, eg.

- 7. you might consider just using HTTP POST.  There isn't a great
  benefit to supporting both GET and POST (very much IMHO).  If you do
  use GET it should be really for information retrieval, not for
  "send[ing] messages".

- 7. "the client and server **may**" be required to sign certain
  messages -- IMHO, this needs to be better described exactly when
  this is expected/necessary.

- 7. the note about nonces are not shown is not needed, as you're
  really not showing anything about TLS -- just the encapsulated
  messages.

- 7.1 and beyond: suggest using "parameters" or "fields" instead of
  "artifacts".

- 7.1 and beyond: examples would be highly helpful here (like the one
  in 7.6)

- 7.6 I note that the example in 7.6 doesn't have all the items in
  section 5.2 :-)

- I did not fully review section 7 as too much of my previous comments
  may affect my review depending on how they're handled.

- section 11: IMHO, the errors need to go in a normal section.
  Appendixes are not normative.  (and this is an example of where
  we'll need our own IANA registry table)

- section 14 ("appendix A" which is actually a section anyway):  the
  encoding and usage of these errors is unclear.



--
Wes Hardaker
USC/ISI

--
sat mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/sat