The API server endpoint MUST
be accessed over HTTP using an https URI [RFC 2818
] and SHOULD
use the default https port. 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 client SHOULD NOT
assume that the URI of the API server for a given network will stay the same and SHOULD
rely on the discovery or provisioning process each time it joins the network.
As described in [CAPPORT-ARCH
], the identity of the client needs to be visible to the Captive Portal API server in order for the server to correctly reply with the client's portal state. If the identifier used by the Captive Portal system is the client's set of IP addresses, the system needs to ensure that the same IP addresses are visible to both the API server and the enforcement device.
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 SHOULD
be distinct per client. Thus, depending on how the Captive Portal system is configured, the URI will be unique for each client host and between sessions for the same client host.
For example, a Captive Portal system that uses per-client session URIs could use "https://example.org/captive-portal/api/X54PD39JV" as its API URI.
The purpose of accessing the Captive Portal API over an HTTPS connection is twofold: first, the encrypted connection protects the integrity and confidentiality of the API exchange from other parties on the local network; second, it provides the client of the API an opportunity to authenticate the server that is hosting the API. This authentication allows the client to ensure that the entity providing the Captive Portal API has a valid certificate for the hostname provisioned by the network using the mechanisms defined in [RFC 8910
], by validating that a DNS-ID [RFC 6125
] on the certificate is equal to the provisioned hostname.
Clients performing revocation checking will need some means of accessing revocation information for certificates presented by the API server. Online Certificate Status Protocol [RFC 6960
] (OCSP) stapling, using the TLS Certificate Status Request extension [RFC 6066
be used. OCSP stapling allows a client to perform revocation checks without initiating new connections. To allow for other forms of revocation checking, especially for clients that do not support OCSP stapling, a captive network SHOULD
permit connections to OCSP responders or Certificate Revocation Lists (CRLs) that are referenced by certificates provided by the API server. For more discussion on certificate revocation checks, see Section 6.5
of RFC 7525
. In addition to connections to OCSP responders and CRLs, a captive network SHOULD
also permit connections to Network Time Protocol (NTP) [RFC 5905
] servers or other time-sync mechanisms to allow clients to accurately validate certificates.
Certificates with missing intermediate certificates that rely on clients validating the certificate chain using the URI specified in the Authority Information Access (AIA) extension [RFC 5280
] SHOULD NOT
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.
If the client is unable to validate the certificate presented by the API server, it MUST NOT
proceed with any of the behavior for API interaction described in this document. The client will proceed to interact with the captive network as if the API capabilities were not present. It may still be possible for the user to access the network if the network redirects a cleartext webpage to a web portal.