An Abstract Application Layer Interface to Transport Services
draft-ietf-taps-interface-26

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

IANA has completed its review of draft-ietf-taps-interface-25, which is currently in Last Call (we've also previously reviewed -20 and -22), and has the following comments:

We understand that this document doesn't require any registry actions.

While it's often helpful for a document's IANA Considerations section to remain in place upon publication even if there are no actions, if the authors strongly prefer to remove it, we do not object.

If this assessment is not accurate, please respond as soon as possible.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Sr. Specialist

The following Last Call announcement was sent out (ends 2024-03-01):

From: The IESG
To: IETF-Announce
CC: anna.brunstrom@kau.se, draft-ietf-taps-interface@ietf.org, taps-chairs@ietf.org, taps@ietf.org, zahed.sarker.ietf@gmail.com
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (An Abstract Application Layer Interface to Transport Services) to Proposed Standard


The IESG has received a request from the Transport Services WG (taps) to
consider the following document: - 'An Abstract Application Layer Interface
to Transport Services'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2024-03-01. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document describes an abstract application programming
  interface, API, to the transport layer that enables the selection of
  transport protocols and network paths dynamically at runtime.  This
  API enables faster deployment of new protocols and protocol features
  without requiring changes to the applications.  The specified API
  follows the Transport Services architecture by providing
  asynchronous, atomic transmission of messages.  It is intended to
  replace the BSD sockets API as the common interface to the transport
  layer, in an environment where endpoints could select from multiple
  network paths and potential transport protocols.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-taps-interface/

This draft is going for a 2nd IETF last call due to the changes resulted during the IESG evaluation. A diff towards the -20 version of this document should show the changes since the previous IETF last call.


No IPR declarations have been submitted directly on this I-D.

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

[Ballot comment]
Thank you to Sean Turner for the SECDIR review.

Thank you for the iteration on my DISCUSS position and the efforts to refine the document in response.  I want to acknowledge the significant effort required to produce https://github.com/ietf-tapswg/api-drafts/pull/1463.  My recommendation would be to merge it as it improves -24.

I am abstaining on this document because there is a degree of specificity in the abstract API in this document that I cannot reconcile with proposed standard status.  I would expect to be able to do some basic, repeatable degree of conformance evaluation to understand if a concrete API meets what is described in this abstract API – put more simply, how would I know I have an “API to Transport Services”. Focusing just on the security aspects of the API, I struggled to envision how to do that.

To summarize my DISCUSS feedback, it isn’t clear which classes of security parameters require concrete implementation from the abstract API.

The subsequent PR improved the editorial presentation (much appreciated!), but the following text created further ambiguity:

  The set of security parameters defined here is not exhaustive, but illustrative.
  Implementations SHOULD expose an equivalent to the parameters listed below to allow for
  sufficient configuration of security parameters, but the details are expected
  to vary based on platform and implementation constraints.

If this text and parameters are “illustrative”, they are examples.  What conformance is required for the concrete security API if only examples are provided?  How does one unambiguously agree on equivalence relative to examples? 

If “implementations SHOULD expose”, that means that they can choose not to and still be conformant which degenerates into very little normative guidance around the security aspects of the API.

==[ DISCUSS feedback on -24 ]==
Thanks for the revised text in v-22, -23 and -24.  I’m still do not understanding what exact Security Parameters that Section 6.3.1 is normatively specifying (and which of them are examples).  My confusion is that Section 6.2 has a crisp list of parameters with an explicit names, type, and default value.  The equivalent is not present for the security related parameters.

Section 6.3 says “except as noted below, as with the rest of the Transport Services API, exact names of parameters and/or values of enumerations (e.g., ciphersuites) used in the security parameters are system and implementation specific, and ought to be chosen to follow the principle of least surprise for users of the platform / language environment in question.”  How does one read “except when noted below”?  Is this section saying the normative parameters are server-certificate, client-certificate, pinned-server-certificate, alpn, supported-group, ciphersuite, signature-algorithm, max-cached-sessions, cached-session-lifetime-seconds, pre-shared-key OR that “an API should define certificate bundles, certificate chains for pinned certificates, ALPN, session cache management parameters, supported groups/ciphersuite/ parameters, and PSK parameters but no further details are provided here beyond naming these categories of parameters”? 

I observe that the guidance in Section 4.1 suggests that parameter names are in CamelCase.  That isn’t used here (e.g., “server-certificate” should be “ServerCertificate”).  This might hint that there are not parameters here.  However, the bulleted list in Section 6.3.1. is prefaced with “Security configuration parameters and sample usage follow:” seems to suggest that these are concrete parameters.
==[ DISCUSS ]==

[Ballot discuss]
Thanks for the revised text in v-22, -23 and -24.  I’m still do not understanding what exact Security Parameters that Section 6.3.1 is normatively specifying (and which of them are examples).  My confusion is that Section 6.2 has a crisp list of parameters with an explicit names, type, and default value.  The equivalent is not present for the security related parameters.

Section 6.3 says “except as noted below, as with the rest of the Transport Services API, exact names of parameters and/or values of enumerations (e.g., ciphersuites) used in the security parameters are system and implementation specific, and ought to be chosen to follow the principle of least surprise for users of the platform / language environment in question.”  How does one read “except when noted below”?  Is this section saying the normative parameters are server-certificate, client-certificate, pinned-server-certificate, alpn, supported-group, ciphersuite, signature-algorithm, max-cached-sessions, cached-session-lifetime-seconds, pre-shared-key OR that “an API should define certificate bundles, certificate chains for pinned certificates, ALPN, session cache management parameters, supported groups/ciphersuite/ parameters, and PSK parameters but no further details are provided here beyond naming these categories of parameters”? 

I observe that the guidance in Section 4.1 suggests that parameter names are in CamelCase.  That isn’t used here (e.g., “server-certificate” should be “ServerCertificate”).  This might hint that there are not parameters here.  However, the bulleted list in Section 6.3.1. is prefaced with “Security configuration parameters and sample usage follow:” seems to suggest that these are concrete parameters.

[Ballot comment]
I'm abstaining on this document, because I disagree that
Proposed Standard is appropriate. This document (and its companion)
outline an extremely intricate design without going into the - in
my opinion - necessary details to fully explain all aspects. I
appreciate that the WG intends this to be an "abstract API" that
therefore can be described at a higher level of abstraction, but
that is IMO exactly why PS is not a suitable RFC status here -
we won't be able to determine implementation conformance and hence
interoperability to this spec. If the intend is to publish an API
as a PS, it would IMO need to be described at a level where that is
feasible.

[Ballot comment]
I'm likely to abstain on this document, because I disagree that
Proposed Standard is appropriate. This document (and its companion)
outline an extremely intricate design without going into the - in
my opinion - necessary details to fully explain all aspects. I
appreciate that the WG intends this to be an "abstract API" that
therefore can be described at a higher level of abstraction, but
that is IMO exactly why PS is not a suitable RFC status here -
we won't be able to determine implementation conformance and hence
interoperability to this spec. If the intend is to publish an API
as a PS, it would IMO need to be described at a level where that is
feasible.

[Ballot comment]
I updated my discuss items to non-blocking comments. I'm still a bit concerned that some security items are not fully addressed by the API or its Security Considerations. Resolving my comments would make the document a bit more clear and useful I think.


I'm not sure that the model really expands from netflows to IP flows (or TOR) in the future.

I'm not sure the Security Considerations warn enough about re-using the same credentials with different protocols/auth mechanisms.
(eg TLS and IKEv2, or TLS 1.2 and QUIC, or using RSA as RSA-PKCS1.5 as well as RSA-PSS)

Unqualified Hostname vs FQDN seems a security risk punted mostly to the application.

I don't understand this code:

        Connection := Preconnection.Initiate()
        Connection2 := Connection.Clone()

        Connection -> Ready<>
        Connection2 -> Ready<>

        //---- Ready event handler for any Connection C begin ----
        C.Send(messageDataRequest)

Where does "C" come from in "C.Send" ? The comment says "any Connection C"?

I have a question on this code:

        Preconnections are reusable after being used to initiate a
        Connection, whether this Connection was closed or not. Hence, it
        would be correct to continue as follows after the above example:

        //.. carry out adjustments to the Preconnection, if desired
        Connection := Preconnection.Initiate()

What would happen here? I can imagine a "compiler" turning this into
a noop.  I can also see it would kill the existing Connection state and
start a new one. This could be to a different IP address (eg if the DNS
name has A and AAAA). When starting a new one, what would happen to any
Message or Event queues for Connection ?

        Preconnection.AddRemote(RemoteCandidates)

Should this not technically be:

        Preconnection.AddRemote([]RemoteCandidates)

as the array contains at least a host and a stun server candidate?

Maybe this is just the difference between you using the variable you define
that has been assigned, versus a more C like prototype format, eg:

        Preconnection := NewPreconnection([]LocalEndpoint,

So I guess if your example here had set LocalEndpoint := [a,b] you would not
have used [] in the call ?


Section 6.1.4

Perhaps it would be useful to add a Local Endpoint with ephemeral port before
the Local Endpoint with static port example, as the ephemeral port should be
the far more common case. Right now the examples might give the wrong impression
a local port MUST be specified.

SecurityParameters.Set() seems to allow to set our identiy and our certificate,
but not the remote peer's identity or certificate? For example, one might want
to pin a remote certificate and not just rely on a WithHostname() identifier
being present as subjectAltname on a certificate.


      The Connection state, which can be one of the following:
        Establishing, Established, Closing, or Closed.

I think the text in Section 8 should more clearly show the property names if the
goal is to have different implementations use the identical name. Eg in this case,
why not write: The Connection state ("state"). The next two entries are similarly
lacking a clear keyword to use:

        Whether the Connection can be used to send data.

        Whether the Connection can be used to receive data.

eg. why not define words for these to implementations will use the same words,
in this case perhaps ReadySend and ReadyRcv ?
Writing that now, perhaps "state" should be "State" then ?

Section 8.1.1:

        If this property is an Integer

It is best to define the actual type in this document and not let implementations
choose, if the goal is to try and harmonize implementations. I also see no non-integer
value being given here ?

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

[Ballot discuss]
[updated for -24, although I feel most of my questions have not been discussed yet]

- netflows vs IP flows?

Is TAPS only meant for flows or does it also support IP transport.
I don't see an example that would embody "setup a connection to 192.0.1.1 port
80, but require IPsec. I guess it could be added, eg a WithVPN("IPsec") or
something, but I'm not sure you can specify credentials without those being
interpreted to be for the port 80 in this example ? Is this specifically out
of scope, or just not (yet) specified?

Related, lets say you want to only use a flow if it goes over TOR, I guess one
could introduce a WithTOR() transport requirement. I'm a bit concerned that
without an IANA registry for functions, this might cause conflicts in the future.

- single credentials for multiple protocols?

Does this document cause encouraging of re-using of key pairs for
different protocols (eg TLS and IKEv2, or TLS 1.2 and QUIC). This
might have security implications (eg using RSA as RSA-PKCS1.5 as
well as RSA-PSS)

- Hostname vs FQDN

Can WithHostname be unqualified? (God I hope not!)
If not, can the call WithHostname be renamed to WithFQDN ?
If it can be unqualified, how does one deal with credentials
and identifiers, eg with a 'search domain' containing multiple
domains, RemoteSpecifier.WithHostname("mail") could end up on
either mail.example.com or mail.example.net (or heaven forbid,
the .mail TLD)

It seems a little text is added that says "RECOMMENDED to not use unqualified",
but that raises the question on why even support it? It's just too
dangerous imho.

- WithPort and WithService, but not WithProtocol

How does one choose their syslog service transport protocol, since syslog
over udp and tcp are valid and both have the same service name? Or does
WithService accept values like "514/udp" ?

- ALPN

I don't see a WithALPN method for setting the ALPN.
- Preconnection vs Listener

[Ballot comment]

        It is not necessary for an application to handle all events;
        some events may have implementation-specific default handlers. The
        application should not assume that ignoring events (e.g., errors)
        is always safe.

What is "ignoring events" vs "having a default handler for events" ? Wouldn't
default handlers be handled outside the application, and thus not trigger an
event towards the application? So that applications "ignoring events" would
be unrelated to "implementation-specific default handlers"? Perhaps the last
sentence should just start in a new paragraph to indicate these two things
are separate unrelated notes?

        SecurityParameters.Set(identity, myIdentity)

I assume myIdentity would be an array of Type and Value? Eg type=fqdn or type=RDN ?


I don't understand this code:

        Connection := Preconnection.Initiate()
        Connection2 := Connection.Clone()

        Connection -> Ready<>
        Connection2 -> Ready<>

        //---- Ready event handler for any Connection C begin ----
        C.Send(messageDataRequest)

Where does "C" come from in "C.Send" ? The comment says "any Connection C"?

I have a question on this code:

        Preconnections are reusable after being used to initiate a
        Connection, whether this Connection was closed or not. Hence, it
        would be correct to continue as follows after the above example:

        //.. carry out adjustments to the Preconnection, if desired
        Connection := Preconnection.Initiate()

What would happen here? I can imagine a "compiler" turning this into
a noop.  I can also see it would kill the existing Connection state and
start a new one. This could be to a different IP address (eg if the DNS
name has A and AAAA). When starting a new one, what would happen to any
Message or Event queues for Connection ?

        Preconnection.AddRemote(RemoteCandidates)

Should this not technically be:

        Preconnection.AddRemote([]RemoteCandidates)

as the array contains at least a host and a stun server candidate?

Maybe this is just the difference between you using the variable you define
that has been assigned, versus a more C like prototype format, eg:

        Preconnection := NewPreconnection([]LocalEndpoint,

So I guess if your example here had set LocalEndpoint := [a,b] you would not
have used [] in the call ?


Section 6.1

        An Endpoint object can be configured with the following identifiers:
        * Hostname (string):

This starts with listing endpoint identifiers with types (eg string and 16-bit
integers) but then stops specifying their types further down. I guess WithService(),
WithIPAddress() and WithInterface take a (string)

Section 6.1.4

Perhaps it would be useful to add a Local Endpoint with ephemeral port before
the Local Endpoint with static port example, as the ephemeral port should be
the far more common case. Right now the examples might give the wrong impression
a local port MUST be specified.


SecurityParameters.Set() seems to allow to set our identiy and our certificate,
but not the remote peer's identity or certificate? For example, one might want
to pin a remote certificate and not just rely on a WithHostname() identifier
being present as subjectAltname on a certificate.

        If security is opportunistic, it will allow Connections without
        transport security, but will still attempt to use security
        if available.

I assume what is meant is "but will still attempt to use unauthenticated security
if available" ?

      The Connection state, which can be one of the following:
        Establishing, Established, Closing, or Closed.

I think the text in Section 8 should more clearly show the property names if the
goal is to have different implementations use the identical name. Eg in this case,
why not write: The Connection state ("state"). The next two entries are similarly
lacking a clear keyword to use:

        Whether the Connection can be used to send data.

        Whether the Connection can be used to receive data.

eg. why not define words for these to implementations will use the same words,
in this case perhaps ReadySend and ReadyRcv ?
Writing that now, perhaps "state" should be "State" then ?

Section 8.1.1:

        If this property is an Integer

It is best to define the actual type in this document and not let implementations
choose, if the goal is to try and harmonize implementations. I also see no non-integer
value being given here ?

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

[Ballot discuss]

- netflows vs IP flows?

Is TAPS only meant for flows or does it also support IP transport.
I don't see an example that would embody "setup a connection to 192.0.1.1 port
80, but require IPsec. I guess it could be added, eg a WithVPN("IPsec") or
something, but I'm not sure you can specify credentials without those being
interpreted to be for the port 80 in this example ? Is this specifically out
of scope, or just not (yet) specified?

Related, lets say you want to only use a flow if it goes over TOR, I guess one
could introduce a WithTOR() transport requirement. I'm a bit concerned that
without an IANA registry for functions, this might cause conflicts in the future.

- single credentials for multiple protocols?

Does this document cause encouraging of re-using of key pairs for
different protocols (eg TLS and IKEv2, or TLS 1.2 and QUIC). This
might have security implications (eg using RSA as RSA-PKCS1.5 as
well as RSA-PSS)

- identity and server-certificate forces same use over different protocols?

The current API kind of forces re-use of credentials for different protocols, eg:

SecurityParameters.Set(server-certificate, myCertificate)

        // Specifying a Remote Endpoint is optional when using Listen
        Preconnection := NewPreconnection(LocalSpecifier,
                                  TransportProperties,
                                  SecurityParameters)

Let's say that a server only supports TLS 1.2 with RSA-PKCS-1.5 and TLS
1.3 with RSASSA-PSS. We shouldn't use 1 RSA key from 1 certificate for
these two different RSA operations. Would this mean we could never tell
the TAPS API "TLS 1.2 or 1.3 is fine". Maybe that is okay and we should
pick an keypair that works the same in 1.2 and 1.3, but we don't know
what the future will hold.

If we could set multiple identities, TAPS could pick the appropriate one.
eg:
        SecurityParameters.Set(identity, myIdentity)
        SecurityParameters.Set(server-certificate, []myCertificate)

(and possibly multiple identities too?)

- Hostname vs FQDN

Can WithHostname be unqualified? (God I hope not!)
If not, can the call WithHostname be renamed to WithFQDN ?
If it can be unqualified, how does one deal with credentials
and identifiers, eg with a 'search domain' containing multiple
domains, RemoteSpecifier.WithHostname("mail") could end up on
either mail.example.com or mail.example.net (or heaven forbid,
the .mail TLD)

- WithPort and WithService, but not WithProtocol

How does one choose their syslog service transport protocol, since syslog
over udp and tcp are valid and both have the same service name? Or does
WithService accept values like "514/udp" ?

- ALPN

I don't see a WithALPN method for setting the ALPN.
- Preconnection vs Listener

The arch document talks about Preconnection, Connection and Listener
but this document in Section 3 places Listener as a Preconnection.

[Ballot comment]
- Camelcase vs Dromedariescase

Why is it RemoteSpecifier.WithHostname and not RemoteSpecifier.WithHostName,
while it is RemoteSpecifier.WithIPAddress and not RemoteSpecifier.WithIPaddress ?

        String: Instances are represented in a way that is common to
        the programming language, e.g. UTF-8.

Why doesn't it define this just like the other basic types?
eg: "Instances are represented in UTF-8"
Also, how would that work for things like DNS (Ulabel vs Alabel)


        IP Address: An IPv4 or IPv6 address.

Maybe reference RFC5952 ?


        It is not necessary for an application to handle all events;
        some events may have implementation-specific default handlers. The
        application should not assume that ignoring events (e.g., errors)
        is always safe.

What is "ignoring events" vs "having a default handler for events" ? Wouldn't
default handlers be handled outside the application, and thus not trigger an
event towards the application? So that applications "ignoring events" would
be unrelated to "implementation-specific default handlers"? Perhaps the last
sentence should just start in a new paragraph to indicate these two things
are separate unrelated notes?

        SecurityParameters.Set(identity, myIdentity)

I assume myIdentity would be an array of Type and Value? Eg type=fqdn or type=RDN ?


I don't understand this code:

        Connection := Preconnection.Initiate()
        Connection2 := Connection.Clone()

        Connection -> Ready<>
        Connection2 -> Ready<>

        //---- Ready event handler for any Connection C begin ----
        C.Send(messageDataRequest)

Where does "C" come from in "C.Send" ? The comment says "any Connection C"?

I have a question on this code:

        Preconnections are reusable after being used to initiate a
        Connection, whether this Connection was closed or not. Hence, it
        would be correct to continue as follows after the above example:

        //.. carry out adjustments to the Preconnection, if desired
        Connection := Preconnection.Initiate()

What would happen here? I can imagine a "compiler" turning this into
a noop.  I can also see it would kill the existing Connection state and
start a new one. This could be to a different IP address (eg if the DNS
name has A and AAAA). When starting a new one, what would happen to any
Message or Event queues for Connection ?

What is "credentials" (especially because previously we have myCertificate,
so it is unclear if this now contains myKey and if so, where in the previous
example myKey was conveyed to TAPS.

        Preconnection.AddRemote(RemoteCandidates)

Should this not technically be:

        Preconnection.AddRemote([]RemoteCandidates)

as the array contains at least a host and a stun server candidate?

Maybe this is just the difference between you using the variable you define
that has been assigned, versus a more C like prototype format, eg:

        Preconnection := NewPreconnection([]LocalEndpoint,

So I guess if your example here had set LocalEndpoint := [a,b] you would not
have used [] in the call ?


Section 4.1:

        For the purposes of this document, these names are alphanumeric strings

Is there another purpose? If it is outside this document, why does this document
care? Does it try to set a standard here to ensure interoperable names? Maybe
just remove the "For the purposes of this document," ?

        Vendor or implementation specific properties MUST use a string
        identifying the vendor or implementation as the Namespace

What if Vendor Foo has a non-standard tcp property MagicSmoke? Does it go
under tcp.Foo.MagicSmoke or under Foo.tcp.MagicSmoke or something else?

Section 6.1

        An Endpoint object can be configured with the following identifiers:
        * Hostname (string):

This starts with listing endpoint identifiers with types (eg string and 16-bit
integers) but then stops specifying their types further down. I guess WithService(),
WithIPAddress() and WithInterface take a (string)

Section 6.1.4

Perhaps it would be useful to add a Local Endpoint with ephemeral port before
the Local Endpoint with static port example, as the ephemeral port should be
the far more common case. Right now the examples might give the wrong impression
a local port MUST be specified.


SecurityParameters.Set() seems to allow to set our identiy and our certificate,
but not the remote peer's identity or certificate? For example, one might want
to pin a remote certificate and not just rely on a WithHostname() identifier
being present as subjectAltname on a certificate.

        If security is opportunistic, it will allow Connections without
        transport security, but will still attempt to use security
        if available.

I assume what is meant is "but will still attempt to use unauthenticated security
if available" ?

      The Connection state, which can be one of the following:
        Establishing, Established, Closing, or Closed.

I think the text in Section 8 should more clearly show the property names if the
goal is to have different implementations use the identical name. Eg in this case,
why not write: The Connection state ("state"). The next two entries are similarly
lacking a clear keyword to use:

        Whether the Connection can be used to send data.

        Whether the Connection can be used to receive data.

eg. why not define words for these to implementations will use the same words,
in this case perhaps ReadySend and ReadyRcv ?
Writing that now, perhaps "state" should be "State" then ?

Section 8.1.1:

        If this property is an Integer

It is best to define the actual type in this document and not let implementations
choose, if the goal is to try and harmonize implementations. I also see no non-integer
value being given here ?

      A higher value reflects a higher priority.

This is uncommon in IETF protocols. Normally priority is down with lower numbers
being higher priority. Why reverse it here?




NITS:

Wouldn't the American spelling be "rendezvouzing" instead of "rendezvousing" :-)

[Ballot discuss]
[ this review is still incomplete, but I wanted to at least file what I have here ]

- netflows vs IP flows?

Is TAPS only meant for flows or does it also support IP transport.
I don't see an example that would embody "setup a connection to 192.0.1.1 port
80, but require IPsec. I guess it could be added, eg a WithVPN("IPsec") or
something, but I'm not sure you can specify credentials without those being
interpreted to be for the port 80 in this example ? Is this specifically out
of scope, or just not (yet) specified?

Related, lets say you want to only use a flow if it goes over TOR, I guess one
could introduce a WithTOR() transport requirement. I'm a bit concerned that
without an IANA registry for functions, this might cause conflicts in the future.

- single credentials for multiple protocols?

Does this document cause encouraging of re-using of key pairs for
different protocols (eg TLS and IKEv2, or TLS 1.2 and QUIC). This
might have security implications (eg using RSA as RSA-PKCS1.5 as
well as RSA-PSS)

- identity and server-certificate forces same use over different protocols?

The current API kind of forces re-use of credentials for different protocols, eg:

SecurityParameters.Set(server-certificate, myCertificate)

        // Specifying a Remote Endpoint is optional when using Listen
        Preconnection := NewPreconnection(LocalSpecifier,
                                  TransportProperties,
                                  SecurityParameters)

Let's say that a server only supports TLS 1.2 with RSA-PKCS-1.5 and TLS
1.3 with RSASSA-PSS. We shouldn't use 1 RSA key from 1 certificate for
these two different RSA operations. Would this mean we could never tell
the TAPS API "TLS 1.2 or 1.3 is fine". Maybe that is okay and we should
pick an keypair that works the same in 1.2 and 1.3, but we don't know
what the future will hold.

If we could set multiple identities, TAPS could pick the appropriate one.
eg:
        SecurityParameters.Set(identity, myIdentity)
        SecurityParameters.Set(server-certificate, []myCertificate)

(and possibly multiple identities too?)

- Hostname vs FQDN

Can WithHostname be unqualified? (God I hope not!)
If not, can the call WithHostname be renamed to WithFQDN ?
If it can be unqualified, how does one deal with credentials
and identifiers, eg with a 'search domain' containing multiple
domains, RemoteSpecifier.WithHostname("mail") could end up on
either mail.example.com or mail.example.net (or heaven forbid,
the .mail TLD)

- WithPort and WithService, but not WithProtocol

How does one choose their syslog service transport protocol, since syslog
over udp and tcp are valid and both have the same service name? Or does
WithService accept values like "514/udp" ?

- ALPN

I don't see a WithALPN method for setting the ALPN.
- Preconnection vs Listener

The arch document talks about Preconnection, Connection and Listener
but this document in Section 3 places Listener as a Preconnection.

[Ballot comment]
- Camelcase vs Dromedariescase

Why is it RemoteSpecifier.WithHostname and not RemoteSpecifier.WithHostName,
while it is RemoteSpecifier.WithIPAddress and not RemoteSpecifier.WithIPaddress ?

        String: Instances are represented in a way that is common to
        the programming language, e.g. UTF-8.

Why doesn't it define this just like the other basic types?
eg: "Instances are represented in UTF-8"
Also, how would that work for things like DNS (Ulabel vs Alabel)


        IP Address: An IPv4 or IPv6 address.

Maybe reference RFC5952 ?


        It is not necessary for an application to handle all events;
        some events may have implementation-specific default handlers. The
        application should not assume that ignoring events (e.g., errors)
        is always safe.

What is "ignoring events" vs "having a default handler for events" ? Wouldn't
default handlers be handled outside the application, and thus not trigger an
event towards the application? So that applications "ignoring events" would
be unrelated to "implementation-specific default handlers"? Perhaps the last
sentence should just start in a new paragraph to indicate these two things
are separate unrelated notes?

        SecurityParameters.Set(identity, myIdentity)

I assume myIdentity would be an array of Type and Value? Eg type=fqdn or type=RDN ?


I don't understand this code:

        Connection := Preconnection.Initiate()
        Connection2 := Connection.Clone()

        Connection -> Ready<>
        Connection2 -> Ready<>

        //---- Ready event handler for any Connection C begin ----
        C.Send(messageDataRequest)

Where does "C" come from in "C.Send" ? The comment says "any Connection C"?

I have a question on this code:

        Preconnections are reusable after being used to initiate a
        Connection, whether this Connection was closed or not. Hence, it
        would be correct to continue as follows after the above example:

        //.. carry out adjustments to the Preconnection, if desired
        Connection := Preconnection.Initiate()

What would happen here? I can imagine a "compiler" turning this into
a noop.  I can also see it would kill the existing Connection state and
start a new one. This could be to a different IP address (eg if the DNS
name has A and AAAA). When starting a new one, what would happen to any
Message or Event queues for Connection ?

What is "credentials" (especially because previously we have myCertificate,
so it is unclear if this now contains myKey and if so, where in the previous
example myKey was conveyed to TAPS.

        Preconnection.AddRemote(RemoteCandidates)

Should this not technically be:

        Preconnection.AddRemote([]RemoteCandidates)

as the array contains at least a host and a stun server candidate?

Maybe this is just the difference between you using the variable you define
that has been assigned, versus a more C like prototype format, eg:

        Preconnection := NewPreconnection([]LocalEndpoint,

So I guess if your example here had set LocalEndpoint := [a,b] you would not
have used [] in the call ?


Section 4.1:

        For the purposes of this document, these names are alphanumeric strings

Is there another purpose? If it is outside this document, why does this document
care? Does it try to set a standard here to ensure interoperable names? Maybe
just remove the "For the purposes of this document," ?

        Vendor or implementation specific properties MUST use a string
        identifying the vendor or implementation as the Namespace

What if Vendor Foo has a non-standard tcp property MagicSmoke? Does it go
under tcp.Foo.MagicSmoke or under Foo.tcp.MagicSmoke or something else?

Section 6.1

        An Endpoint object can be configured with the following identifiers:
        * Hostname (string):

This starts with listing endpoint identifiers with types (eg string and 16-bit
integers) but then stops specifying their types further down. I guess WithService(),
WithIPAddress() and WithInterface take a (string)

Section 6.1.4

Perhaps it would be useful to add a Local Endpoint with ephemeral port before
the Local Endpoint with static port example, as the ephemeral port should be
the far more common case. Right now the examples might give the wrong impression
a local port MUST be specified.


SecurityParameters.Set() seems to allow to set our identiy and our certificate,
but not the remote peer's identity or certificate? For example, one might want
to pin a remote certificate and not just rely on a WithHostname() identifier
being present as subjectAltname on a certificate.

        If security is opportunistic, it will allow Connections without
        transport security, but will still attempt to use security
        if available.

I assume what is meant is "but will still attempt to use unauthenticated security
if available" ?

      The Connection state, which can be one of the following:
        Establishing, Established, Closing, or Closed.

I think the text in Section 8 should more clearly show the property names if the
goal is to have different implementations use the identical name. Eg in this case,
why not write: The Connection state ("state"). The next two entries are similarly
lacking a clear keyword to use:

        Whether the Connection can be used to send data.

        Whether the Connection can be used to receive data.

eg. why not define words for these to implementations will use the same words,
in this case perhaps ReadySend and ReadyRcv ?
Writing that now, perhaps "state" should be "State" then ?

Section 8.1.1:

        If this property is an Integer

It is best to define the actual type in this document and not let implementations
choose, if the goal is to try and harmonize implementations. I also see no non-integer
value being given here ?

      A higher value reflects a higher priority.

This is uncommon in IETF protocols. Normally priority is down with lower numbers
being higher priority. Why reverse it here?

[ review to be continued from 8.1.3 ]



NITS:

Wouldn't the American spelling be "rendezvouzing" instead of "rendezvousing" :-)

[Ballot discuss]
# GEN AD review of draft-ietf-taps-interface-22

CC @larseggert

Thanks to Thomas Fossati for the General Area Review Team (Gen-ART) review
(https://mailarchive.ietf.org/arch/msg/gen-art/Uohwi2MvOOwswMfkE5w4mt9IZKE).

## Discuss

### Section 4.1, paragraph 8
```
    *  For IETF protocols, the name of a Protocol-specific Property
        SHOULD be specified in an IETF document published in the RFC
        Series.
```
For IETF protocols, i.e., protocols published on the IETF RFC stream,
those names must IMO be also specified in IETF-stream RFCs. I see no
reason to let other RFC streams make definitions for IETF protocols.

### Section 6.1, paragraph 13
```
    *  Interface name (string), e.g., to qualify link-local or multicast
        addresses (see Section 6.1.2 for details):

    LocalSpecifier.WithInterface("en0")
```
How does an application learn which interface name strings are
allowed/available on the system? The API doesn't seem to provide this
information. Also, based on the examples, there seem to be special
names such as "any" - where are those defined and how are conflicts
with names used on the system avoided?

### Section 6.1.3, paragraph 6
```
    In order to scope an alias to a specific transport protocol, an
    Endpoint can specify a protocol identifier.

    AlternateRemoteSpecifier.WithProtocol(QUIC)
```
This is the first and only time protocol identifiers are used. What
are they defined to be?

### Section 6.1.3, paragraph 9
```
    The following example shows a case where example.com has a server
    running on port 443, with an alternate port of 8443 for QUIC.

    RemoteSpecifier := NewRemoteEndpoint()
    RemoteSpecifier.WithHostname("example.com")
    RemoteSpecifier.WithPort(443)

    QUICRemoteSpecifier := NewRemoteEndpoint()
    QUICRemoteSpecifier.WithHostname("example.com")
    QUICRemoteSpecifier.WithPort(8443)
    QUICRemoteSpecifier.WithProtocol(QUIC)

    RemoteSpecifier.AddAlias(QUICRemoteSpecifier)
```
Why does the `RemoteSpecifier` definition not contain a `WithProtocol`
clause for TCP/TLS? And what would that look like, given that TCP/TLS
is a protocol combination?

### Section 6.2, paragraph 0
```
  6.2.  Specifying Transport Properties
```
This section defines a boatload of different properties, many of which
are interacting with each other due to how our current transport
protocols are implemented. Future interactions, due to future
transport protocols potentially becoming available, are undefined. I
question how a potential programmer is supposed to make informed
choices here without needing to be aware of all of this
background/baggage?

### Section 8.1.5, paragraph 4
```
    Default:  Weighted Fair Queueing (see Section 3.6 in [RFC8260])

    This property specifies which scheduler should be used among
    Connections within a Connection Group, see Section 7.4.  A set of
    schedulers is described in [RFC8260].
```
What is this scheduler scheduling? 7.4 is silent on this. I'm guessing
this is related to `connPriority`?

### Section 9.1.3, paragraph 9
```
    If a Message Property contradicts a Connection Property, and if this
    per-Message behavior can be supported, it overrides the Connection
    Property for the specific Message.  For example, if reliability is
    set to Require and a protocol with configurable per-Message
    reliability is used, setting msgReliable to false for a particular
    Message will allow this Message to be sent without any reliability
    guarantees.  Changing the msgReliable Message Property is only
    possible for Connections that were established enabling the Selection
    Property perMsgReliability.
```
How is this going to work in the opposite case, i.e., if an unreliable
connection was set up and then some messages are passed in which
require reliable transmission? At connection open, the stack may have
chosen a transport protocol that cannot support reliable
transmission? (Also, I think this general principle of message >
connection has other issues for other properties.)

[Ballot comment]
## Comments

I'm likely to abstain on this document, because I disagree that
Proposed Standard is appropriate. This document (and its companion)
outline as extremely intricate design, and I am not aware of any
attempts to implement even a sizable subset of it. Given the various
interactions between the API components and the attributes and
behaviors of existing transport protocols (and their implementation),
I strongly believe that in-depth experimentation with actual
implementations is needed before we can have the confidence in the
design we'd like to see for publication on the Standards Track.

### Section 1.1, paragraph 23
```
    *  String: Instances are represented in a way that is common to the
        programming language, e.g.  UTF-8.
```
If the intend of this API is to be language independent, it can't
really fall back on assuming a defined string representation of a
given language. Instead, it should define how strings are encoded.

### Section 4.1, paragraph 1
```
    Transport Properties are referred to by property names.  For the
    purposes of this document, these names are alphanumeric strings in
    which the following characters are allowed: lowercase letters a-z,
    uppercase letters A-Z, digits 0-9, the hyphen -, and the underscore
    _. These names serve two purposes:
```
This allows property names that are indistinguishable from integers.
Is that a bug or a feature? Also, are they case-sensitive?

### Section 4.1, paragraph 7
```
    Namespaces for each of the keywords provided in the IANA protocol
    numbers registry (see https://www.iana.org/assignments/protocol-
    numbers/protocol-numbers.xhtml) are reserved for Protocol-specific
    Properties and MUST NOT be used for vendor or implementation-specific
    properties.  Terms listed as keywords as in the protocol numbers
    registry SHOULD be avoided as any part of a vendor- or
    implementation-specific property name.
```
This doesn't work if vendors use property names that the IETF later
adds to the IANA registry. Suggest to instead define a
vendor-specific prefix/name here, ideally one that is illegal for the
IANA registry.

### Section 6, paragraph 6
```
    If more than one Local Endpoint is specified on a Preconnection, then
    all the Local Endpoints on the Preconnection MUST represent the same
    host.  For example, they might correspond to different interfaces on
    a multi-homed host, of they might correspond to local interfaces and
    a STUN server that can be resolved to a server reflexive address for
    a Preconnection used to make a peer-to-peer Rendezvous.
```
In order to make this MUST enforceable, a concrete definition of
what "represent the same host" means is IMO needed. Is this a static
or dynamic check?

### Section 6, paragraph 6
```
    If more than one Remote Endpoint is specified on the Preconnection,
    then all the Remote Endpoints on the Preconnection should represent
    the same service, to the extent that the application and the
    Transport Services system can validate that the Remote Endpoints are
    indeed the same service.  For example, the Remote Endpoints might
    represent various network interfaces of a host, or a server reflexive
    address that can be used to reach a host, or a set of hosts that
    provide equivalent local balanced service.
```
It's a lowercase "should", but I still have no idea how a programmer
or the API would verify whether all endpoints are the same service.
Seems unenforceable.

### Section 6.1, paragraph 8
```
    *  Port (a 16-bit integer):
```
Previously, only length-unlimited integer types were defined?

### Section 6.1, paragraph 10
```
    *  Service (an identifier that maps to a port; either the name of a
        well-known service, or a DNS SRV service name to be resolved):

    RemoteSpecifier.WithService("https")
```
I assume when you say "name of a well-known service" you mean "service
name associated with a port number on
https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml"?
It would be good to explicitly say that. Also, there seems to be an
assumption that the OS provides `getservbyname` or similar - is this
a reasonable assumption?

### Section 6.1.1, paragraph 4
```
    RemoteSpecifier.WithMulticastGroupIP(GroupAddress)
```
It's a design choice to not overload `WithIPAddress` here and instead
define `WithMulticastGroupIP`. I'd have overloaded, in order to avoid
the need for error handling if the wring type of IP address is passed
in.

### Section 6.1.1, paragraph 3
```
    RemoteSpecifier.WithTTL(TTL)
```
I'd point out that since IPv6, we switched to "hop count" for the
term, to make it clear it's not actually a time value
(anymore). Suggest to use the more modern term?

### Section 6.1.4, paragraph 3
```
    RemoteSpecifier := NewRemoteEndpoint()
    RemoteSpecifier.WithHostname("example.com")
    RemoteSpecifier.WithService("https")
```
Does `WithService("https")` implicitly set `WithProtocol(TCP/TLS)` or
is that missing from the example? If it does, which other such
implications are defined?

### Section 6.2.5, paragraph 0
```
  6.2.5.  Use 0-RTT Session Establishment with a Safely Replayable Message
```
This is an awfully specific preference compared to all the others.
Maybe make it a bit less specific by calling it "Initial Message will
be Safely Replayable" without mentioning a specific use case such as
0-RTT? (Or maybe even define a "replayable" message flag, and only do
0-RTT if that is set on the first message.)

### Section 6.2.7, paragraph 4
```
    This property specifies the application's need for protection against
    corruption for all data transmitted on this Connection.  Disabling
    this property could enable later control of the sender checksum
    coverage (see Section 9.1.3.6).
```
I don't know what "enable later control of the sender checksum
coverage" is supposed to mean. Also, how does this
(and `fullChecksumRecv`) intersect with `reliability`, which also
talks about corruption?

### Section 8.1.1, paragraph 3
```
    Type:  Integer (non-negative) or Full Coverage

    Default:  Full Coverage
```
How is "Full Coverage" expressed?

### Section 8.1.8, paragraph 4
```
    Numeric values of these properties specify an upper-bound rate that a
    transfer is not expected to exceed (even if flow control and
    congestion control allow higher rates), and/or a lower-bound rate
    below which the application does not deem it will be useful.  These
    are specified in bits per second.  The enumerated value Unlimited
    indicates that no bound is specified.
```
Over what timescale, or is this supposed to apply to instantaneous
bandwidth? Because an app can control how much data over time to feed
into a connection, but cannot usually know what send rate that
results in.

### Section 8.1.11.1, paragraph 3
```
    This property, if applicable, represents the maximum Message size
    that can be sent without incurring network-layer fragmentation at the
    sender.  It is specified as the number of bytes.  It exposes a value
    to the application based on the Maximum Packet Size (MPS) as
    described in Datagram PLPMTUD [RFC8899].  This can allow a sending
    stack to avoid unwanted fragmentation at the network-layer or
    segmentation by the transport layer.
```
Is this supposed to vary as PMTUD happens?

### Section 9.2.1, paragraph 2
```
    messageData := "hello"
    Connection.Send(messageData)
    The interpretation of a Message to be sent is dependent on the
    implementation, and on the constraints on the Protocol Stacks implied
    by the Connection’s transport properties.  For example, a Message may
    be a single datagram for UDP Connections; or an HTTP Request for HTTP
    Connections.
```
I don't think you mean "UDP datagram here", since that would include
the UDP header. UDP payload?

### Section 9.2.6, paragraph 2
```
    A Transport Services system gives no guarantees about how its
    expression of relative priorities will be realized.  However, the
    Transport Services system will seek to ensure that performance of
    relatively-prioritized Connections and Messages is not worse with
    respect to those Connections and Messages than an equivalent
    configuration in which all prioritization properties are left at
    their defaults.
```
Without defining what is meant by "performance" in this case, it's not
possible to know what "not worse" means. (Or how a transport system
might seek to ensure that.)

### Section 9.3.2, paragraph 1
```
    Each call to Receive will be paired with a single Receive event,
    which can be a success or an error.  This allows an application to
    provide backpressure to the transport stack when it is temporarily
    not ready to receive Messages.
```
Isn't the act of not reading and the resulting buffer growth already
providing this backpressure?

### Too many authors

The document has eight authors, which exceeds the recommended author limit. Has
the sponsoring AD agreed that this is appropriate?

### Inclusive language

Found terminology that should be reviewed for inclusivity; see
https://www.rfc-editor.org/part2/#inclusive_language for background and more
guidance:

* Terms `natively` and `native`; alternatives might be `built-in`,
  `fundamental`, `ingrained`, `intrinsic`, `original`

### IP addresses

Found IP block or address not inside RFC5737/RFC3849 example ranges:
`232.1.1.1`.

## Nits

All comments below are about very minor potential issues that you may choose to
address in some way - or ignore - as you see fit. Some were flagged by
automated tools (via https://github.com/larseggert/ietf-reviewtool), so there
will likely be some false positives. There is no need to let me know what you
did with these suggestions.

### Typos

#### Section 9.1.3.9, paragraph 4
```
-    prefered.
+    preferred.
+          +
```

#### Section 9.1.3.10, paragraph 3
```
-    this property to true will result in a sending endpount setting the
-                                                        ^
+    this property to true will result in a sending endpoint setting the
+                                                        ^
```

### Outdated references

Reference `[RFC8229]` to `RFC8229`, which was obsoleted by `RFC9329` (this may
be on purpose).

### Grammar/style

#### Section 1.1, paragraph 2
```
ming language, e.g. UTF-8. If the intend of this API is to be language indep
                                  ^^^^^^
```
The word "intend" is a verb. Did you mean the noun "intent"?

#### Section 2, paragraph 2
```
the kind of transport, can be bi-directional or unidirectional, and that ca
                              ^^^^^^^^^^^^^^
```
This word is normally spelled as one.

#### Section 6.1.2, paragraph 3
```
tener := Preconnection.Listen() Join an Source-Specific Multicast group in re
                                    ^^
```
Use "a" instead of "an" if the following word doesn't start with a vowel sound,
e.g. "a sentence", "a university".

#### Section 8, paragraph 9
```
lgorithm); to prefer immediate acknowledgment from the peer endpoint when su
                              ^^^^^^^^^^^^^^
```
Do not mix variants of the same word ("acknowledgment" and "acknowledgement")
within a single text.

#### Section 8.1.6, paragraph 11
```
onal Message Context, which allows to add Message Properties, identify Send
                                  ^^^^^^
```
Did you mean "adding"? Or maybe you should add a pronoun? In active voice,
"allow" + "to" takes an object, usually a pronoun.

#### Section 8.1.10, paragraph 4
```
In these cases, they add an additional transformation to further encode or e
                      ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
```
This phrase might be redundant. Consider either removing or replacing the
adjective "additional".

#### Section 9.3.2.3, paragraph 3
```
paths and are not necessarily privacy sensitive. Still, some information cou
                              ^^^^^^^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 9.3.2.3, paragraph 3
```
l, some information could be privacy sensitive because it might reveal usage
                            ^^^^^^^^^^^^^^^^^
```
This word is normally spelled with a hyphen.

#### Section 14, paragraph 5
```
cts (see Section 6.2) that are pre-configured with frequently used sets of p
                              ^^^^^^^^^^^^^^
```
Do not mix variants of the same word ("pre-configure" and "preconfigure")
within a single text.

## Notes

This review is in the ["IETF Comments" Markdown format][ICMF], You can use the
[`ietf-comments` tool][ICT] to automatically convert this review into
individual GitHub issues. Review generated by the [`ietf-reviewtool`][IRT].

[ICMF]: https://github.com/mnot/ietf-comments/blob/main/format.md
[ICT]: https://github.com/mnot/ietf-comments
[IRT]: https://github.com/larseggert/ietf-reviewtool

[Ballot comment]
Thank you for the work on this document.

Many thanks to Robert Sparks for his ART ART early: https://mailarchive.ietf.org/arch/msg/art/g3nBK52CUcWroPMW2bZR15BjdRk/ and last call reviews and to the authors for addressing Robert's comments.

[Ballot comment]
I have not completed my review prior to the telechat where this document is scheduled, but I wanted to go on record giving early kudos to the document shepherd who took the time to give a comprehensive explanation as to why there are eight authors, saving us the investigation and debate.

[Ballot discuss]
# Internet AD comments for draft-ietf-taps-interface-22
CC @ekline

* comment syntax:
  - https://github.com/mnot/ietf-comments/blob/main/format.md

* "Handling Ballot Positions":
  - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/

## Discuss

### S6.1.12

* "there is currently no portable standard format for a PvD identifier"

  RFC 8801 should be considered here.

  An argument can be made that there is no *single* format, but there
  certainly is a string FQDN PvD ID standard.

  I think it's fair to require that the FQDN PvD ID strings be considered
  MTI here, or that an implementation have some way to use handles that
  refer to these.  Maybe that's what's meant here by the integer option
  mention and I'm just not getting the clue.

[Ballot comment]
# Internet AD comments for draft-ietf-taps-interface-22
CC @ekline

* comment syntax:
  - https://github.com/mnot/ietf-comments/blob/main/format.md

* "Handling Ballot Positions":
  - https://ietf.org/about/groups/iesg/statements/handling-ballot-positions/

# Comments

### S3

* "The application should not assume that ignoring events..."
  s/should not/SHOULD NOT/?

### S6.1

* "Connection can perform name resolution"

  Does the Connection do name resolution?  I would have expected this to
  either be done by Preconnection or just "the API implementation".

### S6.1.3

* If calls like NewPreconnection() take an array of RemoteEndpoints why
  is it necessary to add one RemoteEndpoint to another via .AddAlias(),
  rather than just tossing into the []RemoteEndpoints array?

### S6.2

* It's probably too late for a bikeshed, but I find a Preference named
  "Ignore" to not mean "No Preference", as I read it.  I would have expected
  something like a Preference of "None".

  To me, "Ignore" feels kinda somewhat like "Avoid" (or "Eschew" :D ).

### S6.2.1

* "without corruption"?

  I think I would have expected "without loss"; "without corruption" implies
  to me that there's some extra level of integrity checking go on (vis.
  S6.2.7).

### S6.2.13

* Why should the preference be Avoid for Rendezvous use cases?  It seems
  to me like many Rendezvous uses are not necessarily long-lived and so
  might be Preference None (Ignore), or even Prefer.

### S9.1.3.7

* Same question as S6.2.1 above.

## Nits

### S5

* "Actions, events, and errors in implementations" ->
  "Action, event, and error objects in implementations"

### S6.1, S6.1.4

* "Port (a 16-bit integer)"

  Perhaps "unsigned integer", or "non-negative integer"?

* ":0a" -> ":a", I think

### S6.1.5

* "newPreconnection(...)" -> "NewPreconnection(...)"?

### S9.1.3.10

* s/endpount/endpoint/

[Ballot comment]
I am excited about this doc, and can confirm based on some experience that this is basically implementable.

Nevertheless there are a few problems, and potentially significant errors:

(S4.1) "Namespaces for each of the keywords provided in the IANA protocol numbers registry ... are reserved for Protocol-specific Properties and MUST NOT be used for vendor or implementation-specific properties."

It's regrettable that this excludes QUIC, TLS, HTTP, and other candidates for protocols operating under this API. Would it be too much to add a registry for additional reserved names? Indeed, there is enough noise in the protocol number registry it might be better to just have a registry of the 10? protocols that today might conceivably operate under TAPS.

(S7.3) This section confused me as to whether ICE is done by the Transport Service (paragraph 4), the app (paragraph 8), or both. (I think it's both.) Maybe state this more explicitly?

(S7.4) What happens if a Clone command results in a connection with different properties (e.g. in a second connection, the peer rejects the necessary TCP option)?

(S8, paragraph 3) "Therefore, it is RECOMMENDED that Protocol-specific Properties are used for properties common across different protocols and that Protocol-specific Properties are only used where specific protocols or properties are necessary."

I think the first instance of "protocol-specific properties should be "generic properties"?

(S8.2) UTO is not TCP-specific! QUIC does it too. Maybe this should be a generic property?

(S9.2.6) "The Transport Services API does order connPriority over msgPriority. In the absence of other externalities (e.g., transport-layer flow control), a priority 1 Message on a priority 0 Connection will be sent before a priority 0 Message on a priority 1 Connection in the same group."

Everywhere in this doc, larger integers = higher priorities. So IIUC the Priority 1 connection should be sent first!

[Ballot comment]
Hi,

Moderate level comments:

(1) As per the architecture doc, I think that it is great that you are defining a new transport API.  I note that this API doesn't really include any standard APIs or structures to monitor the state of the transport sessions for a given application (i.e., API user).  E.g., how many connections are currently open, total number of connections (since library was initialized), number of errored transport connections, drops, mtu issues, flow rates, etc.  I think that with some of the changes to the Internet architecture (e.g., QUIC to cite one obvious example), it reduces the ability for network operators to monitor and debug network issues between applications.  A potential corollary of this is that a lot more debug and diagnostics information will need to be made available to applications in a common way to allow application support staff, and users of those applications to better understand where in the network issues and failures are happening.  It would seem unreasonable for me to hold a discuss on this document for what might be a lot of work and discussion that could take a long time to resolve but I hope that the authors and WG will consider whether there is further useful future work required in additional RFCs.



Minor level comments:

(2) p 6, sec 1.1.  Terminology and Notation

  *  Array: Denoted []Type, an instance takes a value for each of zero
      or more elements in a sequence of the given Type.  An array may be
      of fixed or variable length.
  *  Collection: An unordered grouping of one or more values of the
      same type.

Perhaps calling it a Set may be better than Collection (if duplicates are not allowed) or a Bag (if duplicates are allowed).


(3) p 17, sec 6.1.  Specifying Endpoints

  Note that an IPv6 address specified with a scope (e.g.
  2001:db8:4920:e29d:a420:7461:7073:0a%en0) is equivalent to
  WithIPAddress with an unscoped address and WithInterface together.

Would it not just be cleaner to not allow interface scoped IP addresses, and force the clients to use WithInterface, in the case they want to target a specific interface?


(4) p 26, sec 6.2.  Specifying Transport Properties

    Upon reading, the Preference type
  of a Selection Property changes into Boolean, where true means that
  the selected Protocol Stack supports the feature or uses the path
  associated with the Selection Property, and false means that the
  Protocol Stack does not support the feature or use the path.

I misunderstood this on first reading - maybe explicitly state that the types for non Preference types are unchanged on a get, maybe give an example of the return type for section 6.2.11.


(5) p 64, sec 9.2.  Sending Data

  The optional endOfMessage parameter supports partial sending and is
  described in Section 9.2.3.

If this is an asynchronous API, I presume that the caller must prevent any changes to, or freeing of, the messageData object until it has received a event to indicate that the send has successfully completed.  Perhaps this is too detailed for this abstract level API and is left to the implementation.


(6) p 70, sec 9.3.2.  Receive Events

  Each call to Receive will be paired with a single Receive event,
  which can be a success or an error.  This allows an application to
  provide backpressure to the transport stack when it is temporarily
  not ready to receive Messages.

The backpressure aspect wasn't entirely clear to me.  So, if an application can handle receiving multiple receive events at the same time, it can make multiple calls to receive without waiting for, or processing, any receive events?  Is that how the application controls the backpressure?


(7) p 70, sec 9.3.2.  Receive Events

  Each call to Receive will be paired with a single Receive event,
  which can be a success or an error.  This allows an application to
  provide backpressure to the transport stack when it is temporarily
  not ready to receive Messages.

How does the transport stack know that the application has finished with the memory holding the message in the receive event, or is the expectation that the receive message contents is logically always allocated on the heap and it is responsibility of the receiver to free the memory once it is done with it?

Regards,
Rob

[Ballot comment]
Firstly, thank you very much for writing this document -- I found it a fascinating read.

I'd also like to thank Matt Brown for the DNS-DIR review, it was most helpful.

I only have a few nits / suggestions to make:
1: S 1.4.  Glossary of Key Terms
*Endpoint: An identifier for one side of a Connection (local or
      remote), such as a hostnames or URL.

I'm not really sure that the definition of "Endpoint" works. E.g: the definition of "Connection" is "Shared state of two or more endpoints that persists across Messages". Ok, fine. But can you really have shared state between two **identifiers**? I don't really see how I'd have shared state between e.g hostnames, but I can see how I'd have state between entities *identified* by an identifier like a hostname. I understand what you are aiming for (and also "endpoint" seems to be used in more than one context), but I don't think that the definition as written actually works...

2: S 2.1.  Event-Driven API
This paragraph compares and contrasts the Socket API and the Transport Services API, but in the paragraph starting with "For example, an application first issues a call to receive new data from the connection.", it is unclear under which paradigm you are meaning. I'd suggest: "For example, when using the Transport Services API, an application first ..."

[Ballot comment]
Firstly, thank you very much for writing this document -- I found it a fascinating read.

I only have a few nits / suggestions to make:
1: S 1.4.  Glossary of Key Terms
*Endpoint: An identifier for one side of a Connection (local or
      remote), such as a hostnames or URL.

I'm not really sure that the definition of "Endpoint" works. E.g: the definition of "Connection" is "Shared state of two or more endpoints that persists across Messages". Ok, fine. But can you really have shared state between two **identifiers**? I don't really see how I'd have shared state between e.g hostnames, but I can see how I'd have state between entities *identified* by an identifier like a hostname. I understand what you are aiming for (and also "endpoint" seems to be used in more than one context), but I don't think that the definition as written actually works...

2: S 2.1.  Event-Driven API
This paragraph compares and contrasts the Socket API and the Transport Services API, but in the paragraph starting with "For example, an application first issues a call to receive new data from the connection.", it is unclear under which paradigm you are meaning. I'd suggest: "For example, when using the Transport Services API, an application first ..."

[Ballot comment]
Thank you to Sean Turner for the SECDIR review.

** Section 6.1. 
-- Per “Port (a 16-bit integer):”, shouldn’t this be “16-bit unsigned integer”?

-- Per “Service (an identifier that maps to a port; either the name of a well-known service, or a DNS SRV service name to be resolved):”, what makes something a “well-known service”?  Is this string have to be from https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?

-- Per “IP address (IPv4 or IPv6 address):”, is there a formal syntax for an IPv4 or IPv6 address that can be cited?

** Section 6.3.  Editorial.  Should the convention of “myVariableName” be used here?
OLD
SecurityParameters.Set(pre-shared-key, key, identity)

NEW
SecurityParameters.Set(pre-shared-key, myKey, myIdentity)

** Section 6 of draft-ietf-taps-arch-18 said:
==[ snip ]==
  However, a Transport
  Services implementation can race different security protocols, e.g.,
  if the application explicitly specifies that it considers them
  equivalent.
==[ snip ]==

How does one use the API described in this document to convey equivalence?

** A few methods seem to be used in the prose without formal definition beyond the example:

-- Section 6.1.1: WithTTL()
-- Section 6.1.3: WithProtocol()

[Ballot discuss]
** Section 6.3.  I’m having trouble understanding the level of abstraction used to specify the SecurityParameter API if the desired outcome is an interoperable solution.  My top-line concern is around what are the defined security parameters are where are they formally defined. The API examples seem to suggest they are “identity, server-certificate, client-certificate, key-pair, supported-group, ciphersuite, signature-algorithm, and pre-shared-key.”

A few examples of this ambiguity:

-- “SecurityParameters.Set(identity, myIdentity)”: What is the “identity” parameter? What would be passed here?

-- Per “SecurityParameters.Set(server-certificate, myCertificate)” and “SecurityParameters.Set(client-certificate, myCertificate)”, assuming myCertificate is an X.509 certificate, what format would that be passed in (e.g., PEM, DER)?

-- What is in “myCertficate”:
o can it be a certificate chain?
o in the case of client-auth or a server, is this a bundle with both an X.509 and a private key?

-- The parameters “supported-group”, “ciphersuite” and “signature-algorithm” all appear to be enumerated values.  Where do those come from?

[Ballot comment]
Thank you to Sean Turner for the SECDIR review.

** Section 6.1. 
-- Per “Port (a 16-bit integer):”, shouldn’t this be “16-bit unsigned integer”?

-- Per “Service (an identifier that maps to a port; either the name of a well-known service, or a DNS SRV service name to be resolved):”, what makes something a “well-known service”?  Is this string have to be from https://www.iana.org/assignments/service-names-port-numbers/service-names-port-numbers.xhtml?

-- Per “IP address (IPv4 or IPv6 address):”, is there a formal syntax for an IPv4 or IPv6 address that can be cited?

** Section 6.3.  Editorial.  Should the convention of “myVariableName” be used here?
OLD
SecurityParameters.Set(pre-shared-key, key, identity)

NEW
SecurityParameters.Set(pre-shared-key, myKey, myIdentity)

** Section 6 of draft-ietf-taps-arch-18 said:
==[ snip ]==
  However, a Transport
  Services implementation can race different security protocols, e.g.,
  if the application explicitly specifies that it considers them
  equivalent.
==[ snip ]==

How does one use the API described in this document to convey equivalence?

** A few methods seem to be used in the prose without formal definition beyond the example:
-- Section 6.1.1: WithTTL()
-- Section 6.1.3: WithProtocol()

[Ballot comment]

# Éric Vyncke, INT AD, comments for draft-ietf-taps-interface-22

Thank you for the work put into this document.

Please find below some non-blocking COMMENT points (but replies would be appreciated even if only for my own education), and some nits.

Special thanks to Anna Brunstrom for the shepherd's detailed write-up including the WG consensus, and the justification of the intended status and of the large number of authors. I can only support having all those authors cited (especially from current/past academia).

Other thanks to Tatuya Jinmei, the Internet directorate reviewer (at my request), please consider this int-dir review:
https://datatracker.ietf.org/doc/review-ietf-taps-interface-22-intdir-telechat-jinmei-2023-09-01/ (while a positive review, I would appreciate a reply by authors, esp on issue 1)

Other thanks to Matt Brown, the DNS directorate reviewer (at my request), please consider this dns  -dir review:
https://datatracker.ietf.org/doc/review-ietf-taps-interface-22-dnsdir-telechat-brown-2023-08-27/

I hope that this review helps to improve the document,

Regards,

-éric

# COMMENTS

## Abstract and Section 1

It is not only about "multiple interfaces" but also about "multiple provisioning domains" (usually linked to interfaces), e.g., an interface can have several IPv6 addresses and several next-hops. RFC 7556 is only mentioned in Section 2.

## Section 1

`Action(param0, param1?, ...) / Event` the use of `\` is unclear... suggest using two lines ? Should param1 in Event() also be suffixed by a '?' ?

Is `IP Address` scoped ? E.g., fe80::1%eth0 Can it be unicast, anycast, multicast ? Even if section 6.1 is about this issue, it may be worth already telling the readers.

## Section 3

`from a Remote Endpoint` does the use of 'a' preclude a multicast group endpoint ?

## Section 3.1

Useful section. Thanks.

## Section 4.1

It is a little underspecified whether the '.' is also removed when the Namespace component is omitted (I guess yes, but let's be specific).

Should 'tcp' be in uppercase in `tcp Connection could support ` ?

`IETF document published in the RFC Series` in which stream ? Are ISE or IAB or IRTF streams also OK ?

## Section 5

If not mistaken, then there are only 3 occurrences of a normative SHOULD and several other non-normative "should". Is it the intent ?

## Section 6.1

I am not sure whether I like the split between .WithIPAddress() and .WithInterface()... E.g., using "fe80::1%eth0" as an endpoint would be nicer ?

Should there be a .WithPvD() to handle multiple PvDs on the same interface ? Even after reading section 6.2.12, it is unclear.

## Section 6.1.1

TTL is so legacy... Why not using RFC 8200 hop limit ?


# NITS

## Section 6.1 and other places

2001:db8:4920:e29d:a420:7461:7073:0a is not a valid RFC 5952 address ;-)

## Section 8.1.11.13

s/It specified as the number of bytes/It *is* specified as *a* number of bytes/ ?

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has reviewed draft-ietf-taps-interface-20, which is currently in Last Call, and has the following comments:

We understand that this document doesn't require any registry actions.

While it's often helpful for a document's IANA Considerations section to remain in place upon publication even if there are no actions, if the authors strongly prefer to remove it, we do not object.

If this assessment is not accurate, please respond as soon as possible.

For definitions of IANA review states, please see:

https://datatracker.ietf.org/help/state/draft/iana-review

Thank you,

David Dong
IANA Services Specialist

The following Last Call announcement was sent out (ends 2023-04-14):

From: The IESG
To: IETF-Announce
CC: Zaheduzzaman.Sarker@ericsson.com, anna.brunstrom@kau.se, draft-ietf-taps-interface@ietf.org, taps-chairs@ietf.org, taps@ietf.org
Reply-To: last-call@ietf.org
Sender:
Subject: Last Call:  (An Abstract Application Layer Interface to Transport Services) to Proposed Standard


The IESG has received a request from the Transport Services WG (taps) to
consider the following document: - 'An Abstract Application Layer Interface
to Transport Services'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
last-call@ietf.org mailing lists by 2023-04-14. Exceptionally, comments may
be sent to iesg@ietf.org instead. In either case, please retain the beginning
of the Subject line to allow automated sorting.

Abstract


  This document describes an abstract application programming
  interface, API, to the transport layer that enables the selection of
  transport protocols and network paths dynamically at runtime.  This
  API enables faster deployment of new protocols and protocol features
  without requiring changes to the applications.  The specified API
  follows the Transport Services architecture by providing
  asynchronous, atomic transmission of messages.  It is intended to
  replace the BSD sockets API as the common interface to the transport
  layer, in an environment where endpoints could select from multiple
  interfaces and potential transport protocols.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-taps-interface/



No IPR declarations have been submitted directly on this I-D.

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

This document reached broad agreement, with contributions from most active WG members.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

No.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

This document specifies and abstract API for the Transport Services reference architecture described in the -arch draft; the proposed API is based on experience gained in one widely deployed production implementation and two open implementations deployed for research purposes, as listed in Appendix C of the -implementation draft.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

This draft has benefited from broad TSV area review within the WG itself, and has had secdir and artart early review.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review necessary as no MIB models, YANG models, media types, or URI types etc. are used in the document.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

It does not contain a YANG module.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

No sections of the document are written in a formal language.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

The document has undergone both artart and secdir early review and has seen broad review overall to also receive comments for many of the int area topics (esp. v6). All identified issues have been resolved.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed standard. The requested type is consistent with the milestones for the working group and correctly reflected in the Intended RFC status field in the Datatracker. It is the proper type as the abstract API is based on experience from multiple implementations and intended to be used by multiple applications over different realizations of the API.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes; no IPR issues are known.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes, the authors have all shown their willingness to be listed as such.

The draft has 8 authors and editors. The wg believes there is a well-argued case for an exception to the 5 author rule.

First: The TAPS work on the core API draft has been a 7-year journey. It forms the first IETF transport API, something not previously published by the IETF. An integrated team-based approach was recognized as important from early in the document development and was discussed a number of times. The resulting team drew from several previous projects, important initial contributions from two EU projects (NEAT,MAMI), independent work at TU Berlin and Glasgow and independent work at Apple, and a small number of others. Each author continues to play a key part in shaping the way the final document is structured, while bringing necessarily expertise across a wide area of topics (see github activity) to draw expertise on a wide range of subjects. Things have evolved many times, but this was essentially a team effort - not an editorial process to draw together contributions.

Second, the topics span a very wide set of expertise - even for the IETF, and rather than make many documents, the wg purposely focused on three closely linked documents to cover: Understanding of applications use of transport; Architectural design; Privacy, Security and Policy in the stack; Trends in modern API and variations between programming languages, and use of callback, events, etc.; Detailed understanding of differences between the IETF transports; Understanding of STUN/ICE and Rendezvous; Understanding of NAT, details of using of IPv4 and IPv6, etc. The author lists for the other two core documents have been trimmed down to 5 authors, leaving a larger number of authors only for the API draft.

Third, as the document passes through IETF review, IESG review and RFC-Ed the present authors have a commitment and style of working that is effective and ensures that details are not overlooked. This close working may not be typical of the IETF process, and likely is because of the nature of these specific specifications, motivating a longer author list.

Overall, the draft represents a major investment by the entire author team. Normally the underpinning research contribution can be published in Journals, etc. However, in this case, people have been actively working on refining the spec for several years after their research to bring a consistent and new type of API to the IETF, and the final outcome is this spec. For the academic contributors, this contribution is only recognized by their Universities when they are authors.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

There are 2 instances of lines with non-ascii characters and a few lines that are too long and may need editing.

The document has a "Security and Privacy Considerations" Section. According to the idnits tool these should be two separate sections. The authors decided to leave this as it is for now and let the ADs decide about this matter.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

No non-IETF normative references.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No, the companion drafts will be submitted and published together.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

This document has no actions for IANA, which is appropriate.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

No new IANA registries.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

This document reached broad agreement, with contributions from most active WG members.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

No.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

This document specifies and abstract API for the Transport Services reference architecture described in the -arch draft; the proposed API is based on experience gained in one widely deployed production implementation and two open implementations deployed for research purposes, as listed in Appendix C of the -implementation draft.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

This draft has benefited from broad TSV area review within the WG itself, and has had secdir and artart early review.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review necessary as no MIB models, YANG models, media types, or URI types etc. are used in the document.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

It does not contain a YANG module.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

No sections of the document are written in a formal language.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

The document has undergone both artart and secdir early review and has seen broad review overall to also receive comments for many of the int area topics (esp. v6). All identified issues have been resolved.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed standard. The requested type is consistent with the milestones for the working group and correctly reflected in the Intended RFC status field in the Datatracker. It is the proper type as the abstract API is based on experience from multiple implementations and intended to be used by multiple applications over different realizations of the API.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes; no IPR issues are known.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes, the authors have all shown their willingness to be listed as such.

The draft has 7 authors and editors. The wg believes there is a well-argued case for an exception to the 5 author rule.

First: The TAPS work on the core API draft has been a 7-year journey. It forms the first IETF transport API, something not previously published by the IETF. An integrated team-based approach was recognized as important from early in the document development and was discussed a number of times. The resulting team drew from several previous projects, important initial contributions from two EU projects (NEAT,MAMI), independent work at TU Berlin and Glasgow and independent work at Apple, and a small number of others. Each author continues to play a key part in shaping the way the final document is structured, while bringing necessarily expertise across a wide area of topics (see github activity) to draw expertise on a wide range of subjects. Things have evolved many times, but this was essentially a team effort - not an editorial process to draw together contributions.

Second, the topics span a very wide set of expertise - even for the IETF, and rather than make many documents, the wg purposely focused on three closely linked documents to cover: Understanding of applications use of transport; Architectural design; Privacy, Security and Policy in the stack; Trends in modern API and variations between programming languages, and use of callback, events, etc.; Detailed understanding of differences between the IETF transports; Understanding of STUN/ICE and Rendezvous; Understanding of NAT, details of using of IPv4 and IPv6, etc. The author lists for the other two core documents have been trimmed down to 5 authors, leaving a larger number of authors only for the API draft.

Third, as the document passes through IETF review, IESG review and RFC-Ed the present authors have a commitment and style of working that is effective and ensures that details are not overlooked. This close working may not be typical of the IETF process, and likely is because of the nature of these specific specifications, motivating a longer author list.

Overall, the draft represents a major investment by the entire author team. Normally the underpinning research contribution can be published in Journals, etc. However, in this case, people have been actively working on refining the spec for several years after their research to bring a consistent and new type of API to the IETF, and the final outcome is this spec. For the academic contributors, this contribution is only recognized by their Universities when they are authors.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

There are 2 instances of lines with non-ascii characters and a few lines that are too long and may need editing.

The document has a "Security and Privacy Considerations" Section. According to the idnits tool these should be two separate sections. The authors decided to leave this as it is for now and let the ADs decide about this matter.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

No non-IETF normative references.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No, the companion drafts will be submitted and published together.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

This document has no actions for IANA, which is appropriate.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

No new IANA registries.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

# Document Shepherd Write-Up for Group Documents

*This version is dated 4 July 2022.*

Thank you for your service as a document shepherd. Among the responsibilities is
answering the questions in this write-up to give helpful context to Last Call
and Internet Engineering Steering Group ([IESG][1]) reviewers, and your
diligence in completing it is appreciated. The full role of the shepherd is
further described in [RFC 4858][2]. You will need the cooperation of the authors
and editors to complete these checks.

Note that some numbered items contain multiple related questions; please be sure
to answer all of them.

## Document History

1. Does the working group (WG) consensus represent the strong concurrence of a
  few individuals, with others being silent, or did it reach broad agreement?

This document reached broad agreement, with contributions from most active WG members.

2. Was there controversy about particular points, or were there decisions where
  the consensus was particularly rough?

No.

3. Has anyone threatened an appeal or otherwise indicated extreme discontent? If
  so, please summarize the areas of conflict in separate email messages to the
  responsible Area Director. (It should be in a separate email because this
  questionnaire is publicly available.)

No.

4. For protocol documents, are there existing implementations of the contents of
  the document? Have a significant number of potential implementers indicated
  plans to implement? Are any existing implementations reported somewhere,
  either in the document itself (as [RFC 7942][3] recommends) or elsewhere
  (where)?

This document specifies and abstract API for the Transport Services reference architecture described in the -arch draft; the proposed API is based on experience gained in one widely deployed production implementation and two open implementations deployed for research purposes, as listed in Appendix C of the -implementation draft.

## Additional Reviews

5. Do the contents of this document closely interact with technologies in other
  IETF working groups or external organizations, and would it therefore benefit
  from their review? Have those reviews occurred? If yes, describe which
  reviews took place.

This draft has benefited from broad TSV area review within the WG itself, and has had secdir and artart early review.

6. Describe how the document meets any required formal expert review criteria,
  such as the MIB Doctor, YANG Doctor, media type, and URI type reviews.

No formal review necessary as no MIB models, YANG models, media types, or URI types etc. are used in the document.

7. If the document contains a YANG module, has the final version of the module
  been checked with any of the [recommended validation tools][4] for syntax and
  formatting validation? If there are any resulting errors or warnings, what is
  the justification for not fixing them at this time? Does the YANG module
  comply with the Network Management Datastore Architecture (NMDA) as specified
  in [RFC 8342][5]?

It does not contain a YANG module.

8. Describe reviews and automated checks performed to validate sections of the
  final version of the document written in a formal language, such as XML code,
  BNF rules, MIB definitions, CBOR's CDDL, etc.

No sections of the document are written in a formal language.

## Document Shepherd Checks

9. Based on the shepherd's review of the document, is it their opinion that this
  document is needed, clearly written, complete, correctly designed, and ready
  to be handed off to the responsible Area Director?

Yes.

10. Several IETF Areas have assembled [lists of common issues that their
    reviewers encounter][6]. For which areas have such issues been identified
    and addressed? For which does this still need to happen in subsequent
    reviews?

The document has undergone both artart and secdir early review and has seen broad review overall to also receive comments for many of the int area topics (esp. v6). All identified issues have been resolved.

11. What type of RFC publication is being requested on the IETF stream ([Best
    Current Practice][12], [Proposed Standard, Internet Standard][13],
    [Informational, Experimental or Historic][14])? Why is this the proper type
    of RFC? Do all Datatracker state attributes correctly reflect this intent?

Proposed standard. The requested type is consistent with the milestones for the working group and correctly reflected in the Intended RFC status field in the Datatracker. It is the proper type as the abstract API is based on experience from multiple implementations and intended to be used by multiple applications over different realizations of the API.

12. Have reasonable efforts been made to remind all authors of the intellectual
    property rights (IPR) disclosure obligations described in [BCP 79][7]? To
    the best of your knowledge, have all required disclosures been filed? If
    not, explain why. If yes, summarize any relevant discussion, including links
    to publicly-available messages when applicable.

Yes; no IPR issues are known.

13. Has each author, editor, and contributor shown their willingness to be
    listed as such? If the total number of authors and editors on the front page
    is greater than five, please provide a justification.

Yes, the authors have all shown their willingness to be listed as such.

The draft has 7 authors and editors. The wg believes there is a well-argued case for an exception to the 5 author rule.

First: The TAPS work on the core API draft has been a 7-year journey. It forms the first IETF transport API, something not previously published by the IETF. An integrated team-based approach was recognized as important from early in the document development and was discussed a number of times. The resulting team drew from several previous projects, important initial contributions from two EU projects (NEAT,MAMI), independent work at TU Berlin and Glasgow and independent work at Apple, and a small number of others. Each author continues to play a key part in shaping the way the final document is structured, while bringing necessarily expertise across a wide area of topics (see github activity) to draw expertise on a wide range of subjects. Things have evolved many times, but this was essentially a team effort - not an editorial process to draw together contributions.

Second, the topics span a very wide set of expertise - even for the IETF, and rather than make many documents, the wg purposely focused on three closely linked documents to cover: Understanding of applications use of transport; Architectural design; Privacy, Security and Policy in the stack; Trends in modern API and variations between programming languages, and use of callback, events, etc.; Detailed understanding of differences between the IETF transports; Understanding of STUN/ICE and Rendezvous; Understanding of NAT, details of using of IPv4 and IPv6, etc. The author lists for the other two core documents have been trimmed down to 5 authors, leaving a larger number of authors only for the API draft.

Third, as the document passes through IETF review, IESG review and RFC-Ed the present authors have a commitment and style of working that is effective and ensures that details are not overlooked. This close working may not be typical of the IETF process, and likely is because of the nature of these specific specifications, motivating a longer author list.

Overall, the draft represents a major investment by the entire author team. Normally the underpinning research contribution can be published in Journals, etc. However, in this case, people have been actively working on refining the spec for several years after their research to bring a consistent and new type of API to the IETF, and the final outcome is this spec. For the academic contributors, this contribution is only recognized by their Universities when they are authors.

14. Document any remaining I-D nits in this document. Simply running the [idnits
    tool][8] is not enough; please review the ["Content Guidelines" on
    authors.ietf.org][15]. (Also note that the current idnits tool generates
    some incorrect warnings; a rewrite is underway.)

There are 2 instances of lines with non-ascii characters and a few lines that are too long and may need editing.

The document has a "Security and Privacy Considerations" Section. According to the idnits tool these should be two separate sections. The authors decided to leave this as it is for now and let the ADs decide about this matter.

15. Should any informative references be normative or vice-versa? See the [IESG
    Statement on Normative and Informative References][16].

No.

16. List any normative references that are not freely available to anyone. Did
    the community have sufficient access to review any such normative
    references?

No non-IETF normative references.

17. Are there any normative downward references (see [RFC 3967][9] and [BCP
    97][10]) that are not already listed in the [DOWNREF registry][17]? If so,
    list them.

No.

18. Are there normative references to documents that are not ready to be
    submitted to the IESG for publication or are otherwise in an unclear state?
    If so, what is the plan for their completion?

No, the companion drafts will be submitted and published together.

19. Will publication of this document change the status of any existing RFCs? If
    so, does the Datatracker metadata correctly reflect this and are those RFCs
    listed on the title page, in the abstract, and discussed in the
    introduction? If not, explain why and point to the part of the document
    where the relationship of this document to these other RFCs is discussed.

No.

20. Describe the document shepherd's review of the IANA considerations section,
    especially with regard to its consistency with the body of the document.
    Confirm that all aspects of the document requiring IANA assignments are
    associated with the appropriate reservations in IANA registries. Confirm
    that any referenced IANA registries have been clearly identified. Confirm
    that each newly created IANA registry specifies its initial contents,
    allocations procedures, and a reasonable name (see [RFC 8126][11]).

This document has no actions for IANA, which is appropriate.

21. List any new IANA registries that require Designated Expert Review for
    future allocations. Are the instructions to the Designated Expert clear?
    Please include suggestions of designated experts, if appropriate.

No new IANA registries.

[1]: https://www.ietf.org/about/groups/iesg/
[2]: https://www.rfc-editor.org/rfc/rfc4858.html
[3]: https://www.rfc-editor.org/rfc/rfc7942.html
[4]: https://trac.ietf.org/trac/ops/wiki/yang-review-tools
[5]: https://www.rfc-editor.org/rfc/rfc8342.html
[6]: https://trac.ietf.org/trac/iesg/wiki/ExpertTopics
[7]: https://www.rfc-editor.org/info/bcp79
[8]: https://www.ietf.org/tools/idnits/
[9]: https://www.rfc-editor.org/rfc/rfc3967.html
[10]: https://www.rfc-editor.org/info/bcp97
[11]: https://www.rfc-editor.org/rfc/rfc8126.html
[12]: https://www.rfc-editor.org/rfc/rfc2026.html#section-5
[13]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.1
[14]: https://www.rfc-editor.org/rfc/rfc2026.html#section-4.2
[15]: https://authors.ietf.org/en/content-guidelines-overview
[16]: https://www.ietf.org/about/groups/iesg/statements/normative-informative-references/
[17]: https://datatracker.ietf.org/doc/downref/

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

Request for posting confirmation emailed to previous authors: Brian Trammell , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Reese Enghardt , Tommy Pauly

Holding this doc until the arch, interface, and impl docs have had all outstanding comments addressed and been aligned with each other.
We will send the three docs to IESG as a set.

Request for posting confirmation emailed to previous authors: Brian Trammell , Christopher Wood , Colin Perkins , Gorry Fairhurst , Kyle Rose , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Theresa Enghardt , Tommy Pauly

Request for posting confirmation emailed to previous authors: Brian Trammell , Christopher Wood , Colin Perkins , Gorry Fairhurst , Michael Welzl , Mirja Kuehlewind , Philipp Tiesel , Theresa Enghardt , Tommy Pauly , taps-chairs@ietf.org

Request for posting confirmation emailed to previous authors: Brian Trammell , Theresa Enghardt , Tommy Pauly , Michael Welzl , Mirja Kuehlewind , Gorry Fairhurst , Colin Perkins , Philipp Tiesel , Christopher Wood

Request for posting confirmation emailed to previous authors: Brian Trammell , Michael Welzl , Colin Perkins , Gorry Fairhurst , Tommy Pauly , Philipp Tiesel , Theresa Enghardt , Christopher Wood , Mirja Kuehlewind

Request for posting confirmation emailed to previous authors: Michael Welzl , Theresa Enghardt , Philipp Tiesel , Christopher Wood , Colin Perkins , Brian Trammell , Gorry Fairhurst , Mirja Kuehlewind , Tommy Pauly

Request for posting confirmation emailed to previous authors: Michael Welzl , Theresa Enghardt , taps-chairs@ietf.org, Christopher Wood , Colin Perkins , Brian Trammell , Gorry Fairhurst , Mirja Kuehlewind , Philipp Tiesel

Request for posting confirmation emailed to previous authors: Michael Welzl , Theresa Enghardt , Christopher Wood , Colin Perkins , Brian Trammell , Gorry Fairhurst , Mirja Kuehlewind , Philipp Tiesel

Request for posting confirmation emailed to previous authors: Michael Welzl , Theresa Enghardt , Christopher Wood , Colin Perkins , Brian Trammell , Gorry Fairhurst , Mirja Kuehlewind , Philipp Tiesel

Request for posting confirmation emailed to previous authors: Michael Welzl , Theresa Enghardt , Christopher Wood , Colin Perkins , Brian Trammell , Gorry Fairhurst , Mirja Kuehlewind , Philipp Tiesel