Subject: [Captive-portals] I-D Action: draft-ietf-capport-api-01.txt

From: [email-masked]
Date: Sun, 01 Jul 2018 10:35:11 -0700

A New Internet-Draft is available from the on-line Internet-Drafts directories.
This draft is a work item of the Captive Portal Interaction WG of the IETF.

        Title           : Captive Portal API
        Authors         : Tommy Pauly
                          Darshak Thakore
	Filename        : draft-ietf-capport-api-01.txt
	Pages           : 7
	Date            : 2018-07-01

Abstract:
   This document describes an HTTP API that allows hosts to interact
   with a Captive Portal system.

The IETF datatracker status page for this draft is:
https://datatracker.ietf.org/doc/draft-ietf-capport-api/

There are also htmlized versions available at:
https://tools.ietf.org/html/draft-ietf-capport-api-01
https://datatracker.ietf.org/doc/html/draft-ietf-capport-api-01

A diff from the previous version is available at:
https://www.ietf.org/rfcdiff?url2=draft-ietf-capport-api-01

Please note that it may take a couple of minutes from the time of submission
until the htmlized version and diff are available at tools.ietf.org.

Internet-Drafts are also available by anonymous FTP at:
ftp://ftp.ietf.org/internet-drafts/

---

From: David Bird <[email-masked]>
Date: Mon, 2 Jul 2018 07:48:48 -0700

Some comments (will not be at meeting)

Section 1. The introduction states the purpose of the API as:

   o The state of captivity (whether or not the host has access to the
      Internet)

   o  A URI that a host's browser can present to a user to get out of
      captivity

   o  An encrypted connection (TLS for both the API and portal URI)

The state of captivity is not all or nothing and being detailed about
"captivity" (e.g. listing walled garden resources up front, down to
protocol, port, hostnames, etc) will be complex and error prone. The URI
for the captive portal can be gotten by RFC 7710. Captivity signaling
should be granular; because we can, and it includes more use-cases.

Section 2. The workflow is stated as:

   1.  Provisioning, in which a host discovers that a network has a
       captive portal, and learns the URI of the API server

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

    3.  Enforcement, in which the enforcement device in the network
       blocks disallowed traffic, and sends ICMP messages to let hosts
       know they are blocked by the captive portal

My issue is with the ordering... At step 2, we have Capport compliant
devices enforcing themselves.. while non-Capport devices wait for the
network enforcement. We have the (likely) scenarios of API server saying
one thing (implying "self enforcement"), while the network "Enforcement" is
telling the UE something else... who is right? Answer: always the network.

Section 3.2. I think the JSON keys represent a too narrow view of walled
gardens, and while simplicity is good, here it artificially and severely
limits use-cases.

Obviously, the "permitted" field is a boolean, not reflecting the fact the
location very likely has freely available resources in the walled garden.

The "expire-date" and "bytes-remaining" will be hard to synchronize with
network enforcement... the enforcement function might not be counting *all*
bytes (some might be "free"), session expiry could happen because of time
and/or data limits - possibly being consumed by multiple concurrent
devices/sessions - but also things like Idle Time or software restart (NAS
/ AP / etc) or a number of reasons.

What would be useful in the API, in my opinion, is for the API to provide a
sort of validation, authentication, and additional information for and
about network notifications.

On Sun, Jul 1, 2018 at 10:35 AM <[email-masked]> wrote:

> _______________________________________________
> Captive-portals mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/captive-portals
>

---

From: Michael Richardson <[email-masked]>
Date: Sat, 07 Jul 2018 19:38:26 -0400

David Bird <dbird=[email-masked]> wrote:
    > devices/sessions - but also things like Idle Time or software restart (NAS /
    > AP / etc) or a number of reasons.

If bytes-remaining is inaccurate in the negative direction (it runs out of
bytes before they are really gone), then the host winds up renewing too
early, and that is likely just fine.

Possibly the only situation where this is a problem is if the host has to buy
more bytes, and it buys more than it needed to.

expire-date has a time synchronization problem if it's very short timeout (on
the order of minutes).

--
Michael Richardson <[email-masked]>, Sandelman Software Works
 -= IPv6 IoT consulting =-

---

From: Tommy Pauly <[email-masked]>
Date: Mon, 09 Jul 2018 16:33:33 -0700

Hi David,

Thanks for the read-through. Some responses inline!

Best,
Tommy

