Captive Portal API
draft-ietf-capport-api-08

Nice work.

A couple of points on the IANA registrations:

Section 8.1: The "Interoperability Considerations" text isn't quite what I think is anticipated by RFC 6838.  Given what you're saying there against what Section 6.2 of that document says, I think you could just have "None" here, but either way I suggest it's worth a second look.

Section 8.2: I suggest either having a column dedicated to recording the specification (since the Designated Expert is supposed to ensure there is one), or explicitly encourage that it be referenced in the Description column.

Thanks for addressing my DISCUSS and COMMENT points.

I'll start off with a handful of high-level comments, some of which
might qualify for Discuss-level points, but which have obvious
resolution and for which I trust the authors and AD to do the right
thing.

JSON only has Numbers, not integers; Section 5 should not describe
fields as integers without additional clarification (e.g., "integer,
represented as a JSON Number").

Also, the GET example in Section 6 seems to be malformed, not specifying
an HTTP-version.

I also think we should go into more detail on the TLS usage, pulling in
the relevant preexisting IETF BCP and proposed standards to take
advantage of the current state of the art (details in the
section-by-section comments).

Additionally, I note some places in the section-by-section comments
where we can go into more detail on the "chain of custody" of
information presented to the user, making sure that we keep a trusted
path from initial provisioning through to API server access and captive
portal server access.  There are some places where we don't seem to have
a 100% airtight solution, and those gaps can be called out more clearly.

Abstract

   with a Captive Portal system.  With this API, clients can discover
   how to get out of captivity and fetch state about their Captive
   Portal sessions.

The architecture document only implicitly talks about "Captive Portal
sessions" (one mention in passing of when the "end of a session is
imminent").  Should it have more text introducing the term/topic?

Also, the architecture doc talks about learning the "state of
captivity", but this formulation implies that there might be a much
richer state to learn about.

Section 1

   *  A URI that a client browser can present to a user to get out of
      captivity

nit: this feels worded oddly to me; merely presenting (displaying?) a
URI to the user does not help to do anything to get out of captivity.
Presenting the dereferenced content referred to by that URI might be
more effective at it, but would still require user action...

   *  An encrypted connection (using TLS for connections to both the API
      and user portal)

I think "authenticated" is equally as important as "encrypted" and
should be mentioned alongside it.

Section 3

   2.  API Server interaction, in which a client queries the state of
       the captive portal and retrieves the necessary information to get
       out of captivity.

I may be overly tied to this "state of captivity" phrase, but is there a
need to use "state" in a different formulation here?

Section 4

   For example, if the Captive Portal API server is hosted at
   "example.org", the URI of the API could be "https://example.org/
   captive-portal/api"

The architectures says that "the URIs provided in the API SHOULD be
unique to the UE and not dependent on contextual information to function
correctly."  I guess this is referring to the contents of the resource
retrieved by dereferencing the URI of the API and not the URI of the API
itself?  So this example is not in conflict with the SHOULD.

   If the API server needs information about the client identity that is
   not otherwise visible to it, the URI provided to the client during
   provisioning can be distinct per client.  Thus, depending on how the
   Captive Portal system is configured, the URI might be unique for each
   client host and between sessions for the same client host.

I appreciate having this explanation for why "[t]he client SHOULD NOT
assume that the URI for a given network attachment will stay the same"
as the first paragraph of the section tells us.  The explanation is a
little further from the requirement than I would like, but I don't have
a suggestion for bringing them closer together :-/

   For example, a Captive Portal system that uses per-client session
   URIs could use "https://example.org/captive-portal/api/X54PD" as its
   API URI.

Hmm, assuming a base64 alphabet, that has like 30-ish bits of entropy
available in the final path component.  Is that representative of a
large-enough identifier space for real deployments?

Section 4.1

I mentioned this on the architecture document already, though perhaps it
makes more sense to be done in the procotol document (this one): RFC
6125 has guidelines for TLS server authentication and is a good
reference to cite.  However (and regardless of whether we reference 6125
or not), we still will need to say what name type the client looks for
in the certificate and how the client obtains the reference name to
compare against the certificate contents.  For us the latter is probably
simple: just use what we got from the capport provisioning stage (and
leave to 7710bis the question of how we authenticate *that*
information), but it should still be said.

   example above).  The hostname of the API SHOULD be displayed to the
   user in order to indicate the entity which is providing the API
   service.

Should this hostname only be presented to the user (as, presumably, the
identity of the captive network?) when the certificate validation
succeeds?  Presenting a name that has not been authenticated leaves the
user open to spoofing attacks.

   Clients performing revocation checking will need some means of
   accessing revocation information for certificates presented by the
   API server.  Online Certificate Status Protocol [RFC6960] (OCSP)
   stapling, using the TLS Certificate Status Request extension
   [RFC6066] SHOULD be used.  OCSP stapling allows a client to perform

This is consistent though not fully alligned with the recommendations in
BCP 195 (RFC 7525).  Should we reference the BCP and discuss our
deviations from its recommendations?

   revocation checks without initiating new connections.  To allow for
   other forms of revocation checking, a captive network could permit
   connections to OCSP responders or Certificate Revocation Lists (CRLs)
   that are referenced by certificates provided by the API server.  In
   addition to connections to OCSP responders and CRLs, a captive

