Additional information about the network characteristics can be retrieved based on the PvD ID. This set of information is called PvD Additional Information and is encoded as a JSON object [
RFC 8259]. This JSON object is restricted to the Internet JSON (I-JSON) profile, as defined in [
RFC 7493].
The purpose of this JSON object is to provide Additional Information to applications on a client host about the connectivity that is provided using a given interface and source address. It typically includes data that would be considered too large, or not critical enough, to be provided within an RA option. The information contained in this object
MAY be used by the operating system, network libraries, applications, or users in order to decide which set of PvDs should be used for which connection, as described in
Section 3.4.
The Additional Information related to a PvD is specifically intended to be optional and is targeted at optimizing or informing the behavior of user-facing hosts. This information can be extended to provide hints for host system behavior (such as captive portal or walled-garden PvD detection) or application behavior (describing application-specific services offered on a given PvD). This content may not be appropriate for light-weight IoT devices. IoT devices might need only a subset of the information and would in some cases prefer a smaller representation like Concise Binary Object Representation (CBOR) [
RFC 7049]. Delivering a reduced version of the PvD Additional Information designed for such devices is not defined in this document.
When the H-flag of the PvD Option is set, hosts
MAY attempt to retrieve the PvD Additional Information associated with a given PvD by performing an HTTP-over-TLS [
RFC 2818] GET query to
https://<PvD-ID>/.well-known/pvd. Inversely, hosts
MUST NOT do so whenever the H-flag is not set.
Recommendations for how to use TLS securely can be found in [
RFC 7525].
When a host retrieves the PvD Additional Information, it
MUST verify that the TLS server certificate is valid for the performed request, specifically, that a DNS-ID [
RFC 6125] on the certificate is equal to the PvD ID expressed as an FQDN. This validation indicates that the owner of the FQDN authorizes its use with the prefix advertised by the router. If this validation fails, hosts
MUST close the connection and treat the PvD as if it has no Additional Information.
HTTP requests and responses for PvD Additional Information use the "application/pvd+json" media type (see
Section 8.5). Clients
SHOULD include this media type as an Accept header field in their GET requests, and servers
MUST mark this media type as their Content-Type header field in responses.
Note that the DNS name resolution of the PvD ID, any connections made for certificate validation (such as Online Certificate Status Protocol (OCSP) [
RFC 6960]), and the HTTP request itself
MUST be performed using the considered PvD. In other words, the name resolution, PKI checks, source address selection, as well as the next-hop router selection
MUST be performed while exclusively using the set of configuration information attached with the PvD, as defined in
Section 3.4. In some cases, it may therefore be necessary to wait for an address to be available for use (e.g., once the Duplicate Address Detection or DHCPv6 processes are complete) before initiating the HTTP-over-TLS query. In order to address privacy concerns around linkability of the PvD HTTP connection with future user-initiated connections, if the host has a temporary address per [
RFC 4941] in this PvD, then it
SHOULD use a temporary address to fetch the PvD Additional Information and
MAY deprecate the used temporary address and generate a new temporary address afterward.
If the HTTP status of the answer is greater than or equal to 400, the host
MUST close its connection and consider that there is no PvD Additional Information. If the HTTP status of the answer is between 300 and 399, inclusive, it
MUST follow the redirection(s). If the HTTP status of the answer is between 200 and 299, inclusive, the response is expected to be a single JSON object.
After retrieval of the PvD Additional Information, hosts
MUST remember the last Sequence Number value received in an RA including the same PvD ID. Whenever a new RA for the same PvD is received with a different Sequence Number value, or whenever the expiry date for the additional information is reached, hosts
MUST deprecate the Additional Information and stop using it.
Hosts retrieving a new PvD Additional Information object
MUST check for the presence and validity of the mandatory fields specified in
Section 4.3. A retrieved object including an expiration time that is already past or missing a mandatory element
MUST be ignored.
In order to avoid synchronized queries toward the server hosting the PvD Additional Information when an object expires, object updates are delayed by a randomized backoff time.
-
When a host performs a JSON object update after it detected a change in the PvD Option Sequence Number, it MUST add a delay before sending the query. The target time for the delay is calculated as a random time between zero and 2(10 + Delay) milliseconds, where 'Delay' corresponds to the 4-bit unsigned integer in the last received PvD Option.
-
When a host last retrieved a JSON object at time A that includes an expiry time B using the "expires" key, and the host is configured to keep the PvD Additional Information up to date, it MUST add some randomness into its calculation of the time to fetch the update. The target time for fetching the updated object is calculated as a uniformly random time in the interval [(B-A)/2,B].
In the example in
Figure 2, the Delay field value is 1; this means that the host calculates its delay by choosing a uniformly random time between 0 and 2
(10 + 1) milliseconds, i.e., between 0 and 2048 milliseconds.
Since the Delay value is directly within the PvD Option rather than the object itself, an operator may perform a push-based update by incrementing the Sequence Number value while changing the Delay value depending on the criticality of the update and the capacity of its PvD Additional Information servers.
In addition to adding a random delay when fetching Additional Information, hosts
MUST enforce a minimum time between requesting Additional Information for a given PvD on the same network. This minimum time is
RECOMMENDED to be 10 seconds, in order to avoid hosts causing a denial-of-service on the PvD server. Hosts also
MUST limit the number of requests that are made to different PvD Additional Information servers on the same network within a short period of time. A
RECOMMENDED value is to issue no more than five PvD Additional Information requests in total on a given network within 10 seconds. For more discussion, see
Section 6.
The PvD Additional Information object includes a set of IPv6 prefixes (under the key "prefixes") that
MUST be checked against all the Prefix Information Options advertised in the RA. If any of the prefixes included in any associated PIO is not covered by at least one of the listed prefixes, the PvD Additional Information
MUST be considered to be a misconfiguration and
MUST NOT be used by the host. See
Section 4.4 for more discussion on handling such misconfigurations.
If the request for PvD Additional Information fails due to a TLS certificate validation error, an HTTP error, or because the retrieved file does not contain valid PvD JSON, hosts
MUST close any connection used to fetch the PvD Additional Information and
MUST NOT request the information for that PvD ID again for the duration of the local network attachment. If a host detects 10 or more such failures to fetch PvD Additional Information, the local network is assumed to be misconfigured or under attack and the host
MUST NOT make any further requests for any PvD Additional Information, belonging to any PvD ID, for the duration of the local network attachment. For more discussion, see
Section 6.
Whenever the H-flag is set in the PvD Option, a valid PvD Additional Information object
MUST be made available to all hosts receiving the RA by the network operator. In particular, when a captive portal is present, hosts
MUST still be allowed to perform DNS, certificate validation, and HTTP-over-TLS operations related to the retrieval of the object, even before logging into the captive portal.
Routers
SHOULD increment the PvD Option Sequence Number by one whenever a new PvD Additional Information object is available and should be retrieved by hosts. If the value exceeds what can be stored in the Sequence Number field, it
MUST wrap back to zero.
The server providing the JSON files
SHOULD also check whether the client address is contained by the prefixes listed in the Additional Information and
SHOULD return a 403 response code if there is no match.
The PvD Additional Information is a JSON object.
The following table presents the mandatory keys, which
MUST be included in the object:
JSON key |
Description |
Type |
Example |
identifier |
PvD ID FQDN |
String |
"pvd.example.com." |
expires |
Date after which this object is no longer valid
|
[RFC 3339] Date
|
"2020-05-23T06:00:00Z" |
prefixes |
Array of IPv6 prefixes valid for this PvD |
Array of strings |
["2001:db8:1::/48", "2001:db8:4::/48"] |
Table 1
A retrieved object that does not include all three of these keys at the root of the JSON object
MUST be ignored. All three keys need to be validated; otherwise, the object
MUST be ignored. The value stored for "identifier"
MUST be matched against the PvD ID FQDN presented in the PvD Option using the comparison mechanism described in
Section 3.4. The value stored for "expires"
MUST be a valid date in the future. If the PIO of the received RA is not covered by at least one of the "prefixes" key, the retrieved object
SHOULD be ignored.
The following table presents some optional keys that
MAY be included in the object.
JSON key |
Description |
Type |
Example |
dnsZones |
DNS zones searchable and accessible |
Array of strings |
["example.com", "sub.example.com"] |
noInternet |
No Internet; set to "true" when the PvD is restricted
|
Boolean |
true |
Table 2
It is worth noting that the JSON format allows for extensions. Whenever an unknown key is encountered, it
MUST be ignored along with its associated elements.
Private-use or experimental keys
MAY be used in the JSON dictionary. In order to avoid such keys colliding with the keys registered by IANA, implementers or vendors defining private-use or experimental keys
MUST create sub-dictionaries. If a set of PvD Additional Information keys are defined by an organization that has a formal URN namespace [
IANA-URN], the URN namespace
SHOULD be used as the top-level JSON key for the sub-dictionary. For other private uses, the sub-dictionary key
SHOULD follow the format of "vendor-*", where the "*" is replaced by the implementer's or vendor's identifier. For example, keys specific to the FooBar organization could use "vendor-foobar". If a host receives a sub-dictionary with an unknown key, the host
MUST ignore the contents of the sub-dictionary.
The following two examples show how the JSON keys defined in this document can be used:
{
"identifier": "cafe.example.com.",
"expires": "2020-05-23T06:00:00Z",
"prefixes": ["2001:db8:1::/48", "2001:db8:4::/48"],
}
{
"identifier": "company.foo.example.com.",
"expires": "2020-05-23T06:00:00Z",
"prefixes": ["2001:db8:1::/48", "2001:db8:4::/48"],
"vendor-foo":
{
"private-key": "private-value",
},
}
Hosts
MUST validate the TLS server certificate when retrieving PvD Additional Information, as detailed in
Section 4.1.
Hosts
MUST verify that all prefixes in all the RA PIOs are covered by a prefix from the PvD Additional Information. An adversarial router attempting to spoof the definition of an Explicit PvD, without the ability to modify the PvD Additional Information, would need to perform IPv6-to-IPv6 Network Prefix Translation (NPTv6) [
RFC 6296] in order to circumvent this check. Thus, this check cannot prevent all spoofing, but it can detect misconfiguration or mismatched routers that are not adding a NAT.
If NPTv6 is being added in order to spoof PvD ownership, the HTTPS server for Additional Information can detect this misconfiguration. The HTTPS server
SHOULD validate the source addresses of incoming connections (see
Section 4.1). This check gives reasonable assurance that NPTv6 was not used and restricts the information to the valid network users.If the PvD does not provision IPv4 (it does not include the L-flag in the RA), the server cannot validate the source addresses of connections using IPv4. Thus, the PvD ID FQDN for such PvDs
SHOULD NOT have a DNS A record.