> On Jul 2, 2018, at 7:48 AM, David Bird <dbird=[email-masked]> wrote:
> 
> The state of captivity is not all or nothing and being detailed about "captivity" (e.g. listing walled garden resources up front, down to protocol, port, hostnames, etc) will be complex and error prone. The URI for the captive portal can be gotten by RFC 7710. Captivity signaling should be granular; because we can, and it includes more use-cases.

Agreed. The fundamental thing about this API draft is that it is not the exhaustive set of information that the portal may want to communicate to the UE. The example of the state being captive or not is a very simple case, and there can certainly be more values to pass down.
> My issue is with the ordering... At step 2, we have Capport compliant devices enforcing themselves.. while non-Capport devices wait for the network enforcement. We have the (likely) scenarios of API server saying one thing (implying "self enforcement"), while the network "Enforcement" is telling the UE something else... who is right? Answer: always the network.

This workflow is the summary of of the CAPPORT architecture document. I completely agree that the enforcement is handled by the network, which is why this is all in the third step. The API server does not imply enforcement—It's the way for the portal that is doing enforcement to communicate information to the UE.

Non-CAPPORT devices currently do:

1. Provisioning, without knowing about captivity
-
3. Enforcement via blocking and redirects, in which UE's need to guess what happened

The enforcement is always the network, but the UE can provide a better user experience with 2.

> 
> Section 3.2. I think the JSON keys represent a too narrow view of walled gardens, and while simplicity is good, here it artificially and severely limits use-cases. 
> 
> Obviously, the "permitted" field is a boolean, not reflecting the fact the location very likely has freely available resources in the walled garden.
> 
> The "expire-date" and "bytes-remaining" will be hard to synchronize with network enforcement... the enforcement function might not be counting *all* bytes (some might be "free"), session expiry could happen because of time and/or data limits - possibly being consumed by multiple concurrent devices/sessions - but also things like Idle Time or software restart (NAS / AP / etc) or a number of reasons. 

As mentioned above, this is just the basic set of minimal keys. It is intended to be extendable as we flesh out the use cases.

> 
> What would be useful in the API, in my opinion, is for the API to provide a sort of validation, authentication, and additional information for and about network notifications.

Yes, I agree! This was partly discussed at the last meeting; when we had the HMAC key to validate network notifications, we decided to remove that until we had further specified the use cases for validating the network notifications.

> 
> On Sun, Jul 1, 2018 at 10:35 AM <[email-masked] <mailto:[email-masked]>> wrote:
> 
> https://datatracker.ietf.org/doc/draft-ietf-capport-api/ <https://datatracker.ietf.org/doc/draft-ietf-capport-api/>
> 
> https://tools.ietf.org/html/draft-ietf-capport-api-01 <https://tools.ietf.org/html/draft-ietf-capport-api-01>
> https://datatracker.ietf.org/doc/html/draft-ietf-capport-api-01 <https://datatracker.ietf.org/doc/html/draft-ietf-capport-api-01>
> 
> https://www.ietf.org/rfcdiff?url2=draft-ietf-capport-api-01 <https://www.ietf.org/rfcdiff?url2=draft-ietf-capport-api-01>
> 
> 
> until the htmlized version and diff are available at tools.ietf.org <http://tools.ietf.org/>.
> 
> ftp://ftp.ietf.org/internet-drafts/ <ftp://ftp.ietf.org/internet-drafts/>
> 
> [email-masked] <mailto:[email-masked]>
> https://www.ietf.org/mailman/listinfo/captive-portals <https://www.ietf.org/mailman/listinfo/captive-portals>

---

From: David Bird <[email-masked]>
Date: Fri, 13 Jul 2018 07:58:48 -0700

Hi Tommy,

Thanks for the reply... See one follow-up inline.

On Mon, Jul 9, 2018 at 4:33 PM Tommy Pauly <[email-masked]> wrote:

> Agreed. The fundamental thing about this API draft is that it is not the
> exhaustive set of information that the portal may want to communicate to
> the UE. The example of the state being captive or not is a very simple
> case, and there can certainly be more values to pass down.
>
>
> This workflow is the summary of of the CAPPORT architecture document. I
> completely agree that the enforcement is handled by the network, which is
> why this is all in the third step. The API server does not imply
> enforcement—It's the way for the portal that is doing enforcement to
> communicate information to the UE.
>

Do you envision CAPPORT devices doing 1, 2, and 3 before notifying the user
of captivity? Or, will CAPPORT devices just do 1 and 2 before notifying the
user (or attempting to "login")? It is the latter that I would call 'self
enforcement' because the client doesn't *know* there is captivity yet.

