-
Notifications
You must be signed in to change notification settings - Fork 8
/
Copy pathdraft-ietf-capport-architecture.xml
1225 lines (1213 loc) · 67.6 KB
/
draft-ietf-capport-architecture.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version='1.0' encoding='utf-8'?>
<!-- This template is for creating an Internet Draft using xml2rfc,
which is available here: http://xml.resource.org. -->
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
(Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
(using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<!DOCTYPE rfc SYSTEM "rfc2629-xhtml.ent">
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" category="info" docName="draft-ietf-capport-architecture-10" ipr="trust200902" tocInclude="true" tocDepth="4" symRefs="true" sortRefs="true" version="3">
<!-- xml2rfc v2v3 conversion 2.37.2 -->
<!-- category values: std, bcp, info, exp, and historic
ipr values: trust200902, noModificationTrust200902, noDerivativesTrust200902,
or pre5378Trust200902
you can add the attributes updates="NNNN" and obsoletes="NNNN"
they will automatically be output with "(if approved)" -->
<!-- ***** FRONT MATTER ***** -->
<front>
<!-- The abbreviated title is used in the page header - it is only necessary if the
full title is longer than 39 characters -->
<title abbrev="Captive Portal Architecture">Captive Portal Architecture</title>
<seriesInfo name="Internet-Draft" value="draft-ietf-capport-architecture-10"/>
<!-- add 'role="editor"' below for the editors if appropriate -->
<!-- Another author who claims to be an editor -->
<author fullname="Kyle Larose" initials="K." surname="Larose">
<organization>Agilicus</organization>
<address>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="David Dolson" initials="D." surname="Dolson">
<address>
<email>[email protected]</email>
<!-- uri and facsimile elements may also be added -->
</address>
</author>
<author fullname="Heng Liu" initials="H." surname="Liu">
<organization>Google</organization>
<address>
<email>[email protected]</email>
</address>
</author>
<date year="2020"/>
<!-- If the month and year are both specified and are the current ones, xml2rfc will fill
in the current day for you. If only the current year is specified, xml2rfc will fill
in the current day and month for you. If the year is not the current one, it is
necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the
purpose of calculating the expiry date). With drafts it is normally sufficient to
specify just the year. -->
<!-- Meta-data Declarations -->
<area>art</area>
<workgroup>Internet Engineering Task Force</workgroup>
<!-- WG name at the upperleft corner of the doc,
IETF is fine for individual submissions.
If this element is not present, the default is "Network Working Group",
which is used by the RFC Editor as a nod to the history of the IETF. -->
<keyword>plus</keyword>
<!-- Keywords will be incorporated into HTML output
files in a meta tag but they have no effect on text or nroff
output. If you submit your draft to the RFC Editor, the
keywords will be used for the search engine. -->
<abstract>
<t>This document describes a captive portal architecture.
Network provisioning protocols such as DHCP or Router Advertisements (RAs),
an optional signaling protocol, and an HTTP API are used to provide the solution.
</t>
</abstract>
</front>
<middle>
<section>
<name>Introduction</name>
<t>
In this document, "Captive Portal" is used to describe a network to
which a device may be voluntarily attached, such that network access is
limited until some requirements have been fulfilled. Typically a user
is required to use a web browser to fulfill requirements imposed by the
network operator, such as reading advertisements, accepting an
acceptable-use policy, or providing some form of credentials.
</t>
<t>
Implementations of captive portals generally require a web server, some
method to allow/block traffic, and some method to alert the user.
Common methods of alerting the user in implementations prior to this
work involve modifying HTTP or DNS traffic.
</t>
<t>
This document describes an architecture for implementing captive
portals while addressing most of the problems arising for current
captive portal mechanisms. The architecture is guided by these
requirements:
</t>
<ul spacing="normal">
<li>Current captive portal solutions typically implement some variations
of forging DNS or HTTP responses.
Some attempt man-in-the-middle (MITM) proxy of HTTPS in
order to forge reponses.
Captive Portal Solutions should not have to break any protocols or
otherwise act in the manner of an attacker.
Therefore, solutions MUST NOT require the forging of responses from
DNS or HTTP servers, or any other protocol.</li>
<li>Solutions MUST permit clients to perform DNSSEC validation, which rules out solutions
that forge DNS responses.
Solutions SHOULD permit clients to detect and avoid TLS man-in-the-middle attacks
without requiring a human to perform any kind of "exception" processing.</li>
<li>To maximize universality and adoption, solutions MUST operate at the
layer of Internet Protocol (IP) or above, not being specific to any
particular access technology such as Cable, WiFi or mobile
telecom.</li>
<li>Solutions SHOULD allow a device to query the network to determine whether the device is
captive, without the solution being coupled to forging intercepted protocols or
requiring the device to make sacrificial queries to "canary" URIs to check for response
tampering (see <xref target="app-additional"/>). Current captive
portal solutions that work by affecting DNS or HTTP generally only function as intended
with browsers, breaking other applications using those protocols; applications using
other protocols are not alerted that the network is a captive portal.</li>
<li>The state of captivity SHOULD be explicitly available to devices via
a standard protocol, rather than having to infer the state indirectly.</li>
<li>The architecture MUST provide a path of incremental migration,
acknowledging the existence of a huge variety of pre-existing
portals and end-user device implementations and software versions.
This requirement is not to recommend or standardize existing
approaches, rather to provide device and portal implementors a path
to new standard.</li>
</ul>
<t>
A side-benefit of the architecture described in this document is that
devices without user interfaces are able to identify parameters of
captivity. However, this document does not describe a mechanism for such
devices to negotiate for unrestricted network access. A future document could provide a solution
to devices without user interfaces. This document focuses on devices
with user interfaces.
</t>
<t>
The architecture uses the following mechanisms:
</t>
<ul spacing="normal">
<li>Network provisioning protocols provide end-user devices with a
Uniform Resource Identifier <xref target="RFC3986"/> (URI) for
the API that end-user devices query for information about
what is required to escape captivity. DHCP, DHCPv6, and
Router-Advertisement options for this purpose are available in
<xref target="RFC7710bis"/>. Other protocols (such as RADIUS),
Provisioning Domains
<xref target="I-D.pfister-capport-pvd"/>, or
static configuration may also be used to convey this Captive Portal API URI.
A device MAY query this API at any time to determine whether the
network is holding the device in a captive state.
</li>
<li>A Captive Portal can signal User Equipment in response to transmissions by
the User Equipment. This signal works in response to any Internet protocol,
and is not done by modifying protocols in-band. This signal does not carry the
Captive Portal API URI; rather it provides a signal to the User Equipment that it
is in a captive state.
</li>
<li>
Receipt of a Captive Portal Signal provides a hint that User Equipment could be captive.
In response, the device MAY query the provisioned API to obtain
information about the network state.
The device can take immediate action to satisfy the portal
(according to its configuration/policy).
</li>
</ul>
<t>
The architecture attempts to provide confidentiality, authentication, and safety mechanisms
to the extent possible.
</t>
<section>
<name>Requirements Language</name>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 <xref target="RFC2119"/> <xref target="RFC8174"/> when, and only
when, they appear in all capitals, as shown here.
</t>
</section>
<section>
<name>Terminology</name>
<t>Captive Portal: A network which limits communication of attached
devices to restricted hosts until the user has satisfied
Captive Portal Conditions, after which access is permitted to a wider
set of hosts (typically the Internet).</t>
<t>Captive Portal Conditions: site-specific requirements that a user
or device must satisfy in order to gain access to the wider network.</t>
<t>Captive Portal Enforcement Device: The network equipment which enforces the
traffic restriction. Also known as Enforcement Device.</t>
<t>Captive Portal User Equipment: Also known as User Equipment. A device
which has voluntarily joined a network for purposes of communicating
beyond the constraints of the Captive Portal.</t>
<t>User Portal: The web server providing a user interface for
assisting the user in satisfying the conditions to escape
captivity.</t>
<t>Captive Portal API: Also known as API. An HTTP API allowing User Equipment
to query information about its state of captivity within the Captive Portal. This
information might include how to obtain full network access (e.g. by visting a URI).
</t>
<t>Captive Portal API Server: Also known as API Server. A server hosting the
Captive Portal API.
</t>
<t>Captive Portal Signal: A notification from the network used to signal to the User Equipment
that the state of its captivity could have changed.
</t>
<t>Captive Portal Signaling Protocol: Also known as Signaling Protocol. The protocol for
communicating Captive Portal Signals.
</t>
<t>
Captive Portal Session: Also referred to simply as the “session”, a Captive Portal
Session is the association for a particular User Equipment that starts when it
interacts with the Captive Portal and gains open access to the network, and ends
when the User Equipment moves back into the original captive state. The Captive
Network maintains the state of each active Session, and can limit Sessions based
on a length of time or a number of bytes used. The Session is associated with a
particular User Equipment using the User Equipment's identifier (see
<xref target="ue_identity"/>).
</t>
</section>
</section>
<section>
<name>Components</name>
<section anchor="section_client">
<name>User Equipment</name>
<t>
The User Equipment is the device that a user desires to be attached to
a network with full access to all hosts on the network (e.g., to have
Internet access). The User Equipment communication is typically
restricted by the Enforcement Device, described in <xref target="section_capport_enforcement"/>,
until site-specific requirements have been met.
</t>
<t>
This document only considers devices with web browsers, with web
applications being the means of satisfying Captive Portal Conditions.
An example of such User Equipment is a smart phone.
</t>
<t>
The User Equipment:
</t>
<ul spacing="normal">
<li>SHOULD support provisioning of the URI for the Captive Portal API (e.g., by DHCP)</li>
<li>SHOULD distinguish Captive Portal API access per network interface, in the manner
of Provisioning Domain Architecture <xref target="RFC7556"/>.</li>
<li>SHOULD have a non-spoofable mechanism for notifying the user of the Captive Portal</li>
<li>SHOULD have a web browser so that the user may navigate to the User Portal.</li>
<li>SHOULD support updates to the Captive Portal API URI from the network provisioning
service.</li>
<li>MAY prevent applications from using networks that do not grant full
network access. E.g., a device connected to a mobile network may
be connecting to a captive WiFi network; the operating system could
avoid updating the default route to a device on captive WiFi network until
network access restrictions have been lifted (excepting access to the User Portal) in
the new network. This has been termed "make before break".</li>
</ul>
<t>
None of the above requirements are mandatory because (a) we do not wish
to say users or devices must seek full access to the Captive Portal,
(b) the requirements may be fulfilled by manually visiting the captive
portal web application, and (c) legacy devices must continue to be
supported.
</t>
<t>
If User Equipment supports the Captive Portal API, it MUST validate the API server's
TLS certificate (see <xref target="RFC2818"/>) according to the procedures in
<xref target="RFC6125"/>. The API server's URI is obtained via a network
provisioning protocol, which will typically provide a hostname to be used
in TLS server certificate validation, against a DNS-ID in the server certificate.
If the API server is identified by IP address, the iPAddress subjectAltName
is used to validate the server certificate. An Enforcement Device SHOULD allow access to
any services that User Equipment could need to contact to perform certificate validation,
such as OCSP responders, CRLs, and NTP servers; see Section 4.1 of
<xref target="I-D.ietf-capport-api"/> for more information.
If certificate validation fails, User Equipment MUST NOT make any calls to the API
server.
</t>
<t>
The User Equipment can store the last response it received from the Captive Portal API
as a cached view of its state within the Captive Portal. This state can be used to
determine whether its Captive Portal Session is near expiry. For example, the User
Equipment might compare a timestamp indicating when the session expires to the current
time. Storing state in this way can reduce the need for communication with the
Captive Portal API. However, it could lead to the state becoming
stale if the User Equipment's view of the relevant conditions (byte quota, for example)
is not consistent with the Captive Portal API's.
</t>
</section>
<section anchor="section_provisioning">
<name>Provisioning Service</name>
<t>
The Provisioning Service is primarily responsible for providing a Captive
Portal API URI to the User Equipment when it connects to the network, and
later if the URI changes. The provisioning service could also be the same
service which is responsible for provisioning the User Equipment for
access to the Captive Portal (e.g., by providing it with an IP address).
This section discusses two mechanisms which may be used to provide the
Captive Portal API URI to the User Equipment.
</t>
<section anchor="section_dhcp">
<name>DHCP or Router Advertisements</name>
<t>
A standard for providing a Captive Portal API URI using DHCP or Router
Advertisements is described in <xref target="RFC7710bis"/>. The
captive portal architecture expects this URI to indicate the API described
in <xref target="section_api"/>.
</t>
</section>
<section anchor="section_pvd">
<name>Provisioning Domains</name>
<t>
Although still a work in progress,
<xref target="I-D.pfister-capport-pvd"/>
proposes a mechanism for User Equipment to be provided with PvD
Bootstrap Information containing the URI for the API described in
<xref target="section_api"/>.
</t>
</section>
</section>
<section anchor="section_api">
<name>Captive Portal API Server</name>
<t>
The purpose of a Captive Portal API is to permit a query of Captive
Portal state without interrupting the user. This API thereby removes
the need for User Equipment to perform clear-text "canary" (see
<xref target="app-additional"/>) queries to check for response tampering.
</t>
<t>
The URI of this API will have been provisioned to the User Equipment.
(Refer to <xref target="section_provisioning"/>).
</t>
<t>
This architecture expects the User Equipment to query the API when the
User Equipment attaches to the network and multiple times thereafter.
Therefore the API MUST support multiple repeated queries from the same
User Equipment and return the state of captivity for the equipment.
</t>
<t>
At minimum, the API MUST provide the state of captivity. Further the
API MUST be able to provide a URI for the User Portal. The scheme for
the URI MUST be https so that the User Equipment communicates with
the User Portal over TLS.
</t>
<t>
If the API receives a request for state that does not correspond to the
requesting User Equipment, the API SHOULD deny access. Given that the
API might use the User Equipment's identifier for authentication, this
requirement motivates <xref target="id_recommended_hard"/>.
</t>
<t>
A caller to the API needs to be presented with evidence that the content
it is receiving is for a version of the API that it supports. For an
HTTP-based interaction, such as in <xref target="I-D.ietf-capport-api"/>
this might be achieved by using a content type that is unique to the
protocol.
</t>
<t>
When User Equipment receives Captive Portal Signals, the User Equipment
MAY query the API to check its state of captivity.
The User Equipment SHOULD rate-limit these API queries in the event of
the signal being flooded. (See <xref target="Security"/>.)
</t>
<t>
The API MUST be extensible to support future use-cases by allowing
extensible information elements.
</t>
<t>
The API MUST use TLS to ensure server authentication.
The implementation of the API MUST ensure both confidentiality and
integrity of any information provided by or required by it.
</t>
<t>
This document does not specify the details of the API.
</t>
</section>
<section anchor="section_capport_enforcement">
<name>Captive Portal Enforcement Device</name>
<t>
The Enforcement Device component restricts the network access of
User Equipment according to site-specific policy. Typically User Equipment
is permitted access to a small number of services (according to the policies
of the network provider) and is denied general
network access until it satisfies the Captive Portal Conditions.
</t>
<t>
The Enforcement Device component:
</t>
<ul spacing="normal">
<li>Allows traffic to pass for User Equipment that is permitted to
use the network and has satisfied the Captive Portal Conditions.</li>
<li>Blocks (discards) traffic according to the site-specific policy
for User Equipment that has not yet satisfied the Captive Portal Conditions.</li>
<li>Optionally signals User Equipment using the Captive Portal Signaling protocol
if certain traffic is blocked.</li>
<li>Permits User Equipment that has not satisfied the Captive Portal Conditions
to access necessary APIs and web pages to fulfill requirements for escaping captivity.</li>
<li>Updates allow/block rules per User Equipment in response to operations
from the User Portal.</li>
</ul>
</section>
<section anchor="section_signal">
<name>Captive Portal Signal</name>
<t>
When User Equipment first connects to a network, or when there are changes in status,
the Enforcement Device could generate a signal toward the User Equipment. This signal
indicates that the User Equipment might need to contact the API Server to receive
updated information. For instance, this signal might be generated when the end of a
session is imminent, or when network access was denied.
For simplicity, and to reduce the attack surface, all signals SHOULD be considered
equivalent by the User Equipment: as a hint to contact the API.
If future solutions have multiple signal types, each type SHOULD be rate-limited
independently.
</t>
<t>
An Enforcement Device MUST rate-limit any signal generated in response to these conditions. See <xref target="section_signal_risks"/> for a discussion of
risks related to a Captive Portal Signal.
</t>
</section>
<section>
<name>Component Diagram</name>
<t>
The following diagram shows the communication between each component in the
case where the Captive Portal has a User Portal, and the User Equipment
chooses to visit the User Portal in response to discovering and interacting
with the API Server.
</t>
<figure anchor="components">
<name>Captive Portal Architecture Component Diagram</name>
<artwork><![CDATA[
o . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . o
. CAPTIVE PORTAL .
. +------------+ Join Network +--------------+ .
. | |+--------------------------->| Provisioning | .
. | | Provision API URI | Service | .
. | |<---------------------------+| | .
. | User | +--------------+ .
. | Equipment | Query captivity status +-------------+ .
. | |+--------------------------->| API | .
. | | Captivity status response | Server | .
. | |<---------------------------+| | .
. | | +------+------+ .
. | | | Status .
. | | Portal UI page requests +------+------+ .
. | |+--------------------------->| | .
. | | Portal UI pages | User Portal | .
. | |<---------------------------+| | .
. +------------+ | | .
. ^ ^ | +-------------+ .
. | | | Data to/from ext. network | .
. | | +-----------------> +---------------+ Allow/Deny .
. | +--------------------+| | Rules .
. | | Enforcement | | .
. | Captive Portal Signal | Device |<----+ .
. +-------------------------+---------------+ .
. ^ | .
. | | .
. Data to/from external network .
. | | .
o . . . . . . . . . . . . . . . . . . .| |. . . . . . . . . . . o
| v
EXTERNAL NETWORK
]]></artwork>
</figure>
<t>
In the diagram:
</t>
<ul spacing="normal">
<li>During provisioning (e.g., DHCP), and possibly later, the User
Equipment acquires the Captive Portal API URI.</li>
<li>The User Equipment queries the API to learn of its state of
captivity. If captive, the User Equipment presents the portal
user interface from the User Portal to the user.</li>
<li>Based on user interaction, the User Portal directs the
Enforcement Device to either allow or deny external network
access for the User Equipment.</li>
<li>The User Equipment attempts to communicate to the external
network through the Enforcement Device.</li>
<li>The Enforcement Device either allows the User
Equipment's packets to the external network, or blocks the
packets. If blocking traffic and a signal has
been implemented, it may respond with a Captive Portal Signal.</li>
</ul>
<t>
The Provisioning Service, API Server, and User Portal are
described as discrete functions. An implementation might provide the
multiple functions within a single entity. Furthermore, these functions, combined or not,
as well as the Enforcement Device, could be replicated for redundancy or scale.
</t>
</section>
</section>
<section anchor="ue_identity">
<name>User Equipment Identity</name>
<t>
Multiple components in the architecture interact with both the User
Equipment and each other. Since the User Equipment is the focus of
these interactions, the components must be able to both identify the
User Equipment from their interactions with it, and to agree
on the identity of the User Equipment when interacting with each
other.
</t>
<t>
The methods by which the components interact restrict the type of
information that may be used as an identifying characteristics. This
section discusses the identifying characteristics.
</t>
<section anchor="id_identifiers">
<name>Identifiers</name>
<t>
An Identifier is a characteristic of the User Equipment used by
the components of a Captive Portal to uniquely determine which
specific User Equipment is interacting with them.
An Identifier can be a field contained in packets
sent by the User Equipment to the External Network. Or, an
Identifier can be an ephemeral property not contained in packets
destined for the External Network, but instead correlated with
such information through knowledge available to the different
components.
</t>
</section>
<section anchor="id_recommended_props">
<name>Recommended Properties</name>
<t>
The set of possible identifiers is quite large. However, in order
to be considered a good identifier, an identifier SHOULD meet the
following criteria. Note that the optimal identifier will likely
change depending on the position of the components in the network
as well as the information available to them.
An identifier SHOULD:
</t>
<ul spacing="normal">
<li>uniquely identify the User Equipment</li>
<li>be hard to spoof</li>
<li>be visible to the API Server</li>
<li>be visible to the Enforcement Device</li>
</ul>
<t>
An identifier might only apply to the current point of network attachment. If the
device moves to a different network location its identity could change.
</t>
<section anchor="id_recommended_unique">
<name>Uniquely Identify User Equipment</name>
<t>
The Captive Portal MUST associate the User Equipment with an
identifier that is unique among the User Equipment that are
interacting with the Captive Portal at that time.
</t>
<t>
Over time, the User Equipment assigned to an identifier value MAY change. Allowing the
identified device to change over time ensures that the space of possible
identifying values need not be overly large.
</t>
<t>
Independent Captive Portals MAY use the same identifying value to identify
different User Equipment. Allowing independent captive portals to reuse
identifying values allows the identifier to be a property of the local
network, expanding the space of possible identifiers.
</t>
</section>
<section anchor="id_recommended_hard">
<name>Hard to Spoof</name>
<t>
A good identifier does not lend itself to being easily spoofed. At no time
should it be simple or straightforward for one User Equipment to
pretend to be another User Equipment, regardless of whether both are active
at the same time. This property is particularly important when the User
Equipment identifier is referenced externally by devices such as billing systems,
or where the identity of the User Equipment could imply liability.
</t>
</section>
<section anchor="id_recommended_visible_api">
<name>Visible to the API Server</name>
<t>
Since the API Server will need to perform operations which rely on the identity
of the User Equipment, such as answering a query about
whether the User Equipment is captive, the API Server needs
to be able to relate a request to the User Equipment making
the request.
</t>
</section>
<section anchor="id_recommended_visible_ed">
<name>Visible to the Enforcement Device</name>
<t>
The Enforcement Device will decide on a per-packet basis whether
the packet should be forwarded to the external network. Since
this decision depends on which User Equipment sent the packet, the
Enforcement Device requires that it be able to map the packet to its
concept of the User Equipment.
</t>
</section>
</section>
<section anchor="id_evaluating">
<name>Evaluating Types of Identifiers</name>
<t>
To evaluate whether a type of identifier is appropriate, one should consider
every recommended property from the perspective of interactions among
the components in the architecture. When comparing identifier types, choose
the one which best satisfies all of the recommended properties. The
architecture does not provide an exact measure of how well an identifier
type satisfies a given property; care should be taken in performing the
evaluation.
</t>
</section>
<section anchor="id_examples">
<name>Example Identifier Types</name>
<t>
This section provides some example identifier types, along with some
evaluation of whether they are suitable types. The list of identifier types
is not exhaustive. Other types may be used. An important point to note
is that whether a given identifier type is suitable depends heavily on the
capabilities of the components and where in the network the components exist.
</t>
<section anchor="id_example_interface">
<name>Physical Interface</name>
<t>
The physical interface by which the User Equipment is attached to the
network can be used to identify the User Equipment. This identifier type has
the property of being extremely difficult to spoof: the User Equipment is
unaware of the property; one User Equipment cannot manipulate its
interactions to appear as though it is another.
</t>
<t>
Further, if only a single User Equipment is attached to a given physical
interface, then the identifier will be unique. If multiple User Equipment
is attached to the network on the same physical interface, then this type
is not appropriate.
</t>
<t>
Another consideration related to uniqueness of the User Equipment is that
if the attached User Equipment changes, both the API Server and the
Enforcement Device MUST invalidate their state related to the User Equipment.
</t>
<t>
The Enforcement Device needs to be aware of the physical interface,
which constrains the environment: it must either be part of the device providing
physical access (e.g., implemented in firmware), or packets traversing the network
must be extended to include information about the source physical interface (e.g.
a tunnel).
</t>
<t>
The API Server faces a similar problem, implying that it should co-exist with the
Enforcement Device, or that the Enforcement Device should extend requests to it
with the identifying information.
</t>
</section>
<section anchor="id_example_IP_address">
<name>IP Address</name>
<t>
A natural identifier type to consider is the IP address of the User Equipment.
At any given time, no device on the network can have the same IP address
without causing the network to malfunction, so it is appropriate from the
perspective of uniqueness.
</t>
<t>
However, it may be possible to spoof the IP address, particularly for
malicious reasons where proper functioning of the network is not necessary
for the malicious actor. Consequently, any solution using the IP address
SHOULD proactively try to prevent spoofing of the IP address. Similarly,
if the mapping of IP address to User Equipment is changed, the components
of the architecture MUST remove or update their mapping to prevent spoofing.
Demonstrations of return routeability, such as that required for TCP
connection establishment, might be sufficient defense against spoofing,
though this might not be sufficient in networks that use broadcast media
(such as some wireless networks).
</t>
<t>
Since the IP address may traverse multiple segments of the network, more
flexibility is afforded to the Enforcement Device and the API Server: they
simply must exist on a segment of the network where the IP address is still
unique. However, consider that a NAT may be deployed between the User Equipment
and the Enforcement Device. In such cases, it is possible for the components
to still uniquely identify the device if they are aware of the port mapping.
</t>
<t>
In some situations, the User Equipment may have multiple IP addresses (either
IPv4, IPv6 or a dual-stack <xref target="RFC4213"/> combination), while
still satisfying all of the recommended properties. This raises some challenges
to the components of the network. For example, if the User Equipment tries
to access the network with multiple IP addresses, should the Enforcement Device
and API Server treat each IP address as a unique User Equipment, or should it
tie the multiple addresses together into one view of the subscriber?
An implementation MAY do either. Attention should be paid to IPv6 and the fact
that it is expected for a device to have multiple IPv6 addresses on a single
link. In such cases, identification could be performed by subnet, such as the /64
to which the IP belongs.
</t>
</section>
<section anchor="id_example_mac_address">
<name>Media Access Control (MAC) Address</name>
<t>
The MAC address of a device is often used as an identifier in existing implementations.
This document does not discuss the use of MAC addresses within a captive portal system, but they can be used
as an identifier type, subject to the criteria in <xref target="id_recommended_props"/>.
</t>
</section>
</section>
<section anchor="context_free_uri">
<name>Context-free URI</name>
<t>
A Captive Portal API needs to present information to clients
that is unique to that client. To do this, some systems use
information from the context of a request, such as the source
address, to identify the User Equipment.
</t>
<t>
Using information from context rather than information from the
URI allows the same URI to be used for different clients. However,
it also means that the resource is unable to provide relevant
information if the User Equipment makes a request using a different network
path. This might happen when User Equipment has multiple network interfaces.
It might also happen if the address of the API provided by DNS
depends on where the query originates (as in split DNS
<xref target="RFC8499"/>).
</t>
<t>
Accessing the API MAY depend on contextual information. However,
the URIs provided in the API SHOULD be unique to the User Equipment and not
dependent on contextual information to function correctly.
</t>
<t>
Though a URI might still correctly resolve when the User Equipment makes the
request from a different network, it is possible that some
functions could be limited to when the User Equipment makes requests using the
Captive Portal. For example, payment options could be absent or a
warning could be displayed to indicate the payment is not for the
current connection.
</t>
<t>
URIs could include some means of identifying the User Equipment in
the URIs. However, including unauthenticated User Equipment
identifiers in the URI may expose the service to spoofing or replay
attacks.
</t>
</section>
</section>
<section anchor="section_workflow">
<name>Solution Workflow</name>
<t>
This section aims to improve understanding by describing a possible
workflow of solutions adhering to the architecture. Note that the section is
not normative: it describes only as subset of possible implementations.
</t>
<section>
<name>Initial Connection</name>
<t>
This section describes a possible workflow when User Equipment initially
joins a Captive Portal.
</t>
<ol spacing="normal" type="1">
<li>The User Equipment joins the Captive Portal by acquiring a DHCP
lease, RA, or similar, acquiring provisioning information.</li>
<li>The User Equipment learns the URI for the Captive Portal API from the
provisioning information (e.g., <xref target="RFC7710bis"/>).</li>
<li>The User Equipment accesses the Captive Portal API to receive parameters
of the Captive Portal, including User Portal URI. (This step replaces
the clear-text query to a canary URI.)</li>
<li>If necessary, the User navigates to the User Portal to gain access to the
external network.</li>
<li>
If the User interacted with the User Portal to gain access to the external
network in the previous step, the User Portal indicates to the Enforcement
Device that the User Equipment is allowed to access the external network.
</li>
<li>The User Equipment attempts a connection outside the Captive Portal</li>
<li>If the requirements have been satisfied, the access is permitted;
otherwise the "Expired" behavior occurs.</li>
<li>The User Equipment accesses the network until conditions Expire.</li>
</ol>
</section>
<section>
<name>Conditions About to Expire</name>
<t>
This section describes a possible workflow when access is about to expire.
</t>
<ol spacing="normal" type="1">
<li>Precondition: the API has provided the User Equipment with a duration
over which its access is valid.</li>
<li>The User Equipment is communicating with the outside network.</li>
<li>
The User Equipment detects that the length of time left
for its access has fallen below a threshold by comparing its stored
expiry time with the current time.
</li>
<li>The User Equipment visits the API again to validate the expiry time.</li>
<li>If expiry is still imminent, the User Equipment prompts the user to access the
User Portal URI again.</li>
<li>The User accepts the prompt displayed by the User Equipment.</li>
<li>The User extends their access through the User Portal via the User Equipment's user interface.</li>
<li>The User Equipment's access to the outside network continues uninterrupted.</li>
</ol>
</section>
<section>
<name>Handling of Changes in Portal URI</name>
<t>A different Captive Portal API URI could be returned in the following cases:</t>
<ul spacing="normal">
<li>If DHCP is used, a lease renewal/rebind may return a different Captive
Portal API URI.</li>
<li>If RA is used, a new Captive Portal API URI may be specified in a new RA
message received by end User Equipment.</li>
</ul>
<t>When the Network Provisioning Service updates the Captive Portal API URI, the User
Equipment can retrieve updated state from the URI immediately, or it can wait
as it normally would until the expiry conditions it retrieved from the old URI are
about to expire.
</t>
</section>
</section>
<section anchor="Acknowledgments">
<name>Acknowledgments</name>
<t>The authors thank Lorenzo Colitti for providing the majority of the content
for the Captive Portal Signal requirements.</t>
<t>The authors thank Benjamin Kaduk for providing the content related to TLS
certificate validation of the API server.</t>
<t>The authors thank Michael Richardson for providing wording requiring DNSSEC and TLS to
operate without the user adding exceptions.</t>
<t>The authors thank various individuals for their feedback on
the mailing list and during the IETF98 hackathon:
David Bird,
Erik Kline,
Alexis La Goulette,
Alex Roscoe,
Darshak Thakore,
and Vincent van Dam.
</t>
</section>
<!-- Possibly a 'Contributors' section ... -->
<section anchor="IANA">
<name>IANA Considerations</name>
<t>This memo includes no request to IANA.</t>
</section>
<section anchor="Security">
<name>Security Considerations</name>
<!--All drafts are required to have a security considerations section. See RFC3552 -->
<section>
<name>Trusting the Network</name>
<t>
When joining a network, some trust is placed in the network operator.
This is usually considered to be a decision by a user on the basis of
the reputation of an organization. However, once a user makes such a
decision, protocols can support authenticating that a network is operated
by who claims to be operating it. The Provisioning Domain
Architecture <xref target="RFC7556"/> provides some discussion on
authenticating an operator.
</t>
<t>
The user makes an informed choice to visit and trust the Captive
Portal URI. Since the network provides Captive Portal URI to the user
equipment, the network SHOULD do so securely so that the user's trust in the
network can extend to their trust of the Captive Portal URI. E.g., the DHCPv6
AUTH option can sign this information.
</t>
<t>
If a user decides to incorrectly trust an attacking network, they might
be convinced to visit an attacking web page and unwittingly provide
credentials to an attacker. Browsers can authenticate servers but
cannot detect cleverly misspelled domains, for example.
</t>
<t>
Further, the possibility of an on-path attacker in an attacking network
introduces some risks. The attacker could redirect traffic to arbitrary
destinations. The attacker could analyze the user's
traffic leading to loss of confidentiality. Or, the attacker could modify
the traffic inline.
</t>
</section>
<section>
<name>Authenticated APIs</name>
<t>
The solution described here requires that when the User Equipment needs to
access the API server, the User Equipment authenticates the
server; see <xref target="section_client"/>.
</t>
<t>
The Captive Portal API URI might change during the Captive Portal Session.
The User Equipment can apply the same trust mechanisms to the new URI as it
did to the URI it received initially from the network provisioning service.
</t>
</section>
<section>
<name>Secure APIs</name>
<t>
The solution described here requires that the API be secured using TLS.
This is required to allow the User Equipment and API Server to exchange
secrets which can be used to validate future interactions. The API MUST
ensure the integrity of this information, as well as its confidentiality.
</t>
<t>
An attacker with access to this information might be able to
masquerade as a specific User Equipment when interacting with the API, which
could then allow them to masquerade as that User Equipment when interacting
with the User Portal. This could give them the ability to determine whether
the User Equipment has accessed the portal, or deny the User Equipment service
by ending their session using mechanisms provided by the User Portal, or consume that
User Equipment's quota. An attacker with the ability to modify the information
could deny service to the User Equipment, or cause them to appear as a different
User Equipment.
</t>
</section>
<section anchor="section_signal_risks">
<name>Risks Associated with the Signaling Protocol</name>
<t>
If a Signaling Protocol is implemented, it may be possible for any user on
the Internet to send signals in attempt to cause the receiving equipment to
communicate with the Captive Portal API. This has been considered, and implementations may
address it in the following ways:
</t>
<ul spacing="normal">
<li>The signal only signals to the User Equipment to query the API. It does not
carry any information which may mislead or misdirect the User Equipment.</li>
<li>Even when responding to the signal, the User Equipment securely authenticates
with API Servers.</li>
<li>Accesses to the Captive Portal API are rate-limited, reducing the impact of an
attack attempting to generate excessive load on either User Equipment or API.
Note that because there is only one type of signal and one type of API request in
response to the signal, this rate-limiting will not cause loss of signalling
information.
</li>
</ul>
</section>
<section>
<name>User Options</name>
<t>
The Captive Portal Signal could signal to the User Equipment that it is being held
captive. There is no requirement that the User Equipment do something
about this.
Devices MAY permit users to disable automatic reaction to
Captive Portal Signals indications for privacy reasons.
However, there would be the trade-off that the user doesn't get notified
when network access is restricted.
Hence, end-user devices MAY allow users to manually control captive
portal interactions, possibly on the granularity of Provisioning
Domains.
</t>
</section>
<section>
<name>Privacy</name>
<t>
<xref target="ue_identity"/> describes a mechanism by which all components within
the Captive Portal are designed to use the same identifier to uniquely identify
the User Equipment. This identifier could be abused to track the user.
Implementers and designers of Captive Portals should take care to ensure that
identifiers, if stored, are stored securely. Likewise, if any component
communicates the identifier over the network, it should ensure the confidentiality
of the identifier on the wire by using encryption such as TLS.
</t>
<t>
There are benefits to choosing mutable anonymous identifiers. For
example, User Equipment could cycle through multiple identifiers to help prevent
long-term tracking. However, if the components of the network use an internal
mapping to map the identity to a stable, long-term value in order to deal with
changing identifiers, they need to treat that value as sensitive information: an
attacker could use it to tie traffic back to the originating User Equipment,
despite the User Equipment having changed identifiers.
</t>
</section>
</section>
</middle>
<!-- *****BACK MATTER ***** -->
<back>
<!-- References split into informative and normative -->
<!-- There are 2 ways to insert reference entries from the citation libraries:
1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
(for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")
Both are cited textually in the same manner: by using xref elements.
If you use the PI option, xml2rfc will, by default, try to find included files in the same
directory as the including file. You can also define the XML_LIBRARY environment variable
with a value containing a set of directories to search. These can be either in the local
filing system or remote ones accessed by http (http://domain/dir/... ).-->
<references>
<name>References</name>
<references>
<name>Normative References</name>
<reference anchor="RFC2119" target="https://www.rfc-editor.org/info/rfc2119">
<front>
<title>Key words for use in RFCs to Indicate Requirement Levels</title>
<seriesInfo name="DOI" value="10.17487/RFC2119"/>
<seriesInfo name="RFC" value="2119"/>
<seriesInfo name="BCP" value="14"/>
<author initials="S." surname="Bradner" fullname="S. Bradner">
<organization/>