Captive Portal API
Note: This ballot was opened for revision 07 and is now closed.
Barry Leiba Yes
Éric Vyncke Yes
Comment (2020-06-07 for -07)
Thank you for the work put into this document. The document is easy to read and the content is useful. Special thanks to the document shepherd, Martin Thomson, for describing the consensus within the WG. Please find below a couple on non-blocking COMMENTs and some NITs. I hope that this helps to improve the document, Regards, -éric == COMMENTS == -- Section 2 -- While I understand that most captive portals are currently for human beings, I still find the "User Equipment" terminology restrictive for potential devices where the users never interact with (think IoT or health devices or ...). I suggest to rewrite this part. -- Section 4 -- In "client's IP address" (singular address), is a dual-stack (IPv6/IPv4) client covered? Or should this client use the API both over IPv4 and IPv6 ? -- Section 5 -- I suggest to clarify "bytes-remaining" to specify whether the IP header is included in the count. == NITS == -- Section 1 -- Just wondering whether the TLS part is a part of the API rather than a means. -- Section 6 -- Suggestion: mention that "/captive-portal/api/X54PD" was discovered before as in section 4. s/extenal network access/external network access/
Deborah Brungard No Objection
Roman Danyliw (was Discuss) No Objection
Thanks for addressing my DISCUSS and COMMENT points.
Martin Duke (was Discuss) No Objection
Comment (2020-06-08 for -07)
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
Benjamin Kaduk No Objection
Comment (2020-06-09 for -07)
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".
Murray Kucherawy No Objection
Comment (2020-05-13 for -07)
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.
Alvaro Retana No Objection
Magnus Westerlund (was Discuss) No Objection
Thanks for discussion and resolving my issue.
Robert Wilton No Objection
Comment (2020-06-11 for -07)
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