> As mentioned above, this is just the basic set of minimal keys. It is
> intended to be extendable as we flesh out the use cases.
>
>
> What would be useful in the API, in my opinion, is for the API to provide
> a sort of validation, authentication, and additional information for and
> Yes, I agree! This was partly discussed at the last meeting; when we had
> the HMAC key to validate network notifications, we decided to remove that
> until we had further specified the use cases for validating the network
> notifications.
>
>

---

From: Tommy Pauly <[email-masked]>
Date: Fri, 13 Jul 2018 09:16:38 -0700

> On Jul 13, 2018, at 7:58 AM, David Bird <dbird=[email-masked]> wrote:
> 
> Hi Tommy,
> 
> On Mon, Jul 9, 2018 at 4:33 PM Tommy Pauly <[email-masked] <mailto:[email-masked]>> wrote:
> Hi David,
> 
>> On Jul 2, 2018, at 7:48 AM, David Bird <dbird=[email-masked] <mailto:dbird=[email-masked]>> wrote:
>> 
> Do you envision CAPPORT devices doing 1, 2, and 3 before notifying the user of captivity? Or, will CAPPORT devices just do 1 and 2 before notifying the user (or attempting to "login")? It is the latter that I would call 'self enforcement' because the client doesn't *know* there is captivity yet. 
> 

Okay, I understand your point better now. You're right that until something goes wrong (3 blocks us) we don't truly *know* that we're captive and traffic will be blocked. However, I'd argue that this doesn't need to be the central point of the user experience going forward.

Once the device has done 1 and 2, it can present the user with some UI with a login page, or other experience. All this guarantees to the device and the user is that they are on some network that provides a portal landing page experience. That landing page can describe what the contract of the network is—maybe it's totally captive, but maybe some services are allowed through without any extra login (like texting on airplanes, which I'm seeing these days). In the future, maybe some network won't even block traffic, but just use this landing page advertisement as a way to get some information to the user.

As an OS vendor implementor, I view the responsibility of the OS as making sure the user sees the portal landing page if it exists, so as to allow the user to interact with the portal to remove captivity. Enforcement or making any guarantees about enforcement is not the job of the UE, it's the job of the network. The OS can choose whether or not to make a network it's default route for Internet traffic based on hints it has about captivity, as well as its experience of traffic working or not, but that's a reactionary step, not one of enforcement.

Thanks,
Tommy

---

From: David Bird <[email-masked]>
Date: Fri, 13 Jul 2018 09:59:45 -0700

Hi Tommy,

No doubt, I see the benefits from the UE point of view... and, I can see
the value when everything is working just right.

The edge cases the worry me...  as does the deployment / integration.

- What does the UE do if the API says "Your online" ... but you are not
(e.g. Network enforcement indicates captivity) ? (learns to ignore API?)
- What does the UE do if the API says "Your captive" ... but you are not
(the only way you know, really, is that all your friends with older devices
or laptops have no issues getting on-line, so you call UE vendor support!!)
?
- After releasing captivity (or starting without captivity) and
transitioning back to captive state -- do you agree that indication comes
from the network? Or, or is the UE suppose to poll for updates (perhaps
based on some expiration in the API) ?

I agree that enforcement isn't the job of the UE, it is the job of the
network... But, the examples above, I think, demonstrate that the UE *is*
making different decisions concerning enforcement / captivity than non
CAPPORT devices...

On Fri, Jul 13, 2018 at 9:17 AM Tommy Pauly <[email-masked]> wrote:

