max-age-value = delta-seconds
delta-seconds = 1*DIGIT

Figure 2: max-age Value Syntax

delta-seconds is used as defined in [RFC7234], Section 1.2.1.

See Section 2.3.2 for limitations on the range of values for max-age.

2.1.2. The includeSubDomains Directive

The OPTIONAL includeSubDomains directive is a valueless directive that, if present (i.e., it is "asserted"), signals to the UA that the DANE Policy applies to this DANE Host as well as any subdomains of the host's domain name.

2.1.3. The required Directive

The OPTIONAL required directive is a valueless directive that, if present (i.e., it is "asserted"), signals to the UA that it MUST perform a DANE validation and if no DANE information is received (via network lookup or cache) the UA MUST NOT start a TLS connection or it MUST abort the TLS handshake. Because Section 4.1 of [RFC6698] allows fallback from DANE to PKIX, this directive is in place for Host operators to force both PKIX and DANE validation to take place to provide the additional protection on the connection.

2.1.4. Examples

DANE-Validation: max-age=31536000

The HDVA header field below stipulates that the HDVA Policy is to remain in effect for one year (there are approximately 31536000 seconds in a year), and the policy applies only to the domain of the HDVA Host issuing it:

DANE-Validation: max-age=15768000 ; includeSubDomains

The HDVA header field below stipulates that the HDVA Policy is to remain in effect for approximately six months and that the policy applies to the domain of the issuing HDVA Host and all of its subdomains:

DANE-Validation: max-age="31536000"

The max-age directive value can optionally be quoted:

DANE-Validation: max-age=0

The HDVA header field below indicates that the UA must delete the entire HDVA Policy associated with the HDVA Host that sent the header field:

DANE-Validation: max-age=0; includeSubDomains

The HDVA header field below has exactly the same effect as the one immediately above because the includeSubDomains directive's presence in the HDVA header field is ignored when max-age is zero:

DANE-Validation: max-age=15768000; required

The HDVA header field below states that if the UA MUST receive and validate DANE information, and if it does not it MUST close the connection:

2.2. Server Processing Model

This section describes the processing model that DANE Hosts implement. The model has 2 parts: (1) the processing rules for HTTP request messages received over a secure transport (e.g. authenticated, non-anonymous TLS); and (2) the processing rules for HTTP request messages received over non-secure transports, such as TCP.

2.2.1. HTTP-over-Secure-Transport Request Type

When replying to an HTTP request that was conveyed over a secure transport, a DANE Host SHOULD include in its response exactly one DVA header field and MUST satisfy the grammar specified in Section 2.1.

Establishing a given host as a Known DANE Host, in the context of a given UA, is accomplished as follows:

1. Over the HTTP protocol running over secure transport, by correctly returning (per this specification) at least one valid DVA header field to the UA.
2. Through other mechanisms, such as a client-side pre-loaded Known DANE Host List.

2.2.2. HTTP Request Type

