Signed HTTP Exchanges

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 URL and response 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.4 of [I-D.ietf-httpbis-header-structure]). Its ABNF is:¶

Signature = sh-param-list

Each parameterised identifier in the list MUST have parameters named "sig", "integrity", "validity-url", "date", and "expires". Each parameterised identifier MUST also have either "cert-url" and "cert-sha256" parameters or an "ed25519key" parameter. This specification gives no meaning to the identifier itself, which can be used as a human-readable identifier for the signature (however, this is likely to change soon; see Section 3.1.2, Paragraph 1). The present parameters MUST have the following values:¶

"sig"

Byte sequence (Section 3.10 of [I-D.ietf-httpbis-header-structure]) holding the signature of most of these parameters and the exchange's URL and response headers.¶

"integrity"

A string (Section 3.8 of [I-D.ietf-httpbis-header-structure]) containing a "/"-separated sequence of names starting with the lowercase name of the response header field that guards the response payload's integrity. The meaning of subsequent names depends on the response header field, but for the "digest" header field, the single following name is the name of the digest algorithm that guards the payload's integrity.¶

"cert-url"

A string (Section 3.8 of [I-D.ietf-httpbis-header-structure]) containing an absolute URL (Section 2) with a scheme of "https" or "data".¶

"cert-sha256"

Byte sequence (Section 3.10 of [I-D.ietf-httpbis-header-structure]) holding the SHA-256 hash of the first certificate found at "cert-url".¶

"ed25519key"

Byte sequence (Section 3.10 of [I-D.ietf-httpbis-header-structure]) holding an Ed25519 public key ([RFC8032]).¶

"validity-url"

A string (Section 3.8 of [I-D.ietf-httpbis-header-structure]) containing an absolute URL (Section 2) with a scheme of "https".¶

"date" and "expires"

An integer (Section 3.6 of [I-D.ietf-httpbis-header-structure]) representing a Unix time.¶

The "cert-url" parameter is not signed, so intermediates can update it with a pointer to a cached version.¶

Signature:
 sig1;
  sig=*MEUCIQDXlI2gN3RNBlgFiuRNFpZXcDIaUpX6HIEwcZEc0cZYLAIga9DsVOMM+g5YpwEBdGW3sS+bvnmAJJiSMwhuBdqp5UY=*;
  integrity="digest/mi-sha256";
  validity-url="https://example.com/resource.validity.1511128380";
  cert-url="https://example.com/oldcerts";
  cert-sha256=*W7uB969dFW3Mb5ZefPS9Tq5ZbH5iSmOILpjv2qEArmI=*;
  date=1511128380; expires=1511733180,
 sig2;
  sig=*MEQCIGjZRqTRf9iKNkGFyzRMTFgwf/BrY2ZNIP/dykhUV0aYAiBTXg+8wujoT4n/W+cNgb7pGqQvIUGYZ8u8HZJ5YH26Qg==*;
  integrity="digest/mi-sha256";
  validity-url="https://example.com/resource.validity.1511128380";
  cert-url="https://example.com/newcerts";
  cert-sha256=*J/lEm9kNRODdCmINbvitpvdYKNQ+YgBj99DlYp4fEXw=*;
  date=1511128380; expires=1511733180,
 srisig;
  sig=*lGZVaJJM5f2oGczFlLmBdKTDL+QADza4BgeO494ggACYJOvrof6uh5OJCcwKrk7DK+LBch0jssDYPp5CLc1SDA==*;
  integrity="digest/mi-sha256";
  validity-url="https://example.com/resource.validity.1511128380";
  ed25519key=*zsSevyFsxyZHiUluVBDd4eypdRLTqyWRVOJuuKUz+A8=*
  date=1511128380; expires=1511733180,
 thirdpartysig;
  sig=*MEYCIQCNxJzn6Rh2fNxsobktir8TkiaJYQFhWTuWI1i4PewQaQIhAMs2TVjc4rTshDtXbgQEOwgj2mRXALhfXPztXgPupii+*;
  integrity="digest/mi-sha256";
  validity-url="https://thirdparty.example.com/resource.validity.1511161860";
  cert-url="https://thirdparty.example.com/certs";
  cert-sha256=*UeOwUPkvxlGRTyvHcsMUN0A2oNsZbU8EUvg8A9ZAnNc=*;
  date=1511133060; expires=1511478660,

3.2. CBOR representation of exchange response headers

To sign an exchange's response 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 a set of response metadata and headers is the CBOR ([RFC7049]) map with the following mappings:¶

• The byte string ':status' to the byte string containing the response's 3-digit status code, and¶
• For each response header field, the header field's lowercase name as a byte string to the header field's value as a byte string.¶