This leaves it to the reader to know that there may be clients that
don't support OCSP stapling and would need access to some other
mechanism for revocation checking.  It might be worth making that more
explicit, since the type of client on the network is not always under
the control of the network operator.

   network SHOULD also permit connections to Network Time Protocol (NTP)
   [RFC5905] servers or other time-sync mechnisms to allow clients to
   accurately validate certificates.

Is there a way to reliably identify "NTP servers or other time-sync
mechanisms"?  My understanding is that the network generally doesn't
have a way to indicate to a client what NTP (or other time protocol)
server to use, so it would be fairly easy to end up in a situation where
client and enforcement device disagree on what time-synchronization
mechanism to use and the client gets locked out.

   be used by the Captive Portal API server.  If the certificates do
   require the use of AIA, the captive network MUST allow client access
   to the host specified in the URI.

[This implicitly assumes that the DNS resolution of that host is the
same at both client and enforcement device, which hopefully goes without
saying.]

Section 6

   Upon receiving this information the client will use this information
   direct the user to the the web portal (as specified by the user-

nit: "to direct"

   Captive Portal JSON content can contain per-client data that is not
   appropriate to store in an intermediary cache.  Captive Portal API
   servers SHOULD set the Cache-Control header in any responses to
   "private", or a more restrictive value [RFC7234].

Is there a well-defined ordering on Cache-Control header [field]
restrictiveness such that "more restrictive value" is clearly defined?
(nit: s/header/header field/.)

Also, it's easy to miss a normative requirement like this when it's in
an "Example Interaction" section; I suggest moving it elsewhere.

Section 7

   which the client can perform revocation checks.  This allows the
   client to ensure that the API server has authority for a hostname
   that can be presented to a user.

We should say something about how a client does (or does not) determine
that the authenticated hostname is authorized to act for the network
being joined.  The last paragraph's discussion of confusables and
"trustworthy name"s suggests that there isn't much of a direct chain
here, just whether the certified domain name is "trustworthy" or not.
Even if so (which I could understand being the case; it's not an easy
problem), we should be clear about the gap in the system and the
potential risks it entails.

   It is important to note that while the server authentication checks
   can validate a specific hostname, it is certainly possible for the
   API server to present a valid certificate for a hostname that uses
   non-standard characters or is otherwise designed to trick the user
   into believing that its hostname is some other, more trustworthy,
   name.  This is a danger of any scenario in which a hostname is not
   typed in by a user.

Do we want to reference any of the PRECIS stuff (RFC 7564/etc.)?

Section 7.1

   Information passed between a client and a Captive Portal system may
   include a user's personal information, such as a full name and credit
   card details.  Therefore, it is important that Captive Portal API
   Servers do not allow access to the Captive Portal API over
   unencrypted sessions.

While I support this requirement, it seems like the personal information
exchange is more likely to occur between client and Captive Portal
Server than between client and Captive Portal API Server.  Protecting
the exchange with the API server is still important, though, to make
sure that the client talks to the right Captive Portal Server!

Section 8.2

   New assignments for Captive Portal API Keys Registry will be
   administered by IANA using the Specification Required policy
   [RFC8126].  The Designated Expert is expected to validate the
   existence of documentation describing new keys in a permanent
   publicly available specification.  The expert is expected to validate

Does an I-D that is never published as an RFC meet this bar?

   that new keys have a clear meaning and do not create unnecessary
   confusion or overlap with existing keys.  Keys that are specific to

I trust that this includes "matches an existing key name using a
case-insensitive comparison".

Thanks for discussion and resolving my issue.

This document is clearly written. Thanks.

I am also confused by this sentence at the end of section 4.1 about failed authentication:
“It may still be possible for the user to access the network by being redirected to a web portal.”

I suggest “...access the network by redirecting a clear text webpage to a web portal.”  I was a bit confused by the original wording.

As I said in the architecture review, the term for the user portal keeps changing. Over there it’s called a “Captive Portal Server” and a “web portal server”. Here it’s a “user-portal.” The authors of the two docs should get together and agree on a term.

One nit:
s/extenal/external

Hi,

I found this document straight forward and easy to read.

Linda's comment in the Opsdir review is interesting.  I would have expected the CAPPORT architecture document to discuss/reference the problem being solved, but it seems to be mostly silent on this.  I will redirect Linda's comment to the CAPPORT architecture.

In section 5. "API State Structure", it does not state whether a connection could be both time and data limited.  My reading of the spec is that this would be allowed, assuming that is the case, the current text is fine.

6.  Example Interaction

   Upon receiving this information the client will use this information
   direct the user to the the web portal (as specified by the user-
   portal-url value) to enable access to the external network.  Once the
   user satisfies the requirements for extenal network access, the
   client SHOULD query the API server again to verify that it is no
   longer captive.

Nit: information direct => information to direct


7.  Security Considerations

I'm slightly concerned about the third paragraph in the security considerations.  Ideally I would like a solution that doesn't require humans to potentially spot potentially dubious spoofed domain names.  But I can appreciate that is probably out of scope here.

7.1.  Privacy Considerations

Possibly worth adding a comment about the necessity to keep personal information secure.   In addition, should there be any comments about GDPR like constraints (if they apply)?

Thanks,
Rob