DANE Hosts MAY include the DVA header field in HTTP redirects conveyed over non-secure transport. Hosts may choose to do this if they wish to operate using the TLSA usages of DANE-EE or DANE-TA (as defined in [RFC7218].

2.3. User Agent Processing Model

The UA processing model relies on parsing domain names. Note that internationalized domain names SHALL be canonicalized according to the scheme in Section 10 of [RFC6797].

2.3.1. DANE-Validation Response Header Field Processing

If the UA receives, over a secure transport, an HTTP response that includes a DVA header field conforming to the grammar specified in Section 2.1, and there are no underlying secure transport errors or warnings (see Section 2.4), the UA MUST either:

• Note the host as a Known DANE Host if it is not already so noted (see Section 2.3.2)

or

• Update the UA's cached information for the Known DANE Host if any of the max-age, includeSubDomains, or required header field value directives convey information different from that already maintained by the UA.

The max-age value is essentially a "time to live" value relative to the time of the most recent observation of the DVA header field. If the max-age header field value token has a value of 0, the UA MUST remove its cached DANE Policy information (including the includeSubDomains directive, if asserted) if the DANE Host is Known, or, MUST NOT note this DANE Host if it is not yet Known.

If a UA receives more than one DVA header field in an HTTP response message over secure transport, then the UA MUST process only the first DVA header field.

If the UA receives the HTTP response over non-secure transport it MUST NOT note the host as a DVA host. To allow the validation of DANE-EE and DANE-TA TLSA usages, a UA MAY accept DVA headers as a 'hint' to perform DANE Validation on the connection.

If the DVA header is not a Valid DANE Header (see Section 2.4), the UA MUST ignore any present DVA header field(s). The UA MUST ignore any DVA header fields not conforming to the grammar specified in Section 2.1.

2.3.2. Noting a DANE Host - Storage Model

The Effective Date of a Known DANE Host is the time that the UA observed a Valid DANE Header for the host. The Effective Expiration Date of a Known DANE Host is the Effective Date plus the max-age. A Known DANE Host is "expired" if the Effective Expiration Date refers to a date in the past. The UA MUST ignore any expired Known DANE Hosts in its cache.

For example, if a UA is beginning to perform DANE Validation for a Known DANE Host and finds that the cached information for the host indicates an Effective Expiration Date in the past, the UA MUST NOT continue with DANE Validation for the host, and must consider the host to no longer be a Known DANE Host.

Known DANE Hosts are identified only by domain names, and never IP addresses. If the substring matching the host production from the Request-URI (of the message to which the host responded) syntactically matches the IP-literal or IPv4address productions from Section 3.2.2 of [RFC3986], then the UA MUST NOT note this host as a Known DANE Host.

Otherwise, if the substring does not congruently match an existing Known DANE Host's domain name, per the matching procedure specified in Section 8.2 of [RFC6797], then the UA MUST add this host to the Known DANE Host cache. The UA caches the following information:

• the DANE Host's domain name
• the Effective Expiration Date, or enough information to calculate it (the Effective Date and the value of the max-age directive)
• whether or not the includeSubDomains directive is asserted
• whether or not the required directive is asserted

If any other metadata from optional or future DVA header directives are present in the Valid DANE Header, and the UA understands them, the UA MAY note them as well.

UAs MAY set an upper limit on the value of max-age, so that UAs that have noted erroneous DANE Validation Assertions (whether by accident or due to attack) have some chance of aging out over time. If the server sets a max-age greater than the UA's upper limit, the UA MAY behave as if the server set the max-age to the UA's upper limit. For example, if the UA caps max-age at 5184000 seconds (60 days), and a DANE Host sets a max-age directive of 90 days in its Valid DANE Header, the UA MAY behave as if the max-age were effectively 60 days. (One way to achieve this behavior is for the UA to simply store a value of 60 days instead of the 90 day value provided by the DANE Host.) For UA implementation guidance on how to select a maximum max-age, see Section 3.1.

The UA MUST NOT modify any metadata of any superdomain matched Known DANE Host.

2.3.3. HTTP-Equiv <Meta> Element Attribute

UAs MUST NOT heed http-equiv="DANE-Validation" attribute settings on <meta> elements [W3C.REC-html401-19991224] in received content.

2.4. Noting DANE Hosts

Upon receipt of the DVA response header field, the UA notes the host as a Known DANE Host, storing the Host and associated directives in non-volatile storage (for example, along with the HSTS or HPKP metadata). The associated directives are collectively known as DANE Metadata.

The UA MUST note the Host as a DANE Host if and only if it received the DVA response header field over an error-free TLS connection. If the host is a DANE Host, this includes the validation added in Section 2.5.

If the DVA response header field does not meet the above criteria, the UA MUST NOT note the host as a DANE Host. A DVA response header field that meets all these criteria is known as a Valid DANE Header.

Whenever a UA receives a Valid DANE Header, it MUST set its DANE Metadata to the exact Effective Expiration Date (computed from max-age), and note any associated directives if present.

For forward compatibility, the UA MUST ignore any unrecognized DVA header directives, while still processing those directives it does recognize. Section 2.1 specifies the directives max-age, includeSubDomains, and required but future specifications and implementations might use additional directives.

2.5. Validating DANE Connections

When a UA connects to a Known DANE Host using a TLS connection, the UA SHOULD perform a DANE Validation on the Host, as soon as possible (e.g. immediately after receiving the Server Certificate message). A DANE Validation follows the procedure for comparing a certificate association from a TLSA record and a certificate from the TLS handshake as defined in [RFC6698].)

