Network Working Group J. Yasskin
Internet-Draft Google
Intended status: Standards Track March 05, 2018
Expires: September 6, 2018
Signed HTTP Exchanges
draft-yasskin-http-origin-signed-responses-03
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 September 6, 2018.
Yasskin Expires September 6, 2018 [Page 1]
Internet-Draft Signed HTTP Exchanges March 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 . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Signing an exchange . . . . . . . . . . . . . . . . . . . . . 5
3.1. The Signature Header . . . . . . . . . . . . . . . . . . 5
3.1.1. Examples . . . . . . . . . . . . . . . . . . . . . . 6
3.1.2. Open Questions . . . . . . . . . . . . . . . . . . . 8
3.2. CBOR representation of exchange headers . . . . . . . . . 8
3.2.1. Example . . . . . . . . . . . . . . . . . . . . . . . 9
3.3. Loading a certificate chain . . . . . . . . . . . . . . . 10
3.4. Canonical CBOR serialization . . . . . . . . . . . . . . 11
3.5. Signature validity . . . . . . . . . . . . . . . . . . . 11
3.5.1. Open Questions . . . . . . . . . . . . . . . . . . . 15
3.6. Updating signature validity . . . . . . . . . . . . . . . 15
3.6.1. Examples . . . . . . . . . . . . . . . . . . . . . . 16
3.7. The Accept-Signature header . . . . . . . . . . . . . . . 18
3.7.1. Integrity labels . . . . . . . . . . . . . . . . . . 18
3.7.2. Key type labels . . . . . . . . . . . . . . . . . . . 19
3.7.3. Key value labels . . . . . . . . . . . . . . . . . . 19
3.7.4. Examples . . . . . . . . . . . . . . . . . . . . . . 20
3.7.5. Open Questions . . . . . . . . . . . . . . . . . . . 20
4. Cross-origin trust . . . . . . . . . . . . . . . . . . . . . 20
4.1. Stateful header fields . . . . . . . . . . . . . . . . . 21
4.2. Certificate Requirements . . . . . . . . . . . . . . . . 22
5. Transferring a signed exchange . . . . . . . . . . . . . . . 23
5.1. Same-origin response . . . . . . . . . . . . . . . . . . 23
5.1.1. Significant headers for a same-origin response . . . 24
5.1.2. The Signed-Headers Header . . . . . . . . . . . . . . 24
5.2. HTTP/2 extension for cross-origin Server Push . . . . . . 25
5.2.1. Indicating support for cross-origin Server Push . . . 25
5.2.2. NO_TRUSTED_EXCHANGE_SIGNATURE error code . . . . . . 25
5.2.3. Validating a cross-origin Push . . . . . . . . . . . 26
Yasskin Expires September 6, 2018 [Page 2]
Internet-Draft Signed HTTP Exchanges March 2018
5.3. application/http-exchange+cbor format for HTTP/1
compatibility . . . . . . . . . . . . . . . . . . . . . . 26
5.3.1. Example . . . . . . . . . . . . . . . . . . . . . . . 28
5.3.2. Open Questions . . . . . . . . . . . . . . . . . . . 28
6. Security considerations . . . . . . . . . . . . . . . . . . . 28
6.1. Over-signing . . . . . . . . . . . . . . . . . . . . . . 29
6.1.1. Session fixation . . . . . . . . . . . . . . . . . . 29
6.1.2. Misleading content . . . . . . . . . . . . . . . . . 29
6.2. Off-path attackers . . . . . . . . . . . . . . . . . . . 30
6.3. Downgrades . . . . . . . . . . . . . . . . . . . . . . . 30
6.4. Signing oracles are permanent . . . . . . . . . . . . . . 30
6.5. Unsigned headers . . . . . . . . . . . . . . . . . . . . 30
6.6. application/http-exchange+cbor . . . . . . . . . . . . . 31
7. Privacy considerations . . . . . . . . . . . . . . . . . . . 31
8. IANA considerations . . . . . . . . . . . . . . . . . . . . . 32
8.1. Signature Header Field Registration . . . . . . . . . . . 32
8.2. HTTP/2 Settings . . . . . . . . . . . . . . . . . . . . . 32
8.3. HTTP/2 Error code . . . . . . . . . . . . . . . . . . . . 32
8.4. Internet Media Type application/http-exchange+cbor . . . 33
8.5. Internet Media Type application/cert-chain+cbor . . . . . 33
9. References . . . . . . . . . . . . . . . . . . . . . . . . . 34
9.1. Normative References . . . . . . . . . . . . . . . . . . 34
9.2. Informative References . . . . . . . . . . . . . . . . . 37
9.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Appendix A. Use cases . . . . . . . . . . . . . . . . . . . . . 39
A.1. PUSHed subresources . . . . . . . . . . . . . . . . . . . 39
A.2. Explicit use of a content distributor for subresources . 40
A.3. Subresource Integrity . . . . . . . . . . . . . . . . . . 41
A.4. Binary Transparency . . . . . . . . . . . . . . . . . . . 41
A.5. Static Analysis . . . . . . . . . . . . . . . . . . . . . 41
A.6. Offline websites . . . . . . . . . . . . . . . . . . . . 42
Appendix B. Requirements . . . . . . . . . . . . . . . . . . . . 42
B.1. Proof of origin . . . . . . . . . . . . . . . . . . . . . 42
B.1.1. Certificate constraints . . . . . . . . . . . . . . . 42
B.1.2. Signature constraints . . . . . . . . . . . . . . . . 42
B.1.3. Retrieving the certificate . . . . . . . . . . . . . 43
B.2. How much to sign . . . . . . . . . . . . . . . . . . . . 43
B.2.1. Conveying the signed headers . . . . . . . . . . . . 44
B.3. Response lifespan . . . . . . . . . . . . . . . . . . . . 45
B.3.1. Certificate revocation . . . . . . . . . . . . . . . 45
B.3.2. Response downgrade attacks . . . . . . . . . . . . . 45
Appendix C. Determining validity using cache control . . . . . . 46
C.1. Example of updating cache control . . . . . . . . . . . . 46
C.2. Downsides of updating cache control . . . . . . . . . . . 47
Appendix D. Change Log . . . . . . . . . . . . . . . . . . . . . 48
Appendix E. Acknowledgements . . . . . . . . . . . . . . . . . . 49
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 49
Yasskin Expires September 6, 2018 [Page 3]
Internet-Draft Signed HTTP Exchanges March 2018
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:
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].
Yasskin Expires September 6, 2018 [Page 4]
Internet-Draft Signed HTTP Exchanges March 2018
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.
3. Signing an exchange
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.
3.1. 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 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 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.1.2, Paragraph 1). The
present parameters MUST have the following values:
Yasskin Expires September 6, 2018 [Page 5]
Internet-Draft Signed HTTP Exchanges March 2018
"sig" Binary content (Section 4.5 of
[I-D.ietf-httpbis-header-structure]) holding the signature of most
of these parameters and the exchange's headers.
"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]).
"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.1.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.
Yasskin Expires September 6, 2018 [Page 6]
Internet-Draft Signed HTTP Exchanges March 2018
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
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,
Yasskin Expires September 6, 2018 [Page 7]
Internet-Draft Signed HTTP Exchanges March 2018
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.1.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.
3.2. 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.4), 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.
Yasskin Expires September 6, 2018 [Page 8]
Internet-Draft Signed HTTP Exchanges March 2018
* For each request header field in "exchange", the header
field's name as a byte string to the header field's value as a
byte string.
2. The map mapping:
* 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.2.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'
}
]
Yasskin Expires September 6, 2018 [Page 9]
Internet-Draft Signed HTTP Exchanges March 2018
3.3. Loading a certificate chain
The resource at a signature's "certUrl" 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 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.
1. Each "cert" value MUST be a DER-encoded X.509v3 certificate
([RFC5280]). Other key/value pairs in the same array item define
properties of this certificate.
2. The first certificate's "ocsp" value if any MUST be a complete,
DER-encoded OCSP response for that certificate (using the ASN.1
type "OCSPResponse" defined in [RFC2560]). Subsequent
certificates MUST NOT have an "ocsp" value.
3. Each certificate's "sct" value MUST be a
"SignedCertificateTimestampList" for that certificate as defined
by Section 3.3 of [RFC6962].
Loading a "certUrl" takes a "forceFetch" flag. The client MUST:
1. Let "raw-chain" be the result of fetching ([FETCH]) "certUrl".
If "forceFetch" is _not_ set, the fetch can be fulfilled from a
cache using normal HTTP semantics [RFC7234]. If this fetch
fails, return "invalid".
2. Let "certificate-chain" be the array of certificates and
properties produced by parsing "raw-chain" using the CDDL above.
If any of the requirements above aren't satisfied, return
"invalid". Note that this validation requirement might be
impractical to completely achieve due to certificate validation
implementations that don't enforce DER encoding or other standard
constraints.
Yasskin Expires September 6, 2018 [Page 10]
Internet-Draft Signed HTTP Exchanges March 2018
3. Return "certificate-chain".
3.4. 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.
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.5. 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.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.
Yasskin Expires September 6, 2018 [Page 11]
Internet-Draft Signed HTTP Exchanges March 2018
The client MUST use the following algorithm to determine whether each
signature with parameters is invalid or potentially-valid for an
"exchange". 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
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.
1. Let "payload" be the payload body (Section 3.3 of [RFC7230]) of
"exchange". Note that the payload body is the message body with
any transfer encodings removed.
2. 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.
3. If "integrity" names a header field that is not present in
"exchange"'s response headers or which the client cannot use to
check the integrity of "payload" (for example, the header field
is new and hasn't been implemented yet), then return "invalid".
Yasskin Expires September 6, 2018 [Page 12]
Internet-Draft Signed HTTP Exchanges March 2018
Clients MUST implement at least the "Digest" ([RFC3230]) and
"MI" ([I-D.thomson-http-mice]) header fields.
4. If "integrity" is "digest", and the "Digest" header field in
"exchange"'s response headers contains no digest-algorithms
(https://www.iana.org/assignments/http-dig-alg/http-dig-
alg.xhtml [6]) stronger than "SHA", then return "invalid".
5. 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 loading the
certificate chain at "certUrl" passing the "forceFetch"
flag (Section 3.3). If this returns "invalid", return
"invalid".
2. Let "main-certificate" be the first certificate in
"certificate-chain".
3. Set "publicKey" to "main-certificate"'s public key.
4. 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_rsae_sha256 or
rsa_pss_pss_sha256, as defined in Section 4.2.3 of
[I-D.ietf-tls-tls13], depending on which of the
rsaEncryption OID or RSASSA-PSS OID [RFC8017] is
used.
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 the 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]
Yasskin Expires September 6, 2018 [Page 13]
Internet-Draft Signed HTTP Exchanges March 2018
6. If "expires" is more than 7 days (604800 seconds) after "date",
return "invalid".
7. If the current time is before "date" or after "expires", return
"invalid".
8. Let "message" be the concatenation of the following byte
strings:
1. A context string: the ASCII encoding of "HTTP Exchange".
2. A single 0 byte which serves as a separator.
3. The bytes of the canonical CBOR serialization (Section 3.4)
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".
5. The text string "headers" to the CBOR representation
(Section 3.2) of "exchange"'s headers.
9. If "certUrl" is present and the SHA-256 hash of "main-
certificate"'s "cert_data" is not equal to "certSha256" (whose
presence was checked when the "Signature" header field was
parsed), 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.
10. If "signature" is a valid signature of "message" by "publicKey"
using "signing-alg", return "potentially-valid" with whichever
is present of "certificate-chain" or "ed25519Key". Otherwise,
return "invalid".
Yasskin Expires September 6, 2018 [Page 14]
Internet-Draft Signed HTTP Exchanges March 2018
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.5.1. Open Questions
Should the signed message use the TLS format (with an initial 64
spaces) even though these certificates can't be used in TLS servers?
3.6. 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.5, 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]):
validity = {
? signatures: [ + bytes ]
? update: {
? size: uint,
}
]
Yasskin Expires September 6, 2018 [Page 15]
Internet-Draft Signed HTTP Exchanges March 2018
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.6.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).
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"
Yasskin Expires September 6, 2018 [Page 16]
Internet-Draft Signed HTTP Exchanges March 2018
(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
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.
Yasskin Expires September 6, 2018 [Page 17]
Internet-Draft Signed HTTP Exchanges March 2018
3.7. 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.1) is
supported. If the label begins with a "-" character, it instead
indicates that the feature named by the rest of the label is not
supported. Unknown labels and parameters MUST be ignored because new
labels and new parameters on existing labels may be defined by future
specifications.
3.7.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.
Yasskin Expires September 6, 2018 [Page 18]
Internet-Draft Signed HTTP Exchanges March 2018
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.7.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.7.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
"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
Yasskin Expires September 6, 2018 [Page 19]
Internet-Draft Signed HTTP Exchanges March 2018
key isn't known until the matching "