| Network Working Group | J. Yasskin |
| Internet-Draft | K. Ueno |
| Intended status: Standards Track | |
| Expires: March 8, 2019 | September 04, 2018 |
Signed HTTP Exchanges Implementation Checkpoints
draft-yasskin-httpbis-origin-signed-exchanges-impl-02
This document describes checkpoints of draft-yasskin-http-origin-signed-responses to synchronize implementation between clients, intermediates, and publishers.
Discussion of this draft takes place on the HTTP working group mailing list (ietf-http-wg@w3.org), which is archived at https://lists.w3.org/Archives/Public/ietf-http-wg/.
The source code and issues list for this draft can be found in https://github.com/WICG/webpackage.
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on March 8, 2019.
Copyright (c) 2018 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
Each version of this document describes a checkpoint of [I-D.yasskin-http-origin-signed-responses] that can be implemented in sync by clients, intermediates, and publishers. It defines a technique to detect which version each party has implemented so that mismatches can be detected up-front.
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 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.
In the response of an HTTP exchange the server MAY include a Signature header field (Section 3.1) holding a list of one or more parameterised signatures that vouch for the content of the exchange. Exactly which content the signature vouches for can depend on how the exchange is transferred (Section 5).
The client categorizes each signature as “valid” or “invalid” by validating that signature with its certificate or public key and other metadata against the exchange’s headers and content (Section 3.5). This validity then informs higher-level protocols.
Each signature is parameterised with information to let a client fetch assurance that a signed exchange is still valid, in the face of revoked certificates and newly-discovered vulnerabilities. This assurance can be bundled back into the signed exchange and forwarded to another client, which won’t have to re-fetch this validity information for some period of time.
The Signature header field conveys a single signature for an exchange, accompanied by information about how to determine the authority of and refresh that signature. Each signature directly signs the exchange’s headers and identifies one of those headers that enforces the integrity of the exchange’s payload.
The Signature header is a Structured Header as defined by [I-D.ietf-httpbis-header-structure]. Its value MUST be a parameterised list (Section 3.3 of [I-D.ietf-httpbis-header-structure]), and the list MUST contain exactly one element. Its ABNF is:
Signature = sh-param-list
The parameterised identifier in the list MUST have parameters named “sig”, “integrity”, “validity-url”, “date”, “expires”, “cert-url”, and “cert-sha256”. This specification gives no meaning to the identifier itself, which can be used as a human-readable identifier for the signature. The present parameters MUST have the following values:
The “cert-url” parameter is not signed, so intermediates can update it with a pointer to a cached version.
The following header is included in the response for an exchange with effective request URI https://example.com/resource.html. Newlines are added for readability.
Signature: sig1; sig=*MEUCIQDXlI2gN3RNBlgFiuRNFpZXcDIaUpX6HIEwcZEc0cZYLAIga9DsVOMM+g5YpwEBdGW3sS+bvnmAJJiSMwhuBdqp5UY=*; integrity="digest/mi-sha256-03"; validity-url="https://example.com/resource.validity.1511128380"; cert-url="https://example.com/oldcerts"; cert-sha256=*W7uB969dFW3Mb5ZefPS9Tq5ZbH5iSmOILpjv2qEArmI=*; date=1511128380; expires=1511733180
The signature uses a secp256r1 certificate within https://example.com/.
It relies on the Digest response header with the mi-sha256-03 digest algorithm to guard the integrity of the response payload.
The signature includes a “validity-url” that includes the first time the resource was seen. This allows multiple versions of a resource at the same URL to be updated with new signatures, which allows clients to avoid transferring extra data while the old versions don’t have known security bugs.
The certificate at https://example.com/certs has a subjectAltName of example.com, meaning that if it and its signature validate, the exchange can be trusted as having an origin of https://example.com/.
To sign an exchange’s headers, they need to be serialized into a byte string. Since intermediaries and distributors might rearrange, add, or just reserialize headers, we can’t use the literal bytes of the headers as this serialization. Instead, this section defines a CBOR representation that can be embedded into other CBOR, canonically serialized (Section 3.4), and then signed.
The CBOR representation of a set of request and response metadata and headers is the CBOR ([RFC7049]) array with the following content:
Given the HTTP exchange:
GET / HTTP/1.1 Host: example.com Accept: */* HTTP/1.1 200 Content-Type: text/html Digest: mi-sha256-03=dcRDgR2GM35DluAV13PzgnG6+pvQwPywfFvAu1UeFrs= Signed-Headers: "content-type", "digest" <!doctype html> <html> ...
The cbor representation consists of the following item, represented using the extended diagnostic notation from [I-D.ietf-cbor-cddl] appendix G:
[
{
'accept': '*/*',
':method': 'GET',
},
{
'digest': 'mi-sha256-03=dcRDgR2GM35DluAV13PzgnG6+pvQwPywfFvAu1UeFrs=',
':status': '200',
'content-type': 'text/html'
}
]
The resource at a signature’s cert-url MUST have the application/cert-chain+cbor content type, MUST be canonically-encoded CBOR (Section 3.4), and MUST match the following CDDL:
cert-chain = [
"📜⛓", ; U+1F4DC U+26D3
+ {
cert: bytes,
? ocsp: bytes,
? sct: bytes,
* tstr => any,
}
]
The first map (second item) in the CBOR array is treated as the end-entity certificate, and the client will attempt to build a path ([RFC5280]) to it from a trusted root using the other certificates in the chain.
Loading a cert-url takes a forceFetch flag. The client MUST:
Within this specification, the canonical serialization of a CBOR item uses the following rules derived from Section 3.9 of [RFC7049] with erratum 4964 applied:
Note: this specification does not use floating point, tags, or other more complex data types, so it doesn’t need rules to canonicalize those.
The client MUST parse the Signature header field as the parameterised list (Section 4.2.3 of [I-D.ietf-httpbis-header-structure]) described in Section 3.1. If an error is thrown during this parsing or any of the requirements described there aren’t satisfied, the exchange has no valid signatures. Otherwise, each member of this list represents a signature with parameters.
The client MUST use the following algorithm to determine whether each signature with parameters is invalid or potentially-valid for an exchange’s
Potentially-valid results include:
This algorithm accepts a forceFetch flag that avoids the cache when fetching URLs. A client that determines that a potentially-valid certificate chain is actually invalid due to an expired OCSP response MAY retry with forceFetch set to retrieve an updated OCSP from the original server.
Note that the above algorithm can determine that an exchange’s headers are potentially-valid before the exchange’s payload is received. Similarly, if integrity identifies a header field and parameter like Digest: mi-sha256-03 ([I-D.thomson-http-mice]) that can incrementally validate the payload, early parts of the payload can be determined to be potentially-valid before later parts of the payload. Higher-level protocols MAY process parts of the exchange that have been determined to be potentially-valid as soon as that determination is made but MUST NOT process parts of the exchange that are not yet potentially-valid. Similarly, as the higher-level protocol determines that parts of the exchange are actually valid, the client MAY process those parts of the exchange and MUST wait to process other parts of the exchange until they too are determined to be valid.
Both OCSP responses and signatures are designed to expire a short time after they’re signed, so that revoked certificates and signed exchanges with known vulnerabilities are distrusted promptly.
This specification provides no way to update OCSP responses by themselves. Instead, clients need to re-fetch the “cert-url” to get a chain including a newer OCSP response.
The “validity-url” parameter of the signatures provides a way to fetch new signatures or learn where to fetch a complete updated exchange.
Each version of a signed exchange SHOULD have its own validity URLs, since each version needs different signatures and becomes obsolete at different times.
The resource at a “validity-url” is “validity data”, a CBOR map matching the following CDDL ([I-D.ietf-cbor-cddl]):
validity = {
? signatures: [ + bytes ]
? update: {
? size: uint,
}
]
The elements of the signatures array are parameterised identifiers (Section 4.2.4 of [I-D.ietf-httpbis-header-structure]) meant to replace the signatures within the Signature header field pointing to this validity data. If the signed exchange contains a bug severe enough that clients need to stop using the content, the signatures array MUST NOT be present.
If the the update map is present, that indicates that a new version of the signed exchange is available at its effective request URI (Section 5.5 of [RFC7230]) and can give an estimate of the size of the updated exchange (update.size). If the signed exchange is currently the most recent version, the update SHOULD NOT be present.
If both the signatures and update fields are present, clients can use the estimated size to decide whether to update the whole resource or just its signatures.
For example, say a signed exchange whose URL is https://example.com/resource has the following Signature header field (with line breaks included and irrelevant fields omitted for ease of reading).
Signature: sig1; sig=*MEUCIQ...*; ... validity-url="https://example.com/resource.validity.1511157180"; cert-url="https://example.com/oldcerts"; date=1511128380; expires=1511733180
At 2017-11-27 11:02 UTC, sig1 has expired, so the client needs to fetch https://example.com/resource.validity.1511157180 (the validity-url of sig1) if it wishes to update that signature. This URL might contain:
{
"signatures": [
'sig1; '
'sig=*MEQCIC/I9Q+7BZFP6cSDsWx43pBAL0ujTbON/+7RwKVk+ba5AiB3FSFLZqpzmDJ0NumNwN04pqgJZE99fcK86UjkPbj4jw==*; '
'validity-url="https://example.com/resource.validity.1511157180"; '
'integrity="digest/mi-sha256-03"'
'cert-url="https://example.com/newcerts"; '
'cert-sha256=*J/lEm9kNRODdCmINbvitpvdYKNQ+YgBj99DlYp4fEXw=*; '
'date=1511733180; expires=1512337980'
],
"update": {
"size": 5557452
}
}
This indicates that the client could fetch a newer version at https://example.com/resource (the original URL of the exchange), or that the validity period of the old version can be extended by replacing the original signature with the new signature provided. The signature of the updated signed exchange would be:
Signature: sig1; sig=*MEQCIC...*; ... validity-url="https://example.com/resource.validity.1511157180"; cert-url="https://example.com/newcerts"; date=1511733180; expires=1512337980
Signature header fields cost on the order of 300 bytes for ECDSA signatures, so servers might prefer to avoid sending them to clients that don’t intend to use them. A client can send the Accept-Signature header field to indicate that it does intend to take advantage of any available signatures and to indicate what kinds of signatures it supports.
When a server receives an Accept-Signature header field in a client request, it SHOULD reply with any available Signature header fields for its response that the Accept-Signature header field indicates the client supports. However, if the Accept-Signature value violates a requirement in this section, the server MUST behave as if it hadn’t received any Accept-Signature header at all.
The Accept-Signature header field is a Structured Header as defined by [I-D.ietf-httpbis-header-structure]. Its value MUST be a parameterised list (Section 3.3 of [I-D.ietf-httpbis-header-structure]). Its ABNF is:
Accept-Signature = sh-param-list
The order of identifiers in the Accept-Signature list is not significant. Identifiers, ignoring any initial “-“ character, MUST NOT be duplicated.
Each identifier in the Accept-Signature header field’s value indicates that a feature of the Signature header field (Section 3.1) is supported. If the identifier begins with a “-“ character, it instead indicates that the feature named by the rest of the identifier is not supported. Unknown identifiers and parameters MUST be ignored because new identifiers and new parameters on existing identifiers may be defined by future specifications.
Identifiers starting with “digest/” indicate that the client supports the Digest header field ({{!RFC3230) with the parameter from the HTTP Digest Algorithm Values Registry registry named in lower-case by the rest of the identifier. For example, “digest/mi-blake2” indicates support for Merkle integrity with the as-yet-unspecified mi-blake2 parameter, and “-digest/mi-sha256” indicates non-support for Merkle integrity with the mi-sha256 content encoding.
If the Accept-Signature header field is present, servers SHOULD assume support for “digest/mi-sha256-03” unless the header field states otherwise.
Identifiers starting with “ecdsa/” indicate that the client supports certificates holding ECDSA public keys on the curve named in lower-case by the rest of the identifier.
If the Accept-Signature header field is present, servers SHOULD assume support for “ecdsa/secp256r1” unless the header field states otherwise.
The “ed25519key” identifier has parameters indicating the public keys that will be used to validate the returned signature. Each parameter’s name is re-interpreted as binary content (Section 3.9 of [I-D.ietf-httpbis-header-structure]) encoding a prefix of the public key. For example, if the client will validate signatures using the public key whose base64 encoding is 11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=, valid Accept-Signature header fields include:
Accept-Signature: ..., ed25519key; *11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=* Accept-Signature: ..., ed25519key; *11qYAYKxCrfVS/7TyWQHOg==* Accept-Signature: ..., ed25519key; *11qYAQ==* Accept-Signature: ..., ed25519key; **
but not
Accept-Signature: ..., ed25519key; *11qYA===*
because 5 bytes isn’t a valid length for encoded base64, and not
Accept-Signature: ..., ed25519key; 11qYAQ
because it doesn’t start or end with the *s that indicate binary content.
Note that ed25519key; ** is an empty prefix, which matches all public keys, so it’s useful in subresource integrity cases like <link rel=preload as=script href="..."> where the public key isn’t known until the matching <script src="..." integrity="..."> tag.
Accept-Signature: digest/mi-sha256-03
states that the client will accept signatures with payload integrity assured by the Digest header and mi-sha256-03 digest algorithm and implies that the client will accept signatures from ECDSA keys on the secp256r1 curve.
Accept-Signature: -ecdsa/secp256r1, ecdsa/secp384r1
states that the client will accept ECDSA keys on the secp384r1 curve but not the secp256r1 curve and payload integrity assured with the Digest: mi-sha256-03 header field.
To determine whether to trust a cross-origin exchange, the client takes a Signature header field (Section 3.1) and the exchange’s
The client MUST parse the Signature header into a list of signatures according to the instructions in Section 3.5, and run the following algorithm for each signature, stopping at the first one that returns “valid”. If any signature returns “valid”, return “valid”. Otherwise, return “invalid”.
as described by Section 3.3 of
[RFC6962].As described in Section 6.1 of [I-D.yasskin-http-origin-signed-responses], a publisher can cause problems if they sign an exchange that includes private information. There’s no way for a client to be sure an exchange does or does not include private information, but header fields that store or convey stored state in the client are a good sign.
A stateful request header field informs the server of per-client state. These include but are not limited to:
A stateful response header field modifies state, including authentication status, in the client. The HTTP cache is not considered part of this state. These include but are not limited to:
We define a new X.509 extension, CanSignHttpExchanges to be used in the certificate when the certificate permits the usage of signed exchanges. When this extension is not present the client MUST NOT accept a signature from the certificate as proof that a signed exchange is authoritative for a domain covered by the certificate. When it is present, the client MUST follow the validation procedure in Section 4.
CanSignHttpExchanges ::= NULL
Note that this extension contains an ASN.1 NULL (bytes 05 00) because some implementations have bugs with empty extensions.
Leaf certificates without this extension need to be revoked if the private key is exposed to an unauthorized entity, but they generally don’t need to be revoked if a signing oracle is exposed and then removed.
CA certificates, by contrast, need to be revoked if an unauthorized entity is able to make even one unauthorized signature.
Certificates with this extension MUST be revoked if an unauthorized entity is able to make even one unauthorized signature.
Conforming CAs MUST NOT mark this extension as critical.
Clients MUST NOT accept certificates with this extension in TLS connections (Section 4.4.2.2 of [I-D.ietf-tls-tls13]).
This draft of the specification identifies the CanSignHttpExchanges extension with the id-ce-canSignHttpExchangesDraft OID:
id-ce-google OBJECT IDENTIFIER ::= { 1 3 6 1 4 1 11129 }
id-ce-canSignHttpExchangesDraft OBJECT IDENTIFIER ::= { id-ce-google 2 1 22 }
This OID might or might not be used as the final OID for the extension, so certificates including it might need to be reissued once the final RFC is published.
A signed exchange can be transferred in several ways, of which three are described here.
The signature for a signed exchange can be included in a normal HTTP response. Because different clients send different request header fields, and intermediate servers add response header fields, it can be impossible to have a signature for the exact request and response that the client sees. Therefore, when a client calls the validation procedure in Section 3.5) to validate the Signature header field for an exchange represented as a normal HTTP request/response pair, it MUST pass:
If the client relies on signature validity for any aspect of its behavior, it MUST ignore any header fields that it didn’t pass to the validation procedure.
The serialized headers of an exchange represented as a normal HTTP request/response pair (Section 2.1 of [RFC7230] or Section 8.1 of [RFC7540]) are the canonical serialization (Section 3.4) of the CBOR representation (Section 3.2) of the following request and response metadata and headers:
If the exchange’s Signed-Headers header field is not present, doesn’t parse as a Structured Header ([I-D.ietf-httpbis-header-structure]) or doesn’t follow the constraints on its value described in Section 5.1.2, the exchange has no serialized headers.
The Signed-Headers header field identifies an ordered list of response header fields to include in a signature. The request URL and response status are included unconditionally. This allows a TLS-terminating intermediate to reorder headers without breaking the signature. This can also allow the intermediate to add headers that will be ignored by some higher-level protocols, but Section 3.5 provides a hook to let other higher-level protocols reject such insecure headers.
This header field appears once instead of being incorporated into the signatures’ parameters because the signed header fields need to be consistent across all signatures of an exchange, to avoid forcing higher-level protocols to merge the header field lists of valid signatures.
Signed-Headers is a Structured Header as defined by [I-D.ietf-httpbis-header-structure]. Its value MUST be a list (Section 3.2 of [I-D.ietf-httpbis-header-structure]). Its ABNF is:
Signed-Headers = sh-list
Each element of the Signed-Headers list must be a lowercase string (Section 3.7 of [I-D.ietf-httpbis-header-structure]) naming an HTTP response header field. Pseudo-header field names (Section 8.1.2.1 of [RFC7540]) MUST NOT appear in this list.
Higher-level protocols SHOULD place requirements on the minimum set of headers to include in the Signed-Headers header field.
Cross origin push is not implemented.
To allow signed exchanges to be the targets of <link rel=prefetch> tags, we define the application/signed-exchange content type that represents a signed HTTP exchange, including request metadata and header fields, response metadata and header fields, and a response payload.
This content type consists of the concatenation of the following items:
To determine whether to trust a cross-origin exchange stored in an application/signed-exchange resource, pass the Signature header field’s value, fallbackUrl as the effective request URI, signedHeaders, and the payload body to the algorithm in Section 4.
An example application/signed-exchange file representing a possible signed exchange with https://example.com/ follows, with lengths represented by descriptions in <>s, CBOR represented in the extended diagnostic format defined in Appendix G of [I-D.ietf-cbor-cddl], and most of the Signature header field and payload elided with a …:
sxg1-b2\0<2-byte length of the following url string>
https://example.com/<3-byte length of the following header
value><3-byte length of the encoding of the
following array>sig1; sig=*...; integrity="digest/mi-sha256-03"; ...[
{
':method': 'GET',
'accept', '*/*'
},
{
':status': '200',
'content-type': 'text/html'
}
]<!doctype html>\r\n<html>...
All of the security considerations from Section 6 of [I-D.yasskin-http-origin-signed-responses] apply.
Normally, when a client fetches https://o1.com/resource.js, o1.com learns that the client is interested in the resource. If o1.com signs resource.js, o2.com serves it as https://o2.com/o1resource.js, and the client fetches it from there, then o2.com learns that the client is interested, and if the client executes the Javascript, that could also report the client’s interest back to o1.com.
Often, o2.com already knew about the client’s interest, because it’s the entity that directed the client to o1resource.js, but there may be cases where this leaks extra information.
For non-executable resource types, a signed response can improve the privacy situation by hiding the client’s interest from the original publisher.
To prevent network operators other than o1.com or o2.com from learning which exchanges were read, clients SHOULD only load exchanges fetched over a transport that’s protected from eavesdroppers. This can be difficult to determine when the exchange is being loaded from local disk, but when the client itself requested the exchange over a network it SHOULD require TLS ([I-D.ietf-tls-tls13]) or a successor transport layer, and MUST NOT accept exchanges transferred over plain HTTP without TLS.
This depends on the following IANA registrations in [I-D.yasskin-http-origin-signed-responses]:
This document also modifies the registration for:
Type name: application
Subtype name: signed-exchange
Required parameters:
Magic number(s): 73 78 67 31 2D 62 32 00
The other fields are the same as the registration in [I-D.yasskin-http-origin-signed-responses].
| [I-D.thomson-http-mice] | Thomson, M. and J. Yasskin, "Merkle Integrity Content Encoding", Internet-Draft draft-thomson-http-mice-03, August 2018. |
| [I-D.yasskin-http-origin-signed-responses-03] | Yasskin, J., "Signed HTTP Exchanges", Internet-Draft draft-yasskin-http-origin-signed-responses-03, March 2018. |
| [I-D.yasskin-http-origin-signed-responses-04] | Yasskin, J., "Signed HTTP Exchanges", Internet-Draft draft-yasskin-http-origin-signed-responses-04, June 2018. |
| [RFC2965] | Kristol, D. and L. Montulli, "HTTP State Management Mechanism", RFC 2965, DOI 10.17487/RFC2965, October 2000. |
| [RFC6265] | Barth, A., "HTTP State Management Mechanism", RFC 6265, DOI 10.17487/RFC6265, April 2011. |
| [RFC6454] | Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, December 2011. |
| [RFC6455] | Fette, I. and A. Melnikov, "The WebSocket Protocol", RFC 6455, DOI 10.17487/RFC6455, December 2011. |
| [RFC7235] | Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 10.17487/RFC7235, June 2014. |
| [RFC7615] | Reschke, J., "HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields", RFC 7615, DOI 10.17487/RFC7615, September 2015. |
| [RFC8053] | Oiwa, Y., Watanabe, H., Takagi, H., Maeda, K., Hayashi, T. and Y. Ioku, "HTTP Authentication Extensions for Interactive Clients", RFC 8053, DOI 10.17487/RFC8053, January 2017. |
| [W3C.NOTE-OPS-OverHTTP] | Hensley, P., Metral, M., Shardanand, U., Converse, D. and M. Myers, "Implementation of OPS Over HTTP", W3C NOTE NOTE-OPS-OverHTTP, June 1997. |
draft-02
Vs. draft-01:
draft-01
Vs. [I-D.yasskin-http-origin-signed-responses-04]:
draft-00
Vs. [I-D.yasskin-http-origin-signed-responses-03]:
Thanks to Devin Mullins, Ilari Liusvaara, Justin Schuh, Mark Nottingham, Mike Bishop, Ryan Sleevi, and Yoav Weiss for comments that improved this draft.