GET / HTTP/1.1
Host: example.com
Accept: */*

HTTP/1.1 200
Content-Type: text/html
Digest: mi-sha256=dcRDgR2GM35DluAV13PzgnG6+pvQwPywfFvAu1UeFrs=
Signed-Headers: "content-type", "digest"

<!doctype html>
<html>
...

{
  'digest': 'mi-sha256=dcRDgR2GM35DluAV13PzgnG6+pvQwPywfFvAu1UeFrs=',
  ':status': '200',
  'content-type': 'text/html'
}

3.3. Loading a certificate chain

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
  + augmented-certificate
]
augmented-certificate = {
  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.¶

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 MUST be a complete, DER-encoded OCSP response for that certificate (using the ASN.1 type OCSPResponse defined in [RFC6960]). Subsequent certificates MUST NOT have an ocsp value.¶
3. Each certificate's sct value if any MUST be a SignedCertificateTimestampList for that certificate as defined by Section 3.3 of [RFC6962].¶

Loading a cert-url takes a forceFetch flag. The client MUST:¶

1. Let raw-chain be the result of fetching ([FETCH]) cert-url. 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.¶
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:¶

• Integers and the lengths of arrays, maps, and strings MUST use the smallest possible encoding.¶
• Items MUST NOT be encoded with indefinite length.¶

• 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 parameterised list (Section 4.2.5 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¶

• requestUrl, a byte sequence that can be parsed into the exchange's effective request URI (Section 5.5 of [RFC7230]),¶
• responseHeaders, a byte sequence holding the canonical serialization (Section 3.4) of the CBOR representation (Section 3.2) of the exchange's response metadata and headers, and¶
• payload, a stream of bytes constituting the exchange's payload body (Section 3.3 of [RFC7230]). Note that the payload body is the message body with any transfer encodings removed.¶

Potentially-valid results include:¶

• The signed headers of the exchange so that higher-level protocols can avoid relying on unsigned headers, and¶
• Either a certificate chain or a public key so that a higher-level protocol can determine whether it's actually valid.¶

1. Let:¶

   • signature be the signature (byte sequence in the parameterised identifier's "sig" parameter).¶
   • integrity be the signature's "integrity" parameter.¶
   • validity-url be the signature's "validity-url" parameter.¶
   • cert-url be the signature's "cert-url" parameter, if any.¶
   • cert-sha256 be the signature's "cert-sha256" 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.¶

2. Set publicKey and signing-alg depending on which key fields are present:¶

   1. If cert-url is present:¶

      1. Let certificate-chain be the result of loading the certificate chain at cert-url 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. If publicKey is an RSA key, return "invalid".¶
      5. If publicKey is a key using the secp256r1 elliptic curve, set signing-alg to ecdsa_secp256r1_sha256 as defined in Section 4.2.3 of [RFC8446].¶
      6. Otherwise, either return "invalid" or set signing-alg to a non-legacy signing algorithm defined by TLS 1.3 or later ([RFC8446]). This choice MUST depend only on publicKey's type and not on any other context.¶
   2. If ed25519key is present, set publicKey to ed25519key and signing-alg to ed25519, as defined by [RFC8032]¶
3. If expires is more than 7 days (604800 seconds) after date, return "invalid".¶
4. If the current time is before date or after expires, return "invalid".¶

5. Let message be the concatenation of the following byte strings. This matches the [RFC8446] format to avoid cross-protocol attacks if anyone uses the same key in a TLS certificate and an exchange-signing certificate.¶

   1. A string that consists of octet 32 (0x20) repeated 64 times.¶

   2. A context string: the ASCII encoding of "HTTP Exchange 1".¶

      Note: RFC EDITOR PLEASE DELETE THIS NOTE; The implementation of the final RFC MUST use this context string, but implementations of drafts MUST NOT use it and MUST use another draft-specific string beginning with "HTTP Exchange 1 " instead. This ensures that signers can predict how their signatures will be used.¶

   3. A single 0 byte which serves as a separator.¶
   4. If cert-sha256 is set, a byte holding the value 32 followed by the 32 bytes of the value of cert-sha256. Otherwise a 0 byte.¶
   5. The 8-byte big-endian encoding of the length in bytes of validity-url, followed by the bytes of validity-url.¶
   6. The 8-byte big-endian encoding of date.¶
   7. The 8-byte big-endian encoding of expires.¶
   8. The 8-byte big-endian encoding of the length in bytes of requestUrl, followed by the bytes of requestUrl.¶
   9. The 8-byte big-endian encoding of the length in bytes of responseHeaders, followed by the bytes of responseHeaders.¶

6. If cert-url is present and the SHA-256 hash of main-certificate's cert_data is not equal to cert-sha256 (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 [RFC8446]), in order to allow updating the stapled OCSP response without updating signatures at the same time.¶

7. If signature is not a valid signature of message by publicKey using signing-alg, return "invalid".¶

8. If headers, interpreted according to Section 3.2, does not contain a Content-Type response header field (Section 3.1.1.5 of [RFC7231]), return "invalid".¶

   Clients MUST interpret the signed payload as this specified media type instead of trying to sniff a media type from the bytes of the payload, for example by attaching an X-Content-Type-Options: nosniff header field ([FETCH]) to the extracted response.¶

9. If integrity names a header field and parameter that is not present in responseHeaders 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". If the selected header field provides integrity guarantees weaker than SHA-256, return "invalid". If validating integrity using the selected header field requires the client to process records larger than 16384 bytes, return "invalid". Clients MUST implement at least the Digest header field with its mi-sha256 digest algorithm (Section 3 of [I-D.thomson-http-mice]).¶

   Note: RFC EDITOR PLEASE DELETE THIS NOTE; Implementations of drafts of this RFC MUST recognize the draft spelling of the content encoding and digest algorithm specified by [I-D.thomson-http-mice] until that draft is published as an RFC. For example, implementations of draft-thomson-http-mice-03 would use mi-sha256-03 and MUST NOT use mi-sha256 itself. This ensures that final implementations don't need to handle compatibility with implementations of early drafts of that content encoding.¶

   If payload doesn't match the integrity information in the header described by integrity, return "invalid".¶

10. Return "potentially-valid" with whichever is present of certificate-chain or ed25519key.¶

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 ([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. 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 "cert-url" (Section 3.5, Paragraph 6) to get a chain including a newer OCSP response.¶

The "validity-url" parameter (Section 3.1) 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 ([CDDL]):¶

validity = {
  ? signatures: [ + bytes ]
  ? update: {
    ? size: uint,
  }
]

The elements of the signatures array are parameterised identifiers (Section 4.2.6 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.¶

Signature:
 sig1;
  sig=*MEUCIQ...*;
  ...
  validity-url="https://example.com/resource.validity.1511157180";
  cert-url="https://example.com/oldcerts";
  date=1511128380; expires=1511733180,
 sig2;
  sig=*MEQCIG...*;
  ...
  validity-url="https://example.com/resource.validity.1511157180";
  cert-url="https://example.com/newcerts";
  date=1511128380; expires=1511733180,
 thirdpartysig;
  sig=*MEYCIQ...*;
  ...
  validity-url="https://thirdparty.example.com/resource.validity.1511161860";
  cert-url="https://thirdparty.example.com/certs";
  date=1511478660; expires=1511824260

{
  "signatures": [
    'sig1; '
    'sig=*MEQCIC/I9Q+7BZFP6cSDsWx43pBAL0ujTbON/+7RwKVk+ba5AiB3FSFLZqpzmDJ0NumNwN04pqgJZE99fcK86UjkPbj4jw==*; '
    'validity-url="https://example.com/resource.validity.1511157180"; '
    'integrity="digest/mi-sha256"; '
    'cert-url="https://example.com/newcerts"; '
    'cert-sha256=*J/lEm9kNRODdCmINbvitpvdYKNQ+YgBj99DlYp4fEXw=*; '
    'date=1511733180; expires=1512337980'
  ],
  "update": {
    "size": 5557452
  }
}

Signature:
 sig1;
  sig=*MEQCIC...*;
  ...
  validity-url="https://example.com/resource.validity.1511157180";
  cert-url="https://example.com/newcerts";
  date=1511733180; expires=1512337980,
 thirdpartysig;
  sig=*MEYCIQ...*;
  ...
  validity-url="https://thirdparty.example.com/resource.validity.1511161860";
  cert-url="https://thirdparty.example.com/certs";
  date=1511478660; expires=1511824260

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 parameterised list (Section 3.4 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.¶

Accept-Signature: ..., ed25519key; *11qYAYKxCrfVS/7TyWQHOg7hcvPapiMlrwIaaPcHURo=*
Accept-Signature: ..., ed25519key; *11qYAYKxCrfVS/7TyWQHOg==*
Accept-Signature: ..., ed25519key; *11qYAQ==*
Accept-Signature: ..., ed25519key; **

Accept-Signature: ..., ed25519key; *11qYA===*

Accept-Signature: ..., ed25519key; 11qYAQ

Accept-Signature: digest/mi-sha256

Accept-Signature: -ecdsa/secp256r1, ecdsa/secp384r1

4.1. Uncached header fields

Hop-by-hop and other uncached headers MUST NOT appear in a signed exchange. These will eventually be listed in [I-D.ietf-httpbis-cache], but for now they're listed here:¶

• Hop-by-hop header fields listed in the Connection header field (Section 6.1 of [RFC7230]).¶
• Header fields listed in the no-cache response directive in the Cache-Control header field (Section 5.2.2.2 of [RFC7234]).¶

• Header fields defined as hop-by-hop:¶

  • Connection¶
  • Keep-Alive¶
  • Proxy-Connection¶
  • Trailer¶
  • Transfer-Encoding¶
  • Upgrade¶
• Stateful headers as defined below.¶

4.2. Certificate Requirements

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.¶

   id-ce-canSignHttpExchanges OBJECT IDENTIFIER ::= { TBD }

   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.¶

Certificates with this extension MUST have a Validity Period no greater than 90 days.¶

Conforming CAs MUST NOT mark this extension as critical.¶

A conforming CA MUST NOT issue certificates with this extension unless, for each dNSName in the subjectAltName extension of the certificate to be issued:¶

1. An "issue" or "issuewild" CAA property ([RFC6844]) exists that authorizes the CA to issue the certificate; and¶
2. The "cansignhttpexchanges" parameter (Section 4.2.1) is present on the property and is equal to "yes"¶

Clients MUST NOT accept certificates with this extension in TLS connections (Section 4.4.2.2 of [RFC8446]).¶

RFC EDITOR PLEASE DELETE THE REST OF THE PARAGRAPHS IN THIS SECTION¶

   id-ce-google OBJECT IDENTIFIER ::= { 1 3 6 1 4 1 11129 }
   id-ce-canSignHttpExchangesDraft OBJECT IDENTIFIER ::= { id-ce-google 2 1 22 }

Implementations of drafts of this specification MAY recognize the id-ce-canSignHttpExchangesDraft OID as identifying the CanSignHttpExchanges extension. 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.¶

Some certificates have already been issued with this extension and with validity periods longer than 90 days. These certificates will not immediately be treated as invalid. Instead:¶

• Clients MUST reject certificates with this extension that were issued after 2019-05-01 and have a Validity Period longer than 90 days.¶
• After 2019-08-01, clients MUST reject all certificates with this extension that have a Validity Period longer than 90 days.¶

The above requirements on CAs to limit the Validity Period and check for a CAA parameter are effective starting 2019-05-01.¶

5.1. Same-origin response

The signature for a signed exchange can be included in a normal HTTP response. Because different clients send different request header fields, clients don't know how the server's content negotiation algorithm works, and intermediate servers add response header fields, it can be impossible to have a signature for the exchange's exact request, content negotiation, and response. 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:¶

• The Signature header field,¶
• The effective request URI (Section 5.5 of [RFC7230]) of the request,¶
• The serialized headers defined by Section 5.1.1, and¶
• The response's payload.¶

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.¶

If the signed response includes a Variants header field, the client MUST use the cache behavior algorithm in Section 4 of [I-D.ietf-httpbis-variants] to check that the signed response is an appropriate representation for the request the client is trying to fulfil. If the response is not an appropriate representation, the client MUST treat the signature as invalid.¶

Signed-Headers = sh-list

5.2. HTTP/2 extension for cross-origin Server Push

To allow servers to Server-Push (Section 8.2 of [RFC7540]) signed exchanges (Section 3) signed by an authority for which the server is not authoritative (Section 9.1 of [RFC7230]), this section defines an HTTP/2 extension.¶

5.3. application/signed-exchange format

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 a request URL, response metadata and header fields, and a response payload.¶

When served over HTTP, a response containing an application/signed-exchange payload MUST include at least the following response header fields, to reduce content sniffing vulnerabilities (Section 6.8):¶

• Content-Type: application/signed-exchange;v=version¶
• X-Content-Type-Options: nosniff¶

This content type consists of the concatenation of the following items:¶

1. 8 bytes consisting of the ASCII characters "sxg1" followed by 4 0x00 bytes, to serve as a file signature. This is redundant with the MIME type, and recipients that receive both MUST check that they match and stop parsing if they don't.¶

   Note: RFC EDITOR PLEASE DELETE THIS NOTE; The implementation of the final RFC MUST use this file signature, but implementations of drafts MUST NOT use it and MUST use another implementation-specific 8-byte string beginning with "sxg1-".¶

2. 2 bytes storing a big-endian integer fallbackUrlLength.¶

3. fallbackUrlLength bytes holding a fallbackUrl, which MUST UTF-8 decode to an absolute URL with a scheme of "https".¶

   Note: The byte location of the fallback URL is intended to remain invariant across versions of the application/signed-exchange format so that parsers encountering unknown versions can always find a URL to redirect to.¶

   Issue: Should this fallback information also include the method?¶

4. 3 bytes storing a big-endian integer sigLength. If this is larger than 16384 (16*1024), parsing MUST fail.¶
5. 3 bytes storing a big-endian integer headerLength. If this is larger than 524288 (512*1024), parsing MUST fail.¶
6. sigLength bytes holding the Signature header field's value (Section 3.1).¶
7. headerLength bytes holding signedHeaders, the canonical serialization (Section 3.4) of the CBOR representation of the response headers of the exchange represented by the application/signed-exchange resource (Section 3.2), excluding the Signature header field.¶

8. The payload body (Section 3.3 of [RFC7230]) of the exchange represented by the application/signed-exchange resource.¶

   Note that the use of the payload body here means that a Transfer-Encoding header field inside the application/signed-exchange header block has no effect. A Transfer-Encoding header field on the outer HTTP response that transfers this resource still has its normal effect.¶

sxg1\0\0\0\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 map>sig1; sig=*...; integrity="digest/mi-sha256"; ...{
  ':status': '200',
  'content-type': 'text/html'
}<!doctype html>\r\n<html>...

6.1. Over-signing

If a publisher blindly signs all responses as their origin, they can cause at least two kinds of problems, described below. To avoid this, publishers SHOULD design their systems to opt particular public content that doesn't depend on authentication status into signatures instead of signing by default.¶

Signing systems SHOULD also incorporate the following mitigations to reduce the risk that private responses are signed:¶

1. Strip the Cookie request header field and other identifying information like client authentication and TLS session IDs from requests whose exchange is destined to be signed, before forwarding the request to a backend.¶
2. Only sign exchanges where the response includes a Cache-Control: public header. Clients are not required to fail signature-checking for exchanges that omit this Cache-Control response header field to reduce the risk that naive signing systems blindly add it.¶

6.2. Off-path attackers

Relaxing the requirement to consult DNS when determining authority for an origin means that an attacker who possesses a valid certificate no longer needs to be on-path to redirect traffic to them; instead of modifying DNS or IP routing, they need only convince the user to visit another Web site in order to serve responses signed as the target. This consideration and mitigations for it are shared by the combination of [RFC8336] and [I-D.ietf-httpbis-http2-secondary-certs], and are discussed further in [I-D.bishop-httpbis-origin-fed-up].¶

6.3. Downgrades

Signing a bad response can affect more users than simply serving a bad response, since a served response will only affect users who make a request while the bad version is live, while an attacker can forward a signed response until its signature expires. Publishers should consider shorter signature expiration times than they use for cache expiration times.¶

Clients MAY also check the "validity-url" (Section 3.1) of an exchange more often than the signature's expiration would require. Doing so for an exchange with an HTTPS request URI provides a TLS guarantee that the exchange isn't out of date (as long as Section 5.2.3.1 is resolved to keep the same-origin requirement).¶

6.4. Signing oracles are permanent

An attacker with temporary access to a signing oracle can sign "still valid" assertions with arbitrary timestamps and expiration times. As a result, when a signing oracle is removed, the keys it provided access to MUST be revoked so that, even if the attacker used them to sign future-dated exchange validity assertions, the key's OCSP assertion will expire, causing the exchange as a whole to become untrusted.¶

6.5. Unsigned headers

The use of a single Signed-Headers header field prevents us from signing aspects of the request other than its effective request URI (Section 5.5 of [RFC7230]). For example, if a publisher signs both Content-Encoding: br and Content-Encoding: gzip variants of a response, what's the impact if an attacker serves the brotli one for a request with Accept-Encoding: gzip? This is mitigated by using [I-D.ietf-httpbis-variants] instead of request headers to describe how the client should run content negotiation.¶

The simple form of Signed-Headers also prevents us from signing less than the full request URL. The SRI use case (Appendix A.3) may benefit from being able to leave the authority less constrained.¶

Section 3.5 can succeed when some delivered headers aren't included in the signed set. This accommodates current TLS-terminating intermediates and may be useful for SRI (Appendix A.3), but is risky for trusting cross-origin responses (Appendix A.1, Appendix A.2, and Appendix A.6). Section 5.2 requires all headers to be included in the signature before trusting cross-origin pushed resources, at Ryan Sleevi's recommendation.¶

6.6. application/signed-exchange

Clients MUST NOT trust an effective request URI claimed by an application/signed-exchange resource (Section 5.3) without either ensuring the resource was transferred from a server that was authoritative (Section 9.1 of [RFC7230]) for that URI's origin, or calling the algorithm in Section 5.3.1 and getting "valid" back.¶

6.7. Key re-use with TLS

In general, key re-use across multiple protocols is a bad idea.¶

Using an exchange-signing key in a TLS (or other directly-internet-facing) server increases the risk that an attacker can steal the private key, which will allow them to mint packages (similar to Section 6.4) until their theft is discovered.¶

Using a TLS key in a CanSignHttpExchanges certificate makes it less likely that the server operator will discover key theft, due to the considerations in Section 6.2.¶

This specification uses the CanSignHttpExchanges X.509 extension (Section 4.2) to discourage re-use of TLS keys to sign exchanges or vice-versa.¶

We require that clients reject certificates with the CanSignHttpExchanges extension when making TLS connections to minimize the chance that servers will re-use keys like this. Ideally, we would make the extension critical so that even clients that don't understand it would reject such TLS connections, but this proved impossible because certificate-validating libraries ship on significantly different schedules from the clients that use them.¶

Even once all clients reject these certificates in TLS connections, this will still just discourage and not prevent key re-use, since a server operator can unwisely request two different certificates with the same private key.¶

6.8. Content sniffing

While modern browsers tend to trust the Content-Type header sent with a resource, especially when accompanied by X-Content-Type-Options: nosniff, plugins will sometimes search for executable content buried inside a resource and execute it in the context of the origin that served the resource, leading to XSS vulnerabilities. For example, some PDF reader plugins look for %PDF anywhere in the first 1kB and execute the code that follows it.¶

The application/signed-exchange format (Section 5.3) includes a URL and response headers early in the format, which an attacker could use to cause these plugins to sniff a bad content type.¶

To avoid vulnerabilities, in addition to the response header requirements in Section 5.3, servers are advised to only serve an application/signed-exchange resource (SXG) from a domain if it would also be safe for that domain to serve the SXG's content directly, and to follow at least one of the following strategies:¶

1. Only serve signed exchanges from dedicated domains that don't have access to sensitive cookies or user storage.¶
2. Generate signed exchanges "offline", that is, in response to a trusted author submitting content or existing signatures reaching a certain age, rather than in response to untrusted-reader queries.¶

3. Do all of:¶

   1. If the SXG's fallback URL (Section 5.3) is derived from the request URL, percent-encode ([URL]) any bytes that are greater than 0x7E or are not URL code points ([URL]) in the fallback URL . It is particularly important to make sure no unescaped nulls (0x00) or angle brackets (0x3C and 0x3E) appear.¶
   2. Do not reflect request header fields into the set of response headers.¶

There are still a few binary length fields that an attacker may influence to contain sensitive bytes, but they're always followed by lowercase alphabetic strings from a small set of possibilities, which reduces the chance that a client will sniff them as indicating a particular content type.¶

To encourage servers to include the X-Content-Type-Options: nosniff header field, clients SHOULD reject signed exchanges served without it.¶

7.1. Visibility of resource requests

Normally, when a client follows a link from https://source.example/page.html to https://publisher.example/page.html, publisher.example learns that the client is interested in the resource. source.example also has several ways of discovering that the client has clicked the link, including the use of Javascript to record the click or having the link point to a URL that serves a 302 redirect to the real target.¶

If publisher.example signs page.html into page.sxg, distributor.example serves it as https://distributor.example/publisher/page.sxg, and the client fetches it from there, then distributor.example learns that the client is interested, and if the client executes some Javascript on the page or makes subresource requests, that could also report the client's interest back to publisher.example.¶

To prevent network operators other than distributor.example or publisher.example 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 ([RFC8446]) or a successor transport layer, and MUST NOT accept exchanges transferred over plain HTTP without TLS.¶

If source.example and distributor.example are controlled by the same entity, no extra information escapes here. If they are run by different entities, a similar amount of information escapes as if source.example had implemented its click tracking by outsourcing to a service like https://bit.ly/.¶

There has been discussion of allowing a publisher to restrict the set of distributors that can host its signed content. If that's added, then the privacy situation becomes more similar to the situation with CDNs, where a publisher chooses a CDN to serve their content, and the CDN learns about all requests for that content. Here the publisher would choose one or more distributors, and the distributor(s) would learn about requests for the content.¶

For non-executable resource types, a signed response can improve the privacy situation by hiding the client's interest from the original publisher.¶

7.2. User ID transfer

If a request for https://distributor.example/publisher/page.sxg comes with the source's or distributor's user ID for the user, either because it's sent with the distributor's cookies or because the source stashes an encoded user ID into either the request's path or a subdomain, the distributor has a few ways to pass that user ID on to the publisher that signed the page:¶

1. If the distributor has the publisher's signing keys, it can sign a new page with its user ID directly embedded.¶
2. Otherwise, the publisher can sign lots of copies of their package, and the distributor can choose a particular copy to send a subset of the bits in its user ID to the publisher on each click, which will eventually transfer the whole thing.¶

To prevent this, the request for a signed exchange needs to omit credentials and block them from appearing in the URL in the same way it would block them from appearing in a cross-origin URL. We're exploring ways the link can mark the request so user agents can take the right counter-measures.¶

8.1. Signature Header Field Registration

This section registers the Signature header field in the "Permanent Message Header Field Names" registry ([RFC3864]).¶

Header field name: Signature¶

Applicable protocol: http¶

Status: standard¶

Author/Change controller: IETF¶

Specification document(s): Section 3.1 of this document¶

8.2. Accept-Signature Header Field Registration

This section registers the Accept-Signature header field in the "Permanent Message Header Field Names" registry ([RFC3864]).¶

Header field name: Accept-Signature¶

Applicable protocol: http¶

Status: standard¶

Author/Change controller: IETF¶

Specification document(s): Section 3.7 of this document¶

8.3. Signed-Headers Header Field Registration

This section registers the Signed-Headers header field in the "Permanent Message Header Field Names" registry ([RFC3864]).¶

Header field name: Signed-Headers¶

Applicable protocol: http¶

Status: standard¶

Author/Change controller: IETF¶

Specification document(s): Section 5.1.2 of this document¶

8.4. HTTP/2 Settings

This section establishes an entry for the HTTP/2 Settings Registry that was established by Section 11.3 of [RFC7540]¶

Name: ENABLE_CROSS_ORIGIN_PUSH¶

Code: 0xSETTING-TBD¶

Initial Value: 0¶

Specification: This document¶

8.5. HTTP/2 Error code

This section establishes an entry for the HTTP/2 Error Code Registry that was established by Section 11.4 of [RFC7540]¶

Name: NO_TRUSTED_EXCHANGE_SIGNATURE¶

Code: 0xERROR-TBD¶

Description: The client does not trust the signature for a cross-origin Pushed signed exchange.¶

Specification: This document¶

8.6. Internet Media Type application/signed-exchange

IANA is requested to register the MIME media type ([IANA.media-types]) for signed exchanges, application/signed-exchange, as follows:¶

Type name: application¶

Subtype name: signed-exchange¶

Required parameters:¶

• v: A string denoting the version of the file format. ([RFC5234] ABNF: version = DIGIT/%x61-7A) The version defined in this specification is 1. When used with the Accept header field (Section 5.3.2 of [RFC7231]), this parameter can be a comma (,)-separated list of version strings. ([RFC5234] ABNF: version-list = version *( "," version )) The server is then expected to reply with a resource using a particular version from that list.¶

  Note: RFC EDITOR PLEASE DELETE THIS NOTE; Implementations of drafts of this specification MUST NOT use simple integers to describe their versions, and MUST instead define implementation-specific strings to identify which draft is implemented. The newest version of [I-D.yasskin-httpbis-origin-signed-exchanges-impl] describes the meaning of one such string.¶

Optional parameters: N/A¶

Encoding considerations: binary¶

Security considerations: see Section 6.6¶

Interoperability considerations: N/A¶

Published specification: This specification (see Section 5.3).¶

Applications that use this media type: N/A¶

Fragment identifier considerations: N/A¶

Additional information:¶

Deprecated alias names for this type: N/A¶

Magic number(s): 73 78 67 31 00¶

File extension(s): .sxg¶

Macintosh file type code(s): N/A¶

Person and email address to contact for further information: See Authors' Addresses section.¶

Intended usage: COMMON¶

Restrictions on usage: N/A¶

Author: See Authors' Addresses section.¶

Change controller: IESG¶

Provisional registration? Yes¶

8.7. Internet Media Type application/cert-chain+cbor

IANA is requested to register the MIME media type ([IANA.media-types]) for CBOR-format certificate chains, application/cert-chain+cbor, as follows:¶

Type name: application¶

Subtype name: cert-chain+cbor¶

Required parameters: N/A¶

Optional parameters: N/A¶

Encoding considerations: binary¶

Security considerations: N/A¶

Interoperability considerations: N/A¶

Published specification: This specification (see Section 3.3).¶

Applications that use this media type: N/A¶

Fragment identifier considerations: N/A¶

Additional information:¶

Deprecated alias names for this type: N/A¶

Magic number(s): 1*9(??) 67 F0 9F 93 9C E2 9B 93¶

File extension(s): N/A¶

Macintosh file type code(s): N/A¶

Person and email address to contact for further information: See Authors' Addresses section.¶

Intended usage: COMMON¶

Restrictions on usage: N/A¶

Author: See Authors' Addresses section.¶

Change controller: IESG¶

Provisional registration? Yes¶

8.8. The cansignhttpexchanges CAA Parameter

There are no IANA considerations for this parameter.¶

A.1. PUSHed subresources

To reduce round trips, a server might use HTTP/2 Push (Section 8.2 of [RFC7540]) to inject a subresource from another server into the client's cache. If anything about the subresource is expired or can't be verified, the client would fetch it from the original server.¶

For example, if https://example.com/index.html includes¶

<script src="https://jquery.com/jquery-1.2.3.min.js">

Then to avoid the need to look up and connect to jquery.com in the critical path, example.com might push that resource signed by jquery.com.¶

A.2. Explicit use of a content distributor for subresources

In order to speed up loading but still maintain control over its content, an HTML page in a particular origin O.com could tell clients to load its subresources from an intermediate content distributor that's not authoritative, but require that those resources be signed by O.com so that the distributor couldn't modify the resources. This is more constrained than the common CDN case where O.com has a CNAME granting the CDN the right to serve arbitrary content as O.com.¶

<img logicalsrc="https://O.com/img.png"
     physicalsrc="https://distributor.com/O.com/img.png">

To make it easier to configure the right distributor for a given request, computation of the physicalsrc could be encapsulated in a custom element:¶

<dist-img src="https://O.com/img.png"></dist-img>

where the <dist-img> implementation generates an appropriate <img> based on, for example, a <meta name="dist-base"> tag elsewhere in the page. However, this has the downside that the preloader can no longer see the physical source to download it. The resulting delay might cancel out the benefit of using a distributor.¶

This could be used for some of the same purposes as SRI (Appendix A.3).¶

To implement this with the current proposal, the distributor would respond to the physical request to https://distributor.com/O.com/img.png with first a signed PUSH_PROMISE for https://O.com/img.png and then a redirect to https://O.com/img.png.¶

A.3. Subresource Integrity

The W3C WebAppSec group is investigating using signatures in [SRI]. They need a way to transmit the signature with the response, which this proposal provides.¶

Their needs are simpler than most other use cases in that the integrity="ed25519-[public-key]" attribute and CSP-based ways of expressing a public key don't need that key to be wrapped into a certificate.¶

The "ed25519key" signature parameter supports this simpler way of attaching a key.¶

The current proposal for signature-based SRI describes signing only the content of a resource, while this specification requires them to sign the request URI as well. This issue is tracked in https://github.com/mikewest/signature-based-sri/issues/5. The details of what they need to sign will affect whether and how they can use this proposal.¶

A.4. Binary Transparency

So-called "Binary Transparency" may eventually allow users to verify that a program they've been delivered is one that's available to the public, and not a specially-built version intended to attack just them. Binary transparency systems don't exist yet, but they're likely to work similarly to the successful Certificate Transparency logs described by [RFC6962].¶

Certificate Transparency depends on Signed Certificate Timestamps that prove a log contained a particular certificate at a particular time. To build the same thing for Binary Transparency logs containing HTTP resources or full websites, we'll need a way to provide signatures of those resources, which signed exchanges provides.¶

A.5. Static Analysis

Native app stores like the Apple App Store and the Android Play Store grant their contents powerful abilities, which they attempt to make safe by analyzing the applications before offering them to people. The web has no equivalent way for people to wait to run an update of a web application until a trusted authority has vouched for it.¶

While full application analysis probably needs to wait until the authority can sign bundles of exchanges, authorities may be able to guarantee certain properties by just checking a top-level resource and its [SRI]-constrained sub-resources.¶

A.6. Offline websites

Fully-offline websites can be represented as bundles of signed exchanges, although an optimization to reduce the number of signature verifications may be needed. Work on this is in progress in the https://github.com/WICG/webpackage repository.¶

B.1. Proof of origin

To verify that a thing came from a particular origin, for use in the same context as a TLS connection, we need someone to vouch for the signing key with as much verification as the signing keys used in TLS. The obvious way to do this is to re-use the web PKI and CA ecosystem.¶

B.2. How much to sign

The previous [I-D.thomson-http-content-signature] and [I-D.burke-content-signature] schemes signed just the content, while ([I-D.cavage-http-signatures] could also sign the response headers and the request method and path. However, the same path, response headers, and content may mean something very different when retrieved from a different server. Section 5.1.1 currently includes the whole request URL in the signature, but it's possible we need a more flexible scheme to allow some higher-level protocols to accept a less-signed URL.¶

Servers might want to sign other request headers in order to capture their effects on content negotiation. However, there's no standard algorithm to check that a client's actual request headers match request headers sent by a server. The most promising attempt at this is [I-D.ietf-httpbis-variants], which encodes the content negotiation algorithm into the Variants and Variant-Key response headers. The proposal here (Section 3) assumes that is in use and doesn't sign request headers.¶

B.3. Response lifespan

A normal HTTPS response is authoritative only for one client, for as long as its cache headers say it should live. A signed exchange can be re-used for many clients, and if it was generated while a server was compromised, it can continue compromising clients even if their requests happen after the server recovers. This signing scheme needs to mitigate that risk.¶

B.4. Low implementation complexity

Simpler implementations are, all things equal, less likely to include bugs. This section describes decisions that were made in the rest of the specification to reduce complexity.¶

C.1. Example of updating cache control

For example, given a stored exchange of:¶

GET  / HTTP/1.1
Host: example.com
Accept: */*

HTTP/1.1 200
Date: Mon, 20 Nov 2017 10:00:00 UTC
Content-Type: text/html
Date: Tue, 21 Nov 2017 10:00:00 UTC
Expires: Sun, 26 Nov 2017 10:00:00 UTC

<!doctype html>
<html>
...

And an update listing the following headers:¶

Expires: Fri, 1 Dec 2017 10:00:00 UTC
Date: Sat, 25 Nov 2017 10:00:00 UTC

The resulting stored exchange would be:¶

GET / HTTP/1.1
Host: example.com
Accept: */*

HTTP/1.1 200
Content-Type: text/html
Expires: Fri, 1 Dec 2017 10:00:00 UTC
Date: Sat, 25 Nov 2017 10:00:00 UTC

<!doctype html>
<html>
...

C.2. Downsides of updating cache control

In an exchange with multiple signatures, using cache control to expire signatures forces all signatures to initially live for the same period. Worse, the update from one signature's "validity-url" might not match the update for another signature. Clients would need to maintain a current set of headers for each signature, and then decide which set to use when actually parsing the resource itself.¶

This need to store and reconcile multiple sets of headers for a single signed exchange argues for embedding a signature's lifetime into the signature.¶