Network Working Group J. Yasskin Internet-Draft Google Intended status: Standards Track January 26, 2018 Expires: July 30, 2018 Signed HTTP Exchanges draft-yasskin-http-origin-signed-responses-02 Abstract This document specifies how a server can send an HTTP request/ response pair, known as an exchange, with signatures that vouch for that exchange's authenticity. These signatures can be verified against an origin's certificate to establish that the exchange is authoritative for an origin even if it was transferred over a connection that isn't. The signatures can also be used in other ways described in the appendices. These signatures contain countermeasures against downgrade and protocol-confusion attacks. Note to Readers 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/ [1]. The source code and issues list for this draft can be found in https://github.com/WICG/webpackage [2]. Status of This Memo 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 July 30, 2018. Yasskin Expires July 30, 2018 [Page 1] Internet-Draft Signed HTTP Exchanges January 2018 Copyright Notice 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Signing an exchange . . . . . . . . . . . . . . . . . . . . . 5 3.1. The Signed-Headers Header . . . . . . . . . . . . . . . . 5 3.2. The Signature Header . . . . . . . . . . . . . . . . . . 6 3.2.1. Examples . . . . . . . . . . . . . . . . . . . . . . 7 3.2.2. Open Questions . . . . . . . . . . . . . . . . . . . 8 3.3. Significant headers of an exchange . . . . . . . . . . . 9 3.3.1. Open Questions . . . . . . . . . . . . . . . . . . . 9 3.4. CBOR representation of exchange headers . . . . . . . . . 9 3.4.1. Example . . . . . . . . . . . . . . . . . . . . . . . 10 3.5. Canonical CBOR serialization . . . . . . . . . . . . . . 10 3.6. Signature validity . . . . . . . . . . . . . . . . . . . 11 3.6.1. Open Questions . . . . . . . . . . . . . . . . . . . 15 3.7. Updating signature validity . . . . . . . . . . . . . . . 15 3.7.1. Examples . . . . . . . . . . . . . . . . . . . . . . 16 3.8. The Accept-Signature header . . . . . . . . . . . . . . . 18 3.8.1. Integrity labels . . . . . . . . . . . . . . . . . . 19 3.8.2. Key type labels . . . . . . . . . . . . . . . . . . . 19 3.8.3. Key value labels . . . . . . . . . . . . . . . . . . 19 3.8.4. Examples . . . . . . . . . . . . . . . . . . . . . . 20 3.8.5. Open Questions . . . . . . . . . . . . . . . . . . . 20 4. HTTP/2 extension for cross-origin Server Push . . . . . . . . 21 4.1. Indicating support for cross-origin Server Push . . . . . 21 4.2. NO_TRUSTED_EXCHANGE_SIGNATURE error code . . . . . . . . 21 4.2.1. Open Questions . . . . . . . . . . . . . . . . . . . 22 4.3. Validating a cross-origin Push . . . . . . . . . . . . . 22 4.3.1. Validating a certificate chain for an authority . . . 22 4.3.2. Open Questions . . . . . . . . . . . . . . . . . . . 23 5. application/http-exchange+cbor format for HTTP/1 compatibility . . . . . . . . . . . . . . . . . . . . . . . . 23 Yasskin Expires July 30, 2018 [Page 2] Internet-Draft Signed HTTP Exchanges January 2018 5.1. Example . . . . . . . . . . . . . . . . . . . . . . . . . 25 5.2. Open Questions . . . . . . . . . . . . . . . . . . . . . 25 6. Security considerations . . . . . . . . . . . . . . . . . . . 25 6.1. Confidential data . . . . . . . . . . . . . . . . . . . . 25 6.2. Off-path attackers . . . . . . . . . . . . . . . . . . . 25 6.3. Downgrades . . . . . . . . . . . . . . . . . . . . . . . 26 6.4. Signing oracles are permanent . . . . . . . . . . . . . . 26 6.5. Unsigned headers . . . . . . . . . . . . . . . . . . . . 26 6.6. application/http-exchange+cbor . . . . . . . . . . . . . 27 7. Privacy considerations . . . . . . . . . . . . . . . . . . . 27 8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 27 8.1. Signature Header Field Registration . . . . . . . . . . . 28 8.2. HTTP/2 Settings . . . . . . . . . . . . . . . . . . . . . 28 8.3. HTTP/2 Error code . . . . . . . . . . . . . . . . . . . . 28 8.4. Internet Media Type application/http-exchange+cbor . . . 28 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 29 9.1. Normative References . . . . . . . . . . . . . . . . . . 29 9.2. Informative References . . . . . . . . . . . . . . . . . 31 9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Appendix A. Use cases . . . . . . . . . . . . . . . . . . . . . 33 A.1. PUSHed subresources . . . . . . . . . . . . . . . . . . . 33 A.2. Explicit use of a content distributor for subresources . 34 A.3. Subresource Integrity . . . . . . . . . . . . . . . . . . 35 A.4. Binary Transparency . . . . . . . . . . . . . . . . . . . 35 A.5. Static Analysis . . . . . . . . . . . . . . . . . . . . . 35 A.6. Offline websites . . . . . . . . . . . . . . . . . . . . 36 Appendix B. Requirements . . . . . . . . . . . . . . . . . . . . 36 B.1. Proof of origin . . . . . . . . . . . . . . . . . . . . . 36 B.1.1. Certificate constraints . . . . . . . . . . . . . . . 36 B.1.2. Signature constraints . . . . . . . . . . . . . . . . 37 B.1.3. Retrieving the certificate . . . . . . . . . . . . . 37 B.2. How much to sign . . . . . . . . . . . . . . . . . . . . 37 B.2.1. Conveying the signed headers . . . . . . . . . . . . 38 B.3. Response lifespan . . . . . . . . . . . . . . . . . . . . 39 B.3.1. Certificate revocation . . . . . . . . . . . . . . . 39 B.3.2. Response downgrade attacks . . . . . . . . . . . . . 39 Appendix C. Determining validity using cache control . . . . . . 40 C.1. Example of updating cache control . . . . . . . . . . . . 40 C.2. Downsides of updating cache control . . . . . . . . . . . 41 Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 42 Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 42 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 42 1. Introduction Signed HTTP exchanges provide a way to prove the authenticity of a resource in cases where the transport layer isn't sufficient. This can be used in several ways: Yasskin Expires July 30, 2018 [Page 3] Internet-Draft Signed HTTP Exchanges January 2018 o When signed by a certificate ([RFC5280]) that's trusted for an origin, an exchange can be treated as authoritative for that origin, even if it was transferred over a connection that isn't authoritative (Section 9.1 of [RFC7230]) for that origin. See Appendix A.1 and Appendix A.2. o A top-level resource can use a public key to identify an expected author for particular subresources, a system known as Subresource Integrity ([SRI]). An exchange's signature provides the matching proof of authorship. See Appendix A.3. o A signature can vouch for the exchange in some way, for example that it appears in a transparency log or that static analysis indicates that it omits certain attacks. See Appendix A.4 and Appendix A.5. Subsequent work toward the use cases in [I-D.yasskin-webpackage-use-cases] will provide a way to group signed exchanges into bundles that can be transmitted and stored together, but single signed exchanges are useful enough to standardize on their own. 2. Terminology Author The entity that controls the server for a particular origin [RFC6454]. The author can get a CA to issue certificates for their private keys and can run a TLS server for their origin. Exchange (noun) An HTTP request/response pair. This can either be a request from a client and the matching response from a server or the request in a PUSH_PROMISE and its matching response stream. Defined by Section 8 of [RFC7540]. Intermediate An entity that fetches signed HTTP exchanges from an author or another intermediate and forwards them to another intermediate or a client. Client An entity that uses a signed HTTP exchange and needs to be able to prove that the author vouched for it as coming from its claimed origin. Unix time Defined by [POSIX] section 4.16 [3]. 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. Yasskin Expires July 30, 2018 [Page 4] Internet-Draft Signed HTTP Exchanges January 2018 3. Signing an exchange As a response to an HTTP request or as a Server Push (Section 8.2 of [RFC7540]) the server MAY include a "Signed-Headers" header field (Section 3.1) identifying significant (Section 3.3) header fields and a "Signature" header field (Section 3.2) holding a list of one or more parameterised signatures that vouch for the content of the response. The client categorizes each signature as "valid" or "invalid" by validating that signature with its certificate or public key and other metadata against the significant headers and content (Section 3.6). 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. 3.1. The Signed-Headers Header 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.6 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 significant 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. See Appendix B.2 for a discussion of why only the URL from the request is included and not other request headers. "Signed-Headers" is a Structured Header as defined by [I-D.ietf-httpbis-header-structure]. Its value MUST be a list (Section 4.8 of [I-D.ietf-httpbis-header-structure]) of lowercase strings (Section 4.2 of [I-D.ietf-httpbis-header-structure]) naming HTTP response header fields. Pseudo-header field names (Section 8.1.2.1 of [RFC7540]) MUST NOT appear in this list. Yasskin Expires July 30, 2018 [Page 5] Internet-Draft Signed HTTP Exchanges January 2018 Higher-level protocols SHOULD place requirements on the minimum set of headers to include in the "Signed-Headers" header field. 3.2. The Signature Header The "Signature" header field conveys a list of signatures for an exchange, each one accompanied by information about how to determine the authority of and refresh that signature. Each signature directly signs the significant headers of the exchange 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 list (Section 4.8 of [I-D.ietf-httpbis-header-structure]) of parameterised labels (Section 4.4 of [I-D.ietf-httpbis-header-structure]). Each parameterised label MUST have parameters named "sig", "integrity", "validityUrl", "date", and "expires". Each parameterised label MUST also have either "certUrl" and "certSha256" parameters or an "ed25519Key" parameter. This specification gives no meaning to the label itself, which can be used as a human-readable identifier for the signature (see Section 3.2.2, Paragraph 1). The present parameters MUST have the following values: "sig" Binary content (Section 4.5 of [I-D.ietf-httpbis-header-structure]) holding the signature of most of these parameters and the significant headers of the exchange (Section 3.3). "integrity" A string (Section 4.2 of [I-D.ietf-httpbis-header-structure]) containing the lowercase name of the response header field that guards the response payload's integrity. "certUrl" A string (Section 4.2 of [I-D.ietf-httpbis-header-structure]) containing a valid URL string [4]. "certSha256" Binary content (Section 4.5 of [I-D.ietf-httpbis-header-structure]) holding the SHA-256 hash of the first certificate found at "certUrl". "ed25519Key" Binary content (Section 4.5 of [I-D.ietf-httpbis-header-structure]) holding an Ed25519 public key ([RFC8032]). Yasskin Expires July 30, 2018 [Page 6] Internet-Draft Signed HTTP Exchanges January 2018 "validityUrl" A string (Section 4.2 of [I-D.ietf-httpbis-header-structure]) containing a valid URL string [5]. "date" and "expires" An unsigned integer (Section 4.1 of [I-D.ietf-httpbis-header-structure]) representing a Unix time. The "certUrl" parameter is _not_ signed, so intermediates can update it with a pointer to a cached version. 3.2.1. Examples 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="mi"; validityUrl="https://example.com/resource.validity.1511128380"; certUrl="https://example.com/oldcerts"; certSha256=*W7uB969dFW3Mb5ZefPS9Tq5ZbH5iSmOILpjv2qEArmI; date=1511128380; expires=1511733180, sig2; sig=*MEQCIGjZRqTRf9iKNkGFyzRMTFgwf/BrY2ZNIP/dykhUV0aYAiBTXg+8wujoT4n/W+cNgb7pGqQvIUGYZ8u8HZJ5YH26Qg; integrity="mi"; validityUrl="https://example.com/resource.validity.1511128380"; certUrl="https://example.com/newcerts"; certSha256=*J/lEm9kNRODdCmINbvitpvdYKNQ+YgBj99DlYp4fEXw; date=1511128380; expires=1511733180, srisig; sig=*lGZVaJJM5f2oGczFlLmBdKTDL+QADza4BgeO494ggACYJOvrof6uh5OJCcwKrk7DK+LBch0jssDYPp5CLc1SDA integrity="mi"; validityUrl="https://example.com/resource.validity.1511128380"; ed25519Key=*zsSevyFsxyZHiUluVBDd4eypdRLTqyWRVOJuuKUz+A8 date=1511128380; expires=1511733180, thirdpartysig; sig=*MEYCIQCNxJzn6Rh2fNxsobktir8TkiaJYQFhWTuWI1i4PewQaQIhAMs2TVjc4rTshDtXbgQEOwgj2mRXALhfXPztXgPupii+; integrity="mi"; validityUrl="https://thirdparty.example.com/resource.validity.1511161860"; certUrl="https://thirdparty.example.com/certs"; certSha256=*UeOwUPkvxlGRTyvHcsMUN0A2oNsZbU8EUvg8A9ZAnNc; date=1511133060; expires=1511478660, There are 4 signatures: 2 from different secp256r1 certificates within "https://example.com/", one using a raw ed25519 public key Yasskin Expires July 30, 2018 [Page 7] Internet-Draft Signed HTTP Exchanges January 2018 that's also controlled by "example.com", and a fourth using a secp256r1 certificate owned by "thirdparty.example.com". All 4 signatures rely on the "MI" response header to guard the integrity of the response payload. This isn't strictly required-- some signatures could use "MI" while others use "Digest"--but there's not much benefit to mixing them. The signatures include a "validityUrl" 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 certificates at "https://example.com/oldcerts" and "https://example.com/newcerts" have "subjectAltName"s of "example.com", meaning that if they and their signatures validate, the exchange can be trusted as having an origin of "https://example.com/". The author might be using two certificates because their readers have disjoint sets of roots in their trust stores. The author signed with all three certificates at the same time, so they share a validity range: 7 days starting at 2017-11-19 21:53 UTC. The author then requested an additional signature from "thirdparty.example.com", which did some validation or processing and then signed the resource at 2017-11-19 23:11 UTC. "thirdparty.example.com" only grants 4-day signatures, so clients will need to re-validate more often. 3.2.2. Open Questions [I-D.ietf-httpbis-header-structure] provides a way to parameterise labels but not other supported types like binary content. If the "Signature" header field is notionally a list of parameterised signatures, maybe we should add a "parameterised binary content" type. Should the certUrl and validityUrl be lists so that intermediates can offer a cache without losing the original URLs? Putting lists in dictionary fields is more complex than [I-D.ietf-httpbis-header-structure] allows, so they're single items for now. Yasskin Expires July 30, 2018 [Page 8] Internet-Draft Signed HTTP Exchanges January 2018 3.3. Significant headers of an exchange The significant headers of an exchange are: o The method (Section 4 of [RFC7231]) and effective request URI (Section 5.5 of [RFC7230]) of the request. o The response status code (Section 6 of [RFC7231]) and the response header fields whose names are listed in that exchange's "Signed- Headers" header field (Section 3.1), in the order they appear in that header field. If a response header field name from "Signed- Headers" does not appear in the exchange's response header fields, the exchange has no significant 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 3.1, the exchange has no significant headers. 3.3.1. Open Questions Do the significant headers of an exchange need to include the "Signed-Headers" header field itself? 3.4. CBOR representation of exchange headers To sign an exchange's headers, they need to be serialized into a byte string. Since intermediaries and distributors (Appendix A.2) 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.5), and then signed. The CBOR representation of an exchange "exchange"'s headers is the CBOR ([RFC7049]) array with the following content: 1. The map mapping: * The byte string ':method' to the byte string containing "exchange"'s request's method. * The byte string ':url' to the byte string containing "exchange"'s request's effective request URI. 2. The map mapping: Yasskin Expires July 30, 2018 [Page 9] Internet-Draft Signed HTTP Exchanges January 2018 * the byte string ':status' to the byte string containing "exchange"'s response's 3-digit status code, and * for each response header field in "exchange", the header field's name as a byte string to the header field's value as a byte string. 3.4.1. Example Given the HTTP exchange: GET https://example.com/ HTTP/1.1 Accept: */* HTTP/1.1 200 Content-Type: text/html Digest: SHA-256=20addcf7368837f616d549f035bf6784ea6d4bf4817a3736cd2fc7a763897fe3 Signed-Headers: "content-type", "digest" ... The cbor representation consists of the following item, represented using the extended diagnostic notation from [I-D.ietf-cbor-cddl] appendix G: [ { ':url': 'https://example.com/' ':method': 'GET', }, { 'digest': 'SHA-256=20addcf7368837f616d549f035bf6784ea6d4bf4817a3736cd2fc7a763897fe3', ':status': '200', 'content-type': 'text/html' } ] 3.5. Canonical CBOR serialization 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: o Integers and the lengths of arrays, maps, and strings MUST use the smallest possible encoding. Yasskin Expires July 30, 2018 [Page 10] Internet-Draft Signed HTTP Exchanges January 2018 o Items MUST NOT be encoded with indefinite length. o The keys in every map MUST be sorted in the bytewise lexicographic order of their canonical encodings. For example, the following keys are correctly sorted: 1. 10, encoded as 0A. 2. 100, encoded as 18 64. 3. -1, encoded as 20. 4. "z", encoded as 61 7A. 5. "aa", encoded as 62 61 61. 6. [100], encoded as 81 18 64. 7. [-1], encoded as 81 20. 8. false, encoded as F4. Note: this specification does not use floating point, tags, or other more complex data types, so it doesn't need rules to canonicalize those. 3.6. Signature validity The client MUST parse the "Signature" header field as the list of parameterised values (Section 4.8.1 of [I-D.ietf-httpbis-header-structure]) described in Section 3.2. 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. Potentially-valid results include: o The signed headers of the exchange so that higher-level protocols can avoid relying on unsigned headers, and o Either a certificate chain or a public key so that a higher-level protocol can determine whether it's actually valid. This algorithm accepts a "forceFetch" flag that avoids the cache when fetching URLs. A client that determines that a potentially-valid Yasskin Expires July 30, 2018 [Page 11] Internet-Draft Signed HTTP Exchanges January 2018 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. This algorithm also accepts an "allResponseHeaders" flag, which insists that there are no non-significant response header fields in the exchange. 1. Let "originalExchange" be the signature's exchange. 2. Let "headers" be the significant headers (Section 3.3) of "originalExchange". If "originalExchange" has no significant headers, then return "invalid". 3. Let "payload" be the payload body (Section 3.3 of [RFC7230]) of "originalExchange". Note that the payload body is the message body with any transfer encodings removed. 4. If "allResponseHeaders" is set and the response header fields in "originalExchange" are not equal to the response header fields in "headers", then return "invalid". 5. Let: * "signature" be the signature (binary content in the parameterised label's "sig" parameter). * "integrity" be the signature's "integrity" parameter. * "validityUrl" be the signature's "validityUrl" parameter. * "certUrl" be the signature's "certUrl" parameter, if any. * "certSha256" be the signature's "certSha256" parameter, if any. * "ed25519Key" be the signature's "ed25519Key" parameter, if any. * "date" be the signature's "date" parameter, interpreted as a Unix time. * "expires" be the signature's "expires" parameter, interpreted as a Unix time. 6. If "integrity" names a header field that is not present in "headers" or which the client cannot use to check the integrity of "payload" (for example, the header field is new and hasn't Yasskin Expires July 30, 2018 [Page 12] Internet-Draft Signed HTTP Exchanges January 2018 been implemented yet), then return "invalid". Clients MUST implement at least the "Digest" ([RFC3230]) and "MI" ([I-D.thomson-http-mice]) header fields. 7. If "integrity" is "digest", and the "Digest" header field in "headers" contains no digest-algorithms (https://www.iana.org/assignments/http-dig-alg/http-dig- alg.xhtml [6]) stronger than "SHA", then return "invalid". 8. Set "publicKey" and "signing-alg" depending on which key fields are present: 1. If "certUrl" is present: 1. Let "certificate-chain" be the result of fetching ([FETCH]) "certUrl" and parsing it as a TLS 1.3 Certificate message (Section 4.4.2 of [I-D.ietf-tls-tls13]) containing X.509v3 certificates. If "forceFetch" is _not_ set, the fetch can be fulfilled from a cache using normal HTTP semantics [RFC7234]. If this fetch or parse fails, return "invalid". Parsing notes: 1. This does not include the 4-byte header that would appear in a Handshake message. 1. Since this fetch is not in response to a CertificateRequest, the certificate_request_context MUST be empty, and a non-empty value MUST cause the parse to fail. 2. Let "main-certificate" be the first certificate in "certificate-chain". 3. If the SHA-256 hash of "main-certificate"'s "cert_data" is not equal to "certSha256", return "invalid". Note that this intentionally differs from TLS 1.3, which signs the entire certificate chain in its Certificate Verify (Section 4.4.3 of [I-D.ietf-tls-tls13]), in order to allow updating the stapled OCSP response without updating signatures at the same time. 4. Set "publicKey" to "main-certificate"'s public key 5. The client MUST define a partial function from public key types to signing algorithms, and this function must at the minimum include the following mappings: RSA, 2048 bits: rsa_pss_sha256 as defined in Section 4.2.3 of [I-D.ietf-tls-tls13]. Yasskin Expires July 30, 2018 [Page 13] Internet-Draft Signed HTTP Exchanges January 2018 EC, with the secp256r1 curve: ecdsa_secp256r1_sha256 as defined in Section 4.2.3 of [I-D.ietf-tls-tls13]. EC, with the secp384r1 curve: ecdsa_secp384r1_sha384 as defined in Section 4.2.3 of [I-D.ietf-tls-tls13]. Set "signing-alg" to the result of applying this function to type of "main-certificate"'s public key. If the function is undefined on this input, return "invalid". 2. If "ed25519Key" is present, set "publicKey" to "ed25519Key" and "signing-alg" to ed25519, as defined by [RFC8032] 9. If "expires" is more than 7 days (604800 seconds) after "date", return "invalid". 10. If the current time is before "date" or after "expires", return "invalid". 11. Let "message" be the concatenation of the following byte strings. This matches the [I-D.ietf-tls-tls13] format to avoid cross-protocol attacks when TLS certificates are used to sign manifests. 1. A string that consists of octet 32 (0x20) repeated 64 times. 2. A context string: the ASCII encoding of "HTTP Exchange". 3. A single 0 byte which serves as a separator. 4. The bytes of the canonical CBOR serialization (Section 3.5) of a CBOR map mapping: 1. If "certSha256" is set: 1. The text string "certSha256" to the byte string value of "certSha256". 2. The text string "validityUrl" to the byte string value of "validityUrl". 3. The text string "date" to the integer value of "date". 4. The text string "expires" to the integer value of "expires". Yasskin Expires July 30, 2018 [Page 14] Internet-Draft Signed HTTP Exchanges January 2018 5. The text string "headers" to the CBOR representation (Section 3.4) of "exchange"'s headers. 12. If "signature" is "message"'s signature by "main-certificate"'s public key using "signing-alg", return "potentially-valid" with "exchange" and whichever is present of "certificate-chain" or "ed25519Key". Otherwise, return "invalid". 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 like "MI" ([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. 3.6.1. Open Questions Should we ban RSA keys to avoid their vulnerability to Bleichenbacher attacks? 3.7. Updating signature validity 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 "certUrl" (Section 3.6, Paragraph 4) to get a chain including a newer OCSP response. The "validityUrl" parameter (Paragraph 6) 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 "validityUrl" is "validity data", a CBOR map matching the following CDDL ([I-D.ietf-cbor-cddl]): Yasskin Expires July 30, 2018 [Page 15] Internet-Draft Signed HTTP Exchanges January 2018 validity = { ? signatures: [ + bytes ] ? update: { ? size: uint, } ] The elements of the "signatures" array are parameterised labels (Section 4.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. 3.7.1. Examples 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). Yasskin Expires July 30, 2018 [Page 16] Internet-Draft Signed HTTP Exchanges January 2018 Signature: sig1; sig=*MEUCIQ...; ... validityUrl="https://example.com/resource.validity.1511157180"; certUrl="https://example.com/oldcerts"; date=1511128380; expires=1511733180, sig2; sig=*MEQCIG...; ... validityUrl="https://example.com/resource.validity.1511157180"; certUrl="https://example.com/newcerts"; date=1511128380; expires=1511733180, thirdpartysig; sig=*MEYCIQ...; ... validityUrl="https://thirdparty.example.com/resource.validity.1511161860"; certUrl="https://thirdparty.example.com/certs"; date=1511478660; expires=1511824260 At 2017-11-27 11:02 UTC, "sig1" and "sig2" have expired, but "thirdpartysig" doesn't exipire until 23:11 that night, so the client needs to fetch "https://example.com/resource.validity.1511157180" (the "validityUrl" of "sig1" and "sig2") to update those signatures. This URL might contain: { "signatures": [ 'sig1; ' 'sig=*MEQCIC/I9Q+7BZFP6cSDsWx43pBAL0ujTbON/+7RwKVk+ba5AiB3FSFLZqpzmDJ0NumNwN04pqgJZE99fcK86UjkPbj4jw; ' 'validityUrl="https://example.com/resource.validity.1511157180"; ' 'integrity="mi"; ' 'certUrl="https://example.com/newcerts"; ' 'certSha256=*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 first two of the original signatures (the ones with a validityUrl of "https://example.com/resource.validity.1511157180") with the single new signature provided. (This might happen at the Yasskin Expires July 30, 2018 [Page 17] Internet-Draft Signed HTTP Exchanges January 2018 end of a migration to a new root certificate.) The signatures of the updated signed exchange would be: Signature: sig1; sig=*MEQCIC...; ... validityUrl="https://example.com/resource.validity.1511157180"; certUrl="https://example.com/newcerts"; date=1511733180; expires=1512337980, thirdpartysig; sig=*MEYCIQ...; ... validityUrl="https://thirdparty.example.com/resource.validity.1511161860"; certUrl="https://thirdparty.example.com/certs"; date=1511478660; expires=1511824260 "https://example.com/resource.validity.1511157180" could also expand the set of signatures if its "signatures" array contained more than 2 elements. 3.8. The Accept-Signature header "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 list (Section 4.8 of [I-D.ietf-httpbis-header-structure]) of parameterised labels (Section 4.4 of [I-D.ietf-httpbis-header-structure]). The order of labels in the "Accept-Signature" list is not significant. Labels, ignoring any initial "-" character, MUST NOT be duplicated. Each label in the "Accept-Signature" header field's value indicates that a feature of the "Signature" header field (Section 3.2) is supported. If the label begins with a "-" character, it instead indicates that the feature named by the rest of the label is not Yasskin Expires July 30, 2018 [Page 18] Internet-Draft Signed HTTP Exchanges January 2018 supported. Unknown labels and parameters MUST be ignored because new labels and new parameters on existing labels may be defined by future specifications. 3.8.1. Integrity labels Labels starting with "digest/" indicate that the client supports the "Digest" header field ([RFC3230]) with the digest-algorithm from the https://www.iana.org/assignments/http-dig-alg/http-dig-alg.xhtml [7] registry named in lower-case by the rest of the label. For example, "digest/sha-512" indicates support for the SHA-512 digest algorithm, and "-digest/sha-256" indicates non-support for the SHA-256 digest algorithm. Labels starting with "mi/" indicate that the client supports the "MI" header field ([I-D.thomson-http-mice]) with the parameter from the HTTP MI Parameter Registry registry named in lower-case by the rest of the label. For example, "mi/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/sha-256" and "mi/mi-sha256" unless the header field states otherwise. 3.8.2. Key type labels Labels starting with "rsa/" indicate that the client supports certificates holding RSA public keys with a number of bits indicated by the digits after the "/". Labels 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 label. If the "Accept-Signature" header field is present, servers SHOULD assume support for "rsa/2048", "ecdsa/secp256r1", and "ecdsa/ secp384r1" unless the header field states otherwise. 3.8.3. Key value labels The "ed25519key" label 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 4.5 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 Yasskin Expires July 30, 2018 [Page 19] Internet-Draft Signed HTTP Exchanges January 2018 "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 with the "*" that indicates binary content. Note that "ed25519key; *" is an empty prefix, which matches all public keys, so it's useful in subresource integrity (Appendix A.3) cases like "" where the public key isn't known until the matching "