If no TLSA records were received for evaluation and the host's DANE Metadata includes an asserted required directive, the UA MUST terminate the connection.

If the connection has no errors in the DANE Validation, the UA will determine whether to apply any additional correctness checks such as Pin Validation [I-D.ietf-websec-key-pinning], or applying an HTTP Strict Transport Security Policy [RFC6797].

2.6. Interactions With Preloaded DANE Host Lists

UAs MAY choose to implement additional sources of DANE Host information, such as through built-in lists of host information. Such UAs should allow users to override such additional sources, including disabling them from consideration.

The effective policy for a Known DANE Host that has both built-in hosts and hosts from previously observed DVA header response fields is implementation-defined.

2.7. TLSA Certificate Usages in DANE

HDVA is able to interoperate with UAs that support DANE and those that do not. For Hosts that use PKIX-TA or PKIX-EE certificate validation will occur both with and without DANE. Hosts that expect to use DANE-TA or DANE-EE should not expect to interoperate with UAs that do not support DANE. Conversely, hosts that choose PKIX-TA or PKIX-EE should not expect full interoperation with UAs that do not include a full list of trust authorities.

UAs that choose to accept and validate DVA headers over non-secure transport as a 'hint' to perform a DANE Validation MUST do so in according with Section 2.3.1 and MUST allow DANE-TA and DANE-EE usages for the initial connection and given a successful DANE Validation note the TLS connection as error-free.

3. Security Considerations

HTTP DANE-Validation Assertions allow hosts to strongly assert their intention for additional validation of their cryptographic identity. This document concerns the expression, conveyance, and enforcement of the DANE Validation policy.

See [RFC6698] for security considerations relating to a DANE Validation.

This document adds the concept of a required directive that requires the UA to receive TLSA records when communicating with a DANE Host over secure transport. When the host asserts the required directive there is additional risk of an active network attacker blocking DANE information from reaching the UA. This scenario would effectively create a denial of service for the victim of the attack. This is also a concern in some networks, which are configured in such a manner as to effectively block DANE information. If a host chooses to assert the required directive, they should consider clients that may not be able to get DANE information and consider the associated risks when asserting that directive. Without the required directive, an active network attacker could potentially block DANE information from reaching the victim and force validation of the connection to precede without any DANE information this would circumvent the additional out-of-band checks and rely on the UA's normal cryptographic identity validation, which could allow an attacker to man-in-the-middle the connection with a certificate that would otherwise fail DANE Validation.

To help mitigate this risk UAs SHOULD cache TLSA records as mentioned in Section 8.2 of [RFC6698]. In addition, if a UA does a pre-fetch for IP address, they should also prefetch TLSA records for DANE Hosts. Furthermore, UAs can receive TLSA records through another medium such as TLS extensions, HTTP, or other methods, which may not be blocked or be faster than DNS itself.

To discover attacks on a host that does not assert the required directive, over a network where an attacker is blocking the TLSA records from reaching a UA, the host may also employ the Report-Only directive from [I-D.ietf-websec-key-pinning].

3.1. Maximum max-age

As mentioned in Section 2.3.2, UAs MAY cap the max-age value at some upper limit. There is a security trade-off in that low maximum values provide a narrow window of protection for users who visit the Known DANE Host only infrequently, while high maximum values may potentially result in a UA's inability to successfully perform DANE Validation on hosts that assert the required directive should they choose to remove the TLSA record from the domain. Also, if a host has removed the TLSA records, a long max-age would create longer initial connection times while the UA attempts to retrieve a non-existent TLSA record.

There is likely no ideal upper limit to the max-age directive that would satisfy all use cases. However, a value on the order of 60 days (5,184,000 seconds) may be considered a balance between the two competing security concerns.

3.2. Using includeSubDomains Safely

It may happen that DANE Hosts whose hostnames share a parent domain use different Valid DVA Headers. If a host whose hostname is a parent domain for another host sets the includeSubDomains directive, the two hosts' DANE policies may conflict with each other. For example, consider two Known DANE Hosts, example.com and subdomain.example.com. Assume example.com sets a Valid DVA Header such as this:

DANE-Validation: max-age=12000; required; includeSubDomains

DANE-Validation: max-age=12000;