[APPS-REVIEW] Review of draft-ietf-btns-abstract-api-01

["Vijay K. Gurbani" <[e-mail]>]

Dr. Richardson: I was asked by the Applications area to review
draft-ietf-btns-abstract-api-01 and draft-ietf-btns-c-api.  Here is
a review of draft-ietf-btns-abstract-api-01; I will send out a review
of draft-ietf-btns-c-api by the end of this week or early next week.

draft-ietf-btns-abstract-api-01
-------------------------------
This is a valuable document to have for the exact reasons that the
author mentions in S2.  Having dispensed with why such a document
is important, here are more focused comments on the contents of
the draft.  Designing a good and intuitive API is actually very
hard (if you are interested, I can dig up some published literature
on how to do a good enough job in designing one.)

- S3, opening paragraph: s/major kinds of objects/major objects

- S3, opening paragraph: objects are not "abstracted into unique
  opaque tokens" as much as they are *represented* by such constructs.
  I would suggest a rewrite as follows:
   OLD:
      Here we use the term "opaque token" to mean much what "object"
      means in a typical object-oriented programming language, but
      with no public fields (only methods or generic functions).
   NEW:
      The objects are represented by opaque tokens that can be used
      through the public accessor and mutator methods associated with
      the object.

- S3: It is written that, "The API provides a mechanism to query
  the value of attributes of the token."  Do you also provide
  a mechanism to change (or mutate) the state of the object?  Or
  are all operations on the object read-only?  I ask this because
  the Abstract promises that an application may "specify that IPsec
  should be used."  If that is the case, then the application may
  have to use mutators to set the state of the object appropriately.
  And if that is the case, you may want to list the mutators in
  a separate section much as you intend to list accessors in a
  separate section (S9, which is currently empty).

- S3.1: Is the pToken per socket?  In other words, within a process,
  there may be many different sockets.  Does each socket has a unique
  pToken?  It seems from S3.1 that the answer is no; the pToken is
  per process.  However, S5 says in its first paragraph that, "[an
  application] needs to get a protection token that is associated with
  the socket."  Thus, it seems that each socket has a unique pToken.
  You may want to elaborate on this some more to set up the model
  correctly.

- S3.1 says that "It SHOULD always be possible to obtain a current
  protection token for an established connection (whether for a
  connection-oriented transport protocol or for a "connected" UDP
  socket). that is equivalent to any previous protection token
  that was obtained."  A few comments on this.

  First, note the spurious "." after the closing brace; please remove.

  Second, and this goes back to establishing the model of a pToken,
  is the pToken a singleton?  That is, when an application gets the
  current pToken object, does that pToken object correspond to
  the one-and-only pToken object established in that process's space?
  Or is that pToken object a *clone* of the one-and-only pToken
  object (i.e., contents of the objects are the same, but they are
  distinct objects.  Deleting one has no bearing on the other.)

  In software engineering terms, there is the concept of a singleton
  pattern that states that objects with this property are created
  only once within the system.  Whenever an application wants to
  access a singleton object, the system passes a handle to the
  existing one-and-only singleton object to the caller.

  ISTM that a pToken is a singleton object, but then S5 confuses me
  because that seems to lend credence to the fact that there can
  be many pToken objects in a process, each corresponding to a
  socket created by the application.

- S3.3 says that "It is permitted for one protection token to be
  replaced with another (equivalent) protection token due to a node
  moving, suspending and resuming, ..."  This is perplexing, and
  points to the pToken NOT being a singleton object.

  If a node moves, why would the pToken be replaced?  Some
  characteristics -- like the attachment point and network
  identifiers -- may change, but the pToken should remain the same
  object, right?  Likewise, if the node is suspended, then presumably
  the state of the process is saved.  The pToken, as any other
  variable in the system, will be saved and subsequently resurrected
  when the system resumes.  So why is this a special case?  I
  do not understand.

- S4: "All symbols (functions, macros, etc.) defined by this API are
  prefixed with "ipsec_". "  The draft does not specify any APIs
  as such.  So this is probably a place-holder for the future.  If so,
  okay.

- S4: "Specific rules for capitalizations should be driven by the
  specific language binding."  I don't think any modern languages
  mandates capitalization in naming objects, or methods; it is
  purely a syntactic sugar.  You probably want to say instead:

   Specific rules for capitalizations for the identifiers following
   the prefix "ipsec_" should follow the local programming
   conventions.  This draft does not mandate the convention to name
   objects or methods in any way beyond requiring the "ipsec_" prefix.

- S5 says that: As the pToken will not change during the connection.
  (see notes about rekeying).  A simple function is provided to return
  a pToken from a file descriptor.  Many implementions are likely to
  implement this using getsockopt(2), but an interface in those terms
  is not specified in order to keep it more abstract, and therefore
  more portable.

  Some comments on this.

  First, note the gratuitous periods in the first 3 sentences.

  Second, and of more importance, is how do we design such an API?
  One way is to use the getsockopt(2) API that is mentioned and
  its disadvantages.  If a decision is made not to go through this
  route, then something like

      pToken *ipsec_get_ptoken(const int sock);

  could be considered.  The advantage is that this is close enough
  to the Unix system call

      int fileno(FILE *stream);

  that transforms a FILE * object into a file descriptor that the
  legions of *nix programmers would be happy.  For non-*nix
  programmers ... well, they should move to *nix ;-)  Just kidding.
  But seriously, the fileno() function has been in existence for
  so long that it is not tied to *nix platform only.

- S5, fourth paragraph:
  s/received may be received may arrive/received may arrive

- S5, fourth and fifth paragraphs: I am not sure I understand what
  is going on here.  Is it the case that when a peer gets a datagram, it
  also gets some additional data -- the sending peer's pToken --
  as ancillary data?  If so, why would a peer send its pToken, which
  is presumably something to keep secret, to another peer?  I am
  sure you had some reason to put this text in, it is just not
  apparent to the casual reader.

- S6: s/do-not-care values./defaulted accordingly.

- S7: Are these the properties of pToken objects or a pToken object
  template?  The discussion involves default values, which leads
  me to think that they are template values.

- S7, tunnelMode discussion.  Since you have tunnelMode, do you
  also need transportMode?

- S8: Are these the properties of iToken objects or a iToken object
  template?  The discussion involves default values, which leads
  me to think that they are template values.

- S8: s/LEAFOFFAITH/LEAPOFFAITH
  or better yet, LEAP_OF_FAITH; much more readable that way.

- S9, 10, and 11 appear to be place-holders.

- S11: Some things you may want to mention here is what do applications
  do when the IPSec characteristics set by one application are not
  acceptable to others?  Unlike TLS, each application cannot choose
  the specific properties it wants applied to the channel.

  Also, if one application sets the IPSec characteristics, is it a
  problem if another one queries them and sends them to someone else?
  For instance, if the IPSec instance is using a group pre-shared
  key, what happens if one application surreptitiously sends the
  key to a malicious party?  ISTM on a cursory reading that
  certain characteristics of the IPSec connection should not be
  made available to applications even on a read-only basis.

Hope that helps!

- vijay
-- 
Vijay K. Gurbani, Bell Laboratories, Alcatel-Lucent
2701 Lucent Lane, Rm. 9F-546, Lisle, Illinois 60532 (USA)
Email: vkg@{alcatel-lucent.com,bell-labs.com,acm.org}
WWW:   http://www.alcatel-lucent.com/bell-labs
_______________________________________________
APPS-REVIEW mailing list
[e-mail]
https://www.ietf.org/mailman/listinfo/apps-review