> Do you envision CAPPORT devices doing 1, 2, and 3 before notifying the
> user of captivity? Or, will CAPPORT devices just do 1 and 2 before
> notifying the user (or attempting to "login")? It is the latter that I
> would call 'self enforcement' because the client doesn't *know* there is
> captivity yet.
>
>
> Okay, I understand your point better now. You're right that until
> something goes wrong (3 blocks us) we don't truly *know* that we're captive
> and traffic will be blocked. However, I'd argue that this doesn't need to
> be the central point of the user experience going forward.
>
> Once the device has done 1 and 2, it can present the user with some UI
> with a login page, or other experience. All this guarantees to the device
> and the user is that they are on some network that provides a portal
> landing page experience. That landing page can describe what the contract
> of the network is—maybe it's totally captive, but maybe some services are
> allowed through without any extra login (like texting on airplanes, which
> I'm seeing these days). In the future, maybe some network won't even block
> traffic, but just use this landing page advertisement as a way to get some
> information to the user.
>
> As an OS vendor implementor, I view the responsibility of the OS as making
> sure the user sees the portal landing page if it exists, so as to allow the
> user to interact with the portal to remove captivity. Enforcement or making
> any guarantees about enforcement is not the job of the UE, it's the job of
> the network. The OS can choose whether or not to make a network it's
> default route for Internet traffic based on hints it has about captivity,
> as well as its experience of traffic working or not, but that's a
> reactionary step, not one of enforcement.
>
> Thanks,
> Tommy
>
>
>
>>
>> Obviously, the "permitted" field is a boolean, not reflecting the fact
>> the location very likely has freely available resources in the walled
>> garden.
>>

---

From: Tommy Pauly <[email-masked]>
Date: Fri, 13 Jul 2018 10:23:49 -0700

Hi David,

> On Jul 13, 2018, at 9:59 AM, David Bird <dbird=[email-masked]> wrote:
> 
> Hi Tommy,
> 
> No doubt, I see the benefits from the UE point of view... and, I can see the value when everything is working just right. 

We want to optimize the cases when things are working "right", but of course also have reasonable behavior when things aren't.

> - What does the UE do if the API says "Your online" ... but you are not (e.g. Network enforcement indicates captivity) ? (learns to ignore API?)

If the network enforcement indicates captivity, this translates into either (a) failures to access resources, which may or may not be notified with a helpful error; or (b) redirects to portal sites. The UE will not be aware of captivity (or captive-like behavior, since it can't really tell the difference between a real portal and someone redirecting websites) until the user loads some resource, and which point the user may get the landing page in their browser as they do today. This is exactly what happens to us often today, especially when our probes for captivity are defeated. It's not great for the user, but it works (as proven by existing deployments).

> - What does the UE do if the API says "Your captive" ... but you are not (the only way you know, really, is that all your friends with older devices or laptops have no issues getting on-line, so you call UE vendor support!!) ?

In this case, the user will see a landing page prompt when they join the network. That's the only "harm" in this scenario. Just like today when the user gets a prompt for a captive network, they can ignore it and stay on the network and continue to use it. I don't view getting a portal page as an issue to getting online; perhaps I see this when I get on an airplane network, or a coffee shop network, and it just gives me extra information about the flight, without restricting my network access.

> - After releasing captivity (or starting without captivity) and transitioning back to captive state -- do you agree that indication comes from the network? Or, or is the UE suppose to poll for updates (perhaps based on some expiration in the API) ?

The ultimate enforcement of captivity comes from the network. However, the best way to renew access will be to have a notion of both a "soft lifetime" (when you should try to re-auth) and a "hard lifetime" (when your access is totally revoked). The hard lifetime is the job of the network, but it's often a bit too late to keep existing connections up by that point. The API allows us to have a hint of when the soft lifetime is; this is not a matter of polling, but a way to trigger (perhaps) a local notification to let the user know that they have 5 minutes left, and should renew if they want to stay on the network.

> 
> I agree that enforcement isn't the job of the UE, it is the job of the network... But, the examples above, I think, demonstrate that the UE *is* making different decisions concerning enforcement / captivity than non CAPPORT devices...

These decisions, as far as I can tell, are about improving use experience, rather than actually enforcing anything. The UE won't block traffic if it sees the API mark things as captive, etc; but it will be able to give the user better opportunities to interact with the portal.

Thanks,
Tommy

> 
> 
> On Fri, Jul 13, 2018 at 9:17 AM Tommy Pauly <[email-masked] <mailto:[email-masked]>> wrote:
> 
> 
>> On Jul 13, 2018, at 7:58 AM, David Bird <dbird=[email-masked] <mailto:dbird=[email-masked]>> wrote:
>> 
>> Hi Tommy,
>> 
>>> My issue is with the ordering... At step 2, we have Capport compliant devices enforcing themselves.. while non-Capport devices wait for the network enforcement. We have the (likely) scenarios of API server saying one thing (implying "self enforcement"), while the network "Enforcement" is telling the UE something else.... who is right? Answer: always the network.
>>

---

From: David Bird <[email-masked]>
Date: Fri, 13 Jul 2018 11:06:22 -0700

Hi Tommy,

On Fri, Jul 13, 2018 at 10:24 AM Tommy Pauly <[email-masked]> wrote:

> If the network enforcement indicates captivity, this translates into
> either (a) failures to access resources, which may or may not be notified
> with a helpful error; or (b) redirects to portal sites. The UE will not be
> aware of captivity (or captive-like behavior, since it can't really tell
> the difference between a real portal and someone redirecting websites)
> until the user loads some resource, and which point the user may get the
> landing page in their browser as they do today. This is exactly what
> happens to us often today, especially when our probes for captivity are
> defeated. It's not great for the user, but it works (as proven by existing
> deployments).
>

Hm... except "works today, as proven by existing deployments" as the backup
for API/network disagreement includes things like redirecting HTTPS. Does
the solution (over time) get rid of redirecting HTTPS altogether? Or, will
vendors always keep this because of possible API integration issues as the
'backup plan' ?

I think part of the underlying problem, indeed, is that the UE "can't tell
the difference between a captive portal or someone redirecting websites"..
nor can it tell the difference between captive portal enforcement and
dropped packets (non-port-80). Current protocols don't give the
"enforcement function" any way to be *transparent* about what it is
doing... leaving the UE guessing. This is a core problem I believe needs
addressing... and in doing so, the UE knows a lot more about what is
happening, and even what is going to be happening (on a per flow basis).

> In this case, the user will see a landing page prompt when they join the
> network. That's the only "harm" in this scenario. Just like today when the
> user gets a prompt for a captive network, they can ignore it and stay on
> the network and continue to use it. I don't view getting a portal page as
> an issue to getting online; perhaps I see this when I get on an airplane
> network, or a coffee shop network, and it just gives me extra information
> about the flight, without restricting my network access.
>
>

I think the "harm" could come in how this API is deployed. Making it
*incredibly* easy to deploy, in fact, without any network integration -
just a DHCP config change, an API server somewhere on the Internet, and you
are done! Sure, UE/Users might just accept this. Or, UEs might eventually
start probing again -- because they see too many networks doing this, to
user dismay. But, I can accept that this could be compensated by the user
just "connect anyway" and the UE could remember that decision... (Ignoring
the API at the user's request).

> The ultimate enforcement of captivity comes from the network. However, the
> best way to renew access will be to have a notion of both a "soft lifetime"
> (when you should try to re-auth) and a "hard lifetime" (when your access is
> totally revoked). The hard lifetime is the job of the network, but it's
> often a bit too late to keep existing connections up by that point. The API
> allows us to have a hint of when the soft lifetime is; this is not a matter
> of polling, but a way to trigger (perhaps) a local notification to let the
> user know that they have 5 minutes left, and should renew if they want to
> stay on the network.
>
>

I agree that kind of signaling is very valuable (when accurate). However,
the API will eventually become *very* complex (resembling a firewall
config) if we attempt to truly quantify the possible soft and hard limits
being enforces... I don't think we need to do that. In fact, we only need
to do that because the API requires us to tell the UE -- up-front -- what
it needs to know about the network. Shifting that signaling to the network
-- on a need-to-know basis -- provides more granularity (there is no "soft"
and "hard" limit, for example, for resources in the walled garden anyway)
and more options in terms how "enforcement functions" are implemented and
deployed.

> These decisions, as far as I can tell, are about improving use experience,
> rather than actually enforcing anything. The UE won't block traffic if it
> sees the API mark things as captive, etc; but it will be able to give the
> user better opportunities to interact with the portal.
>
> Thanks,
> Tommy
>
>
>
>> On Jul 13, 2018, at 7:58 AM, David Bird <
>> dbird=[email-masked]> wrote:
>>
>> Hi Tommy,
>>
>>> On Jul 2, 2018, at 7:48 AM, David Bird <
>>> dbird=[email-masked]> wrote:
>>>
>>> telling the UE something else.... who is right? Answer: always the network.
>>>
>>>
>> As an OS vendor implementor, I view the responsibility of the OS as
>> making sure the user sees the portal landing page if it exists, so as to
>> allow the user to interact with the portal to remove captivity. Enforcement
>> or making any guarantees about enforcement is not the job of the UE, it's
>> the job of the network. The OS can choose whether or not to make a network
>> it's default route for Internet traffic based on hints it has about
>> captivity, as well as its experience of traffic working or not, but that's
>> a reactionary step, not one of enforcement.
>>
>> Thanks,
>> Tommy
>>
>>
>>
>>>
>>> What would be useful in the API, in my opinion, is for the API to
>>> provide a sort of validation, authentication, and additional information
>>> for and about network notifications.
>>>
>>>