Subject: [Anima] Roman Danyliw's No Objection on draft-ietf-anima-grasp-api-08: (with COMMENT)

From: Roman Danyliw via Datatracker <[email-masked]>
Date: Tue, 01 Dec 2020 16:00:12 -0800

Roman Danyliw has entered the following ballot position for
draft-ietf-anima-grasp-api-08: No Objection

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-anima-grasp-api/

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Thank for responding to the SECDIR reviewer and thank you to Joseph Salowey for
performing it.

** Since this is an API spec a few more example pseudo code snippets showing
common ASA “tasks” invoking this API from both sides of the connection (like
Figure 2) would be very helpful.

** More precise references to draft-ietf-anima-grasp might helpful to
implementers (e.g., in Section 2.3.2.3, “… default GRASP_DEF_LOOPCT, see
[I-D.ietf-anima-grasp]” ==> “... see Section 2.6 of [I-d.ietf-anima-grasp]”)

** Section 1.  Per “An ASA runs in an ACP node and therefore inherits all its
security properties, i.e., message integrity, message confidentiality and the
fact that unauthorized nodes cannot join the ACP.”, in the spirit of precise,
things like message integrity and message confidentiality are not properties of
the ASA or of the ACP _node_ but instead properties of the protocol used on the
control plane.

** Section 2.1.  Recommend using consistent terminology.  In this section ASA
call a “GRASP module”.  However, Section 1 lays out an architecture of GRASP
Core + API.

** Section 2.2.  I found the placement of this section confusing.  There is a
discussion of the calling conventions for an API that hasn’t been discussed
yet.  IMO, this should be after Section 2.3.  That said, thanks for describing
these different calling conventions.  Showing these in examples would be very
helpful.

** Section 2.2.2.2.  Per the definition of TTL, is it worth clarifying here and
in the subsequent descriptions that this is an unsigned of a particular size
(unsigned 32-bit at least) per Section 5 of draft-ietf-anima-grasp?

** Section 2.3.2.3.  Is it worth clarifying that loop_count should be between 0
and 255 per Section 5 of the draft-ietf-anima-grasp?

** Section 2.3.2.3.  Provide a normative reference to which version of C and
Python will be used.

** Section 2.3.2.3.  If an older C is used, is “char *name” the right way to
handle a UTF-8 string?

** Section 2.3.2.3. Per the C data structure of an objective, should loop_count
and value_size be unsigned integers of some kind?

** Section 2.3.2.3.  Why does the Python implementation set a default value of
loop_count but C does not?

** Section 2.3.2.3.  Please provide a reference to libcbor

** These examples in C and Python found Section 2.3.2.3 were helpful.  I was
hoping to find them in the other sections.  Also a C-style .h file with
function prototypes and constants would also be nice (e.g., GRASP_DEF_TIMEOUT,
IPPROTO_*, all the error types)

** Section 2.3.4.  Typo. s/tiemout/timeout/

** Section 2.3.2.4.  The constants IPPROTO_TCP and IPPROTO_UDP aren’t defined
here.  Recommend a reference to the grasp draft.

** Section 2.3.7.  Double checking -- per the info input parameter, is the ASA
supposed to provide this content or is this something from GRASP Core?

** Appendix A.  This list doesn’t appear to be a complete crosswalk of function
to error codes to possible APIs.  For example, “NotObj” is listed as a general
error code, but would that get returned by register_asa()?

** Per the GENART Review, IMO, Paul makes a number of good points, in
particular: -- a reference or further explanation of the flow for dry run and
how this would be used in other API calls

-- additional clarifying language on request_negotiate

-- Renaming the “session nonce” to “session handle” (or something like it)
might improve clarity so the API doesn’t have to deal with multiple “nonce”

---

From: Brian E Carpenter <[email-masked]>
Date: Wed, 2 Dec 2020 13:34:09 +1300

Hi Roman,

Thanks. Assuming we get to "New ID needed" we'll
look at all these. One or two quick comments in line.

> https://datatracker.ietf.org/doc/draft-ietf-anima-grasp-api/

We have some of that in draft-ietf-anima-asa-guidelines, which is
still evolving.

> [I-D.ietf-anima-grasp]” ==> “... see Section 2.6 of [I-d.ietf-anima-grasp]”)

Assuming the GRASP spec soon enters AUTH48, we can actually get the
references right.

> ** Section 2.3.2.3.  If an older C is used, is “char *name” the right way to

Dunno. Has there ever been a stable answer to "How do I process strings in C?"
 
> here.  Recommend a reference to the grasp draft.

Yes, I guess that's correct, although the actual values are IANA-assigned
and widely used in the socket API.