]>

ietf@vitalvas.com

Security end-to-end encryption X25519 AES-GCM HKDF HTTP API This document specifies an application-layer end-to-end encryption (E2EE) scheme for HTTP APIs. The scheme uses X25519 Elliptic Curve Diffie-Hellman (ECDH) for key agreement, HKDF-SHA256 for key derivation, and AES-GCM (with 128-, 192-, or 256-bit keys) for authenticated encryption of request and response payloads. Server public keys are discovered through a Well-Known URI and authenticated either by TLS or by a stronger out-of-band trust mechanism, depending on the deployment threat model. The scheme is designed to provide confidentiality and integrity of payloads independent of, and in addition to, transport-layer security such as TLS. It provides replay protection and key rotation.

Introduction Transport Layer Security (TLS) protects HTTP traffic between two endpoints that share a direct connection. In many modern deployments, however, request and response payloads traverse intermediaries such as reverse proxies, load balancers, content delivery networks, and API gateways. Each intermediary terminates TLS and observes plaintext, which expands the attack surface and weakens the confidentiality guarantee provided to end users. This document specifies a payload-level end-to-end encryption (E2EE) scheme for HTTP APIs. The scheme protects the request and response payload between the originating client and the terminating application server. Intermediaries that handle the HTTP message can route, log metadata, and apply policy. They cannot read or modify the protected payload when clients authenticate the server key set according to the deployment threat model described in . The scheme combines: X25519 for Elliptic Curve Diffie-Hellman (ECDH) key agreement. HKDF with SHA-256 for deriving symmetric keys from the shared secret. AES-GCM with 128-, 192-, or 256-bit keys for authenticated encryption of payloads. A Well-Known URI for publishing the server's static or rotating public key set. The scheme does not replace TLS; it is intended to be deployed on top of TLS so that transport metadata such as the Host header and request path remain protected on the wire.

Conventions and Definitions 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 when, and only when, they appear in all capitals, as shown here. This document uses the following terms:

Client:

The party that initiates an HTTP request and that owns an ephemeral X25519 key pair for the duration of a session.

Server:

The party that terminates the HTTP request, owns one or more X25519 key pairs whose public components are published, and processes the decrypted payload.

Encryption Key (EK):

A direction-specific symmetric key of 128, 192, or 256 bits derived from the X25519 shared secret using HKDF-SHA256 and used as the AES-GCM key. The length is determined by the negotiated AEAD identifier (see ).

AEAD Identifier (AEAD):

A short string naming the AES-GCM variant in use. One of "AES-128-GCM", "AES-192-GCM", or "AES-256-GCM".

Key Identifier (KID):

A short, opaque label that identifies one public key in the server's published key set.

Fingerprint:

A base64url-encoded prefix of the SHA-256 hash of a public key, intended for human-readable verification.

Protocol Overview The protocol has three phases: key discovery, key agreement, and authenticated message exchange.

| | | | 200 OK { keys: [ ... ] } | |<---------------------------------------------| | | | generate ephemeral (csk, cpk) | | shared = X25519(csk, server_public_key) | | EK_req, EK_res = HKDF-SHA256(...) | | | | POST /api/v1/resource | | E2EE-Session: ""; | | aead="AES-256-GCM"; | | epk=:<32B base64>:; ts=; | | nid="" | | Content-Type: application/e2ee | | Body: nonce || ciphertext || tag | |--------------------------------------------->| | | | shared = X25519(...) | | EK_req, EK_res = ... | | decrypt, process | | | | 200 OK | | E2EE-Session: ""; | | aead="AES-256-GCM"; ts= | | Content-Type: application/e2ee | | Body: nonce || ciphertext || tag | |<---------------------------------------------| | | ]]>

Key Discovery

Well-Known URI A server that supports this scheme MUST publish its public key set at the Well-Known URI :

The resource MUST be served over HTTPS and MUST be retrievable with an HTTP GET request. The response MUST have media type application/json.

Key Set Document The response body is a JSON object with the following members:

issuer:

A string identifying the server origin. The value MUST be an HTTPS origin and MUST match the origin from which the key set was retrieved unless the client has explicit out-of-band configuration allowing another issuer. REQUIRED.

keys:

A JSON array of one or more key objects, ordered from most-preferred to least-preferred. REQUIRED.

Each key object has the following members:

kid:

A short opaque string identifying this key within the set. REQUIRED. KIDs MUST be unique within a single key set. The value MUST contain between 1 and 128 characters and MUST match the regular expression ^[A-Za-z0-9._~-]+$. KID comparison is case-sensitive.

alg:

The key agreement algorithm. MUST be the string "X25519" for this version of the protocol. REQUIRED.

aeads:

A non-empty JSON array of AEAD Identifier strings (see ) that the server is willing to accept under this key, in order of server preference. REQUIRED.

public_key:

The 32-byte X25519 public key, base64url-encoded without padding. REQUIRED.

fingerprint:

The base64url-encoded first 16 bytes of the SHA-256 hash of the raw 32-byte public key. RECOMMENDED.

not_before:

An RFC 3339 date-time value before which the key MUST NOT be used. OPTIONAL.

not_after:

An RFC 3339 date-time value after which the key MUST NOT be used. REQUIRED.

max_skew:

A non-negative integer specifying the maximum acceptable absolute difference, in seconds, between the request ts parameter and the server clock. This value bounds the timestamp check in addition to the key validity window and determines the minimum replay-cache retention period (see ). REQUIRED.

Clients MUST treat a key object that is missing a required member, has a member of the wrong JSON type, or contains an invalid public_key, not_before, not_after, or max_skew value as unusable. Clients MUST treat a key set containing duplicate kid values as invalid. Example:

Caching Responses SHOULD include a Cache-Control header. Clients MAY cache the key set for up to the duration indicated, but MUST refresh the key set before using a key whose not_after is in the past, and SHOULD refresh on receipt of a key_unknown error (see ).

Out-of-Band Trust The integrity of the key set ultimately depends on the integrity of the channel used to retrieve it. Clients MUST verify the TLS server certificate of the server hosting the Well-Known URI per and . Clients MUST also verify that the issuer value in the key set matches the HTTPS origin used to retrieve it, unless an out-of-band configuration explicitly authorizes a different issuer. If the deployment threat model includes TLS-terminating intermediaries that are not trusted with plaintext payloads, TLS authentication of the Well-Known URI is not sufficient to authenticate the encryption keys: such an intermediary could substitute its own key set. In that threat model, clients MUST authenticate the key set independently of the TLS connection by using either a pinned key fingerprint or a verified HTTP Message Signature whose signing key was distributed out of band; see . Servers SHOULD additionally protect the key set response with HTTP Message Signatures , signed under a long-lived signing key distributed out of band, and SHOULD include a Content-Digest field over the key set body so that the signature covers a content hash rather than the raw bytes. Clients that have a pinned signing key MUST reject any key set response whose signature is missing or invalid.

AEAD Identifiers This document defines three AEAD Identifiers, all based on AES-GCM : AEAD Identifier Key length Nonce length Tag length AES-128-GCM 16 octets 12 octets 16 octets AES-192-GCM 24 octets 12 octets 16 octets AES-256-GCM 32 octets 12 octets 16 octets All three variants share the same nonce and tag length and differ only in key length. Implementations MUST support AES-128-GCM and AES-256-GCM. Support for AES-192-GCM is OPTIONAL. The client selects one AEAD Identifier from the server's aeads list for each session and signals it in the request (see ). The server MUST reject any request whose AEAD Identifier is not advertised in the current key set entry for the chosen kid.

Key Agreement and Derivation

Ephemeral Client Keys and Sessions A session is a contiguous sequence of requests sent by one client under a single X25519 key pair (csk, cpk). The client public key cpk is sent on the wire as the epk parameter of the E2EE-Session field. Clients MUST generate (csk, cpk) using a cryptographically secure random number generator. The default session scope is a single request: clients SHOULD generate a fresh key pair for every request unless they explicitly opt into a broader scope as described below. A client MAY reuse one (csk, cpk) across multiple requests provided that all of the following hold: The reuse is confined to a single logical client instance (one process, one user, one device). The key pair is not persisted to non-volatile storage and is destroyed on process exit, user logout, or after a deployment- defined inactivity timeout, whichever comes first. The deployment-defined session lifetime does not exceed the shortest not_after of any server key it references. The client maintains its own nid uniqueness within the session (see ). Clients MUST NOT reuse (csk, cpk) across processes, after restart, across users on a shared device, or after any event that would invalidate the client's secure-random state (for example, virtual machine snapshot restore). Each unique value of epk observed by a server defines, together with the server kid, the scope of replay-cache state for that client (see ). Per-request session scope therefore minimises both the lifetime of the client private key and the amount of replay-cache state retained for any one client.

Shared Secret The shared secret is computed as:

per Section 5 of . Implementations MUST check that Z is not the all-zero value and abort if it is.

Encryption Key Derivation The request encryption key (EK_req) and response encryption key (EK_res) are derived from Z using HKDF-SHA256 :

where: || denotes octet-string concatenation, cpk is the raw 32-byte client public key, server_public_key is the raw 32-byte server public key, issuer is the UTF-8 encoding of the key set issuer value, aead is the UTF-8 encoding of the selected AEAD Identifier ("AES-128-GCM", "AES-192-GCM", or "AES-256-GCM"), kid is the UTF-8 encoding of the Key Identifier used, Nk is the key length in octets implied by aead (16, 24, or 32). Binding issuer, aead, kid, and both public keys into the HKDF inputs binds the derived keys to the specific key agreement transcript and prevents cross-origin, cross-protocol, cross-key, cross-direction, or cross-algorithm confusion. Deriving separate request and response keys prevents an AES-GCM nonce collision in one direction from colliding with a nonce in the other direction.

Message Format

Media Type Protected payloads MUST be sent with the media type application/e2ee. The media type identifies the ciphertext envelope defined by this document; the plaintext media type, when needed, is carried in the cty parameter of the E2EE-Session field (see ).

Wire Format The body of a protected request or response is the concatenation:

where: nonce is 12 octets, generated with a cryptographically secure random number generator for every message. Nonces MUST NOT be reused with the same direction-specific EK. ciphertext is the AES-GCM encryption of the inner plaintext using EK_req for requests or EK_res for responses and nonce, with additional authenticated data (AAD) as defined in . The AES-GCM key length is determined by the selected AEAD Identifier (see ). tag is the 16-octet AES-GCM authentication tag. Recipients MUST reject a protected body shorter than 28 octets (12-octet nonce plus 16-octet tag) as malformed.

Interaction with Content-Digest The AES-GCM tag already provides end-to-end integrity for the ciphertext, so a Content-Digest field is not required for integrity. Senders MAY include Content-Digest over the raw ciphertext body for caching, deduplication, or intermediary integrity checks; in that case the digest MUST be computed over the exact serialized body (nonce || ciphertext || tag). Recipients MUST NOT treat a present Content-Digest as a substitute for AES-GCM tag verification, and MUST NOT compute or expose a digest over the decrypted plaintext.

Additional Authenticated Data The AAD passed to AES-GCM binds only the cryptographic transcript of the message. HTTP semantics such as method, target URI, status code, and selected headers are out of scope for AAD and are bound, when needed, by HTTP Message Signatures (see ). For AAD construction, an E2EE-Session field value MUST first be parsed as a Structured Field Item and then serialized using the deterministic serialization algorithm for Structured Fields . The serialized field value does not include the field name, colon, or surrounding whitespace. Recipients MUST NOT use the raw field bytes as received from an HTTP/1.1 connection, because equivalent field values can have different wire serializations and HTTP/2 and HTTP/3 do not preserve an HTTP/1.1 header-field line. For requests, the AAD MUST be the ASCII concatenation:

For responses, the AAD MUST be the ASCII concatenation:

where: encryption-field is the deterministic serialization of the request's parsed E2EE-Session Structured Field value (see ), req-encryption-field is the same value as encryption-field for the request that produced this response, res-encryption-field is the deterministic serialization of the response's own parsed E2EE-Session field value. The leading "e2ee/v1:req" / "e2ee/v1:res" strings combine a protocol-version tag with a domain-separation tag. They prevent a request ciphertext from being accepted as a response (or vice versa) and isolate this protocol from any other use of AES-GCM under the same key. Including both E2EE-Session fields in the response AAD authenticates kid, aead, epk, ts, and nid from both directions jointly with the ciphertext, prevents an intermediary from altering any of them, and prevents response substitution across different requests.

Binding HTTP Semantics This specification does not bind HTTP semantics (method, target URI, status code, request or response headers) into the AES-GCM AAD. Doing so would conflict with the routine behaviour of TLS-terminating intermediaries that legitimately rewrite request targets, normalize paths, or add tracing parameters. Deployments that require an end-to-end binding of HTTP semantics SHOULD apply HTTP Message Signatures to requests and responses, alongside the encryption defined by this document. The covered-components list SHOULD include at least: For requests: @method, @target-uri, the E2EE-Session field, and a Content-Digest field computed over the ciphertext body. For responses: @status, the E2EE-Session field, and a Content-Digest field over the ciphertext body. Because Content-Digest covers the ciphertext (which already contains the AES-GCM tag), an RFC 9421 signature over those components transitively covers the encrypted payload. The signature key and keyid are independent of the X25519 key set defined here and are managed per . A deployment that omits HTTP Message Signatures relies on this protocol's confidentiality and integrity guarantees only at the payload layer, and on TLS and application-level checks for HTTP semantics. This is appropriate when the application cannot be confused by a redirected ciphertext (for example, when each endpoint parses a distinct payload schema and rejects unknown shapes).

The E2EE-Session Field All E2EE control metadata is carried in a single HTTP field named E2EE-Session. The field is a Structured Field whose value is an Item: a String identifying the server key (kid), with named parameters carrying the remaining metadata.

Syntax In the ABNF of , the field value is an sf-item:

The Item value is a String holding the kid. The following parameters are defined: Name Type Request Response Meaning aead String required required AEAD Identifier (see ). epk Byte Sequence required prohibited Client ephemeral X25519 public key. ts Integer required required Seconds since Unix epoch. nid String required required Per-message replay identifier (e.g. UUID). cty String optional optional Media type of the inner plaintext (see ). epk is the raw 32-octet X25519 public key carried as a Structured Fields Byte Sequence (RFC 9651 base64, sf-binary, delimited by :), not base64url. Servers MUST reject any value whose decoded length is not 32 octets. ts MUST be a non-negative Integer. nid MUST contain between 1 and 128 characters and MUST match the regular expression ^[A-Za-z0-9._~-]+$. nid comparison is case-sensitive. cty is OPTIONAL and, when present, MUST be the media type of the inner plaintext (see ). Parameters defined by future revisions of this specification or by extensions MUST use distinct names. Recipients MUST ignore unknown parameters semantically, but unknown parameters remain part of the deterministic serialization that is authenticated as AAD. A field value that contains the same parameter name more than once MUST be rejected as malformed; this check MUST occur before deterministic serialization. Implementations whose Structured Fields parser cannot report duplicate parameters MUST use a parser that can for this field.

Inner Content Type The plaintext recovered after AES-GCM decryption is opaque to this specification. To allow recipients to dispatch on its format without a separate inner header, senders MAY include a cty parameter on the E2EE-Session field carrying the inner plaintext's media type as a String, for example cty="application/json" or cty="application/cbor". The value MUST be a valid media type per Section 8.3 of . Media-type parameters (for example, charset=utf-8) MAY be present in cty. Recipients SHOULD treat the absence of cty as "unspecified" and rely on out-of-band knowledge of the endpoint to interpret the plaintext. Because cty is a parameter of the E2EE-Session field, it is covered by the AES-GCM AAD (see ), so an intermediary cannot alter the advertised inner media type without invalidating the tag. The outer HTTP Content-Type field, when present, MUST remain application/e2ee (or another media type defined for the ciphertext envelope); cty does not replace it. Recipients that receive both an outer Content-Type of application/e2ee and an inner cty MUST use cty only for the decrypted plaintext.

Example

(Line folding shown for readability; the field is a single Structured Field value. AAD construction uses deterministic Structured Fields serialization, not these presentation line breaks.)

Use in Requests and Responses Every request that carries an encrypted payload MUST include exactly one E2EE-Session field with all required parameters. A response that carries an encrypted payload MUST include an E2EE-Session field whose kid Item value and aead parameter echo the request. The epk parameter MUST be omitted from responses; the server reuses the client's ephemeral public key from the request. The ts parameter on a response MUST reflect the server's current time. A response MUST echo the request's nid so that clients can correlate responses and detect duplicate or substituted responses. Clients MUST verify that the kid Item value and the aead and nid parameters of the response E2EE-Session field match the values they sent in the corresponding request, and MUST discard the response without decrypting it on mismatch. A mismatch indicates either an in-path attacker or a misconfigured intermediary serving a cached or cross-routed response. Because the request's E2EE-Session field is included in the response AAD (see ), a mismatch is also detectable as an AES-GCM tag failure during decryption; the pre-decryption check is RECOMMENDED to avoid spending a decryption attempt on an obviously wrong response.

Validation Order Recipients MUST validate the E2EE-Session field before any other protocol step. For requests, servers MUST validate in the following order: Parse as a Structured Fields Item; reject as malformed on failure. Check that the Item value is a String, that all required request parameters are present, that no parameter prohibited in requests by is present, that no parameter name appears more than once, and that all known parameters have the types defined in ; reject as malformed on failure. If cty is present, validate it as a media type per Section 8.3 of ; reject as malformed on failure. Resolve kid against the current key set; reject as key_unknown or key_expired. Check aead against the aeads list for that kid; reject as aead_unsupported. Decode and length-check epk; reject as malformed. Check the protected body length; reject as malformed if it is shorter than 28 octets. Check ts against the selected key's not_before/not_after validity window and max_skew; reject as timestamp_skew if outside the window. Check nid against the replay cache; reject as replay_detected on hit, but do not insert the nid yet. Derive EK_req and attempt AES-GCM decryption; reject as decrypt_failed on tag failure. After successful authentication and before invoking application processing, insert the nid into the replay cache atomically. For responses, clients MUST validate in the following order: Parse as a Structured Fields Item; reject the response on failure. Check that the Item value is a String, that all required response parameters are present, that epk is absent, that no parameter name appears more than once, and that all parameters known to this specification have the types defined in ; reject the response on failure. If cty is present, validate it as a media type per Section 8.3 of ; reject the response on failure. Check that kid, aead, and nid match the request. Check the protected body length; reject the response if it is shorter than 28 octets. Check that ts is a non-negative Integer and is acceptable under local response freshness policy. Derive EK_res and attempt AES-GCM decryption; reject the response on tag failure.

Error Handling When a request cannot be processed due to a protocol error, the server MUST respond with an HTTP error status and a Problem Details object serialized as application/problem+json. The type member MUST be a URI of the form:

]]>

where <code> is one of the codes defined below. The status member MUST equal the HTTP status code of the response. The title member SHOULD be a short, fixed human-readable summary of the code. The detail member, if present, SHOULD describe the specific occurrence subject to the constraints in . Example:

The following codes are defined:

key_unknown:

HTTP 400. The kid Item value does not match any current key.

key_expired:

HTTP 400. The referenced key is outside its not_before/not_after window.

aead_unsupported:

HTTP 400. The aead parameter is not advertised for the referenced kid, or is not recognized by the server.

decrypt_failed:

HTTP 400. AES-GCM authentication failed.

timestamp_skew:

HTTP 400. The ts parameter is outside the acceptable window (see ).

replay_detected:

HTTP 425. The server has already processed a message with this nid within the replay window. The 425 (Too Early) status is reused here to signal that the server is unwilling to process a request that may be a replay.

malformed:

HTTP 400. The E2EE-Session field is missing, not parseable as a Structured Field Item, missing a required parameter, or has a parameter of the wrong type or length, or the protected body is too short to contain a nonce and tag.

IANA Considerations This document requests IANA actions in the following registries.

Well-Known URI IANA is requested to register the URI suffix encryption-keys in the "Well-Known URIs" registry established by , with this document as the reference.

URI suffix:

encryption-keys

Change controller:

IETF

Status:

permanent

Specification document:

This document.

Related information:

This resource returns a JSON key set used by the protocol defined in this document.

Media Type IANA is requested to register the media type application/e2ee in the "Media Types" registry, with this document as the reference and per the procedures in .

Type name:

application

Subtype name:

e2ee

Required parameters:

N/A

Optional parameters:

N/A

Encoding considerations:

binary

Security considerations:

See .

Interoperability considerations:

Implementations need to parse the E2EE-Session Structured Field and process the binary nonce || ciphertext || tag envelope defined by this document. Interoperability depends on agreement on the selected AEAD Identifier, the key set entry referenced by kid, and the AAD construction rules in .

Published specification:

This document.

Applications that use this media type:

HTTP APIs that use the encrypted payload envelope defined by this document.

Fragment identifier considerations:

N/A

Additional information:

Deprecated alias names for this type: N/A Magic number(s): N/A File extension(s): N/A Macintosh file type code(s): N/A

Person and email address to contact for further information:

See the Authors' Addresses section.

Intended usage:

LIMITED USE

Restrictions on usage:

This media type is intended for HTTP request and response payloads that use the encrypted envelope defined by this document. It is not a general-purpose stored file format.

Author:

See the Authors' Addresses section.

Change controller:

IETF

HTTP Field Names IANA is requested to register the following entry in the "Hypertext Transfer Protocol (HTTP) Field Name Registry": Field name: E2EE-Session Status: permanent Structured Type: Item Reference: This document

Problem Type URN Parameter Identifier IANA is requested to add the following entry to the "IETF URN Sub-namespace for Registered Protocol Parameter Identifiers" registry: Registered Parameter Identifier: e2ee Reference: This document IANA Registry Reference: E2EE Error Codes registry, created by this document The registration policy for this registry is IETF Review , as specified for the urn:ietf:params namespace by . The template required by is:

Registry name:

e2ee

Specification:

This document.

Repository:

The E2EE Error Codes registry created by this document.

Index value:

A problem type URI has the form urn:ietf:params:e2ee:error:<code>, where <code> is a lowercase ASCII error code registered in the E2EE Error Codes registry. No transformation or canonicalization is applied. Comparison is by exact string match.

E2EE Error Codes IANA is requested to create the "E2EE Error Codes" registry. The registration policy is Specification Required . Error codes are ASCII strings that MUST contain between 1 and 64 characters and MUST match the regular expression ^[a-z][a-z0-9_]{0,63}$. New registrations MUST provide: Error code HTTP status code Description Reference The initial contents of the registry are: Error code HTTP status Description Reference key_unknown 400 Key identifier is not recognized. This document key_expired 400 Key identifier is outside its validity. This document aead_unsupported 400 AEAD identifier is not supported. This document decrypt_failed 400 AEAD authentication failed. This document timestamp_skew 400 Timestamp is outside the accepted window. This document replay_detected 425 Replay identifier was already observed. This document malformed 400 Protocol metadata or body is malformed. This document

Security Considerations

Threat Model This scheme is designed to protect the confidentiality and integrity of request and response payloads against: Intermediaries that terminate TLS (reverse proxies, CDNs, API gateways), and Passive observers of any plaintext channel between the TLS terminator and the application backend. It is not designed to protect HTTP metadata (method, path, headers other than the protected body, response status) or to defeat traffic analysis. It does not authenticate the client by itself. Client authentication MAY be layered on top using the protected payload (for example, bearer tokens carried inside the ciphertext) or, preferably, by signing the request with HTTP Message Signatures ; in the latter case the signature input MUST include the E2EE-Session field and the Content-Digest field over the ciphertext body so that the signature also binds the AAD and ciphertext.

Transport Layer Security This scheme MUST be used over TLS configured per current best practice . TLS protects request metadata, the Well-Known key set retrieval, and provides server authentication.

Server Authentication and Key Trust When the TLS endpoint that serves the Well-Known URI is also the application endpoint trusted with plaintext payloads, the server's identity is authenticated by the TLS certificate of that host and by the issuer value in the key set. When TLS-terminating intermediaries are present and are not trusted with plaintext payloads, TLS authentication alone does not authenticate the encryption keys end to end. In that deployment, clients MUST verify the fingerprint of any key they use against a value obtained out of band (for example, distributed with the client software) or MUST verify a signature over the key set using a signing key distributed out of band. Mobile and desktop client implementations are RECOMMENDED to pin at least one fingerprint or signing key. Where stronger guarantees are required, servers SHOULD sign the key set with HTTP Message Signatures and cover the body with a Content-Digest field . The signing key is necessarily distributed out of band; clients that pin the signing key obtain key authenticity that is independent of the Web PKI used by TLS.

Forward Secrecy The client's key pair is ephemeral, but the server's published key is static for the lifetime of its key set entry. The scheme therefore provides forward secrecy only with respect to client-side compromise. Compromise of a server private key allows decryption of all sessions that used it. Operators SHOULD rotate server keys frequently and use short not_after windows. Implementations of this specification SHOULD publish at least two overlapping keys in the key set to enable seamless rotation. A future revision of this protocol MAY define a mode in which the server returns a fresh ephemeral public key on first contact, providing full perfect forward secrecy at the cost of an additional round trip.

Replay Protection Servers MUST validate the ts parameter against the key validity window for the referenced kid: any ts before not_before, when present, or after not_after MUST be rejected (timestamp_skew). Servers MUST also reject any ts whose absolute difference from the server clock exceeds the key set entry's max_skew value (timestamp_skew). Servers SHOULD publish a max_skew value no larger than the maximum retry interval they are willing to support; a value of 300 seconds is RECOMMENDED unless the deployment has stricter clock synchronization or longer retry requirements. Clients MUST read max_skew from the selected key set entry and account for it when scheduling retries. A retry sent with a fresh nid after the original request's timestamp has aged beyond max_skew is expected to fail timestamp validation. Servers MUST maintain a cache of recently seen nid values, keyed by (kid, epk), for at least max_skew plus a small tolerance for processing latency and clock granularity. A repeated nid MUST result in replay_detected. Clients MUST generate a fresh, unpredictable nid for every request; a version 4 UUID or any 128-bit value drawn from a cryptographically secure random number generator is sufficient. Servers MUST NOT insert a nid into the replay cache until the request has been authenticated successfully by AES-GCM. Inserting a nid before tag verification would allow an attacker to poison the replay cache with unauthenticated requests. Servers MUST insert the nid atomically after successful authentication and before application side effects occur; if another request with the same (kid, epk, nid) wins that atomic insertion, the later request MUST fail with replay_detected. The nid parameter is an anti-replay identifier and is not an application idempotency key. The two have opposite behavior on a cache hit: a duplicate nid MUST cause the server to reject the request, whereas a duplicate application idempotency key is normally expected to cause the server to return the stored response of the original request. Applications that require both fault-tolerant retries and end-to-end replay protection MUST use distinct values for the two purposes. An application idempotency key, if used, SHOULD be carried inside the encrypted payload so that the application sees it but intermediaries do not, and so that it is bound to the request by the AES-GCM tag. The 12-byte AES-GCM nonce is independently random per message and MUST NOT be reused under the same direction-specific EK.

Plaintext Error Responses Error responses defined in are sent as Problem Details in plaintext and are therefore visible to any TLS-terminating intermediary. Error responses do not carry encrypted application payloads and do not require an E2EE-Session field; some errors occur before the request E2EE-Session field can be parsed safely. Operators MUST treat error metadata as observable to intermediaries. In particular: The detail and instance members of the Problem Details object MUST NOT contain user identifiers, request contents, stack traces, or any value derived from the decrypted plaintext. The title member SHOULD be a fixed string per error code and MUST NOT vary with request content. Extension members defined by future revisions or by deployments MUST be subject to the same constraints. Error type URIs SHOULD be chosen from the fixed set in ; application-specific error information SHOULD instead be returned as an encrypted payload with an appropriate HTTP status. The presence of decrypt_failed or replay_detected reveals to an observer that an attack or a stale retry occurred; this is considered acceptable as it aids defenders more than attackers. Successful responses MUST carry their application payload encrypted under this specification; servers MUST NOT fall back to a plaintext success response when the request was encrypted.

Key Rotation Each request carries a kid, allowing the server to retain the private keys associated with all currently valid kids and decrypt requests that arrive during a rotation. Clients MUST refresh the key set when the cached entry has expired, when no key remains within its validity window, or on key_unknown.

Algorithm Agility This document specifies one key agreement algorithm (X25519), one key-derivation function (HKDF-SHA256), and three AEAD variants (AES-128/192/256-GCM). Servers MAY publish keys with alg values or list aeads entries defined by future specifications; clients that do not recognize an alg MUST ignore the key, and clients that do not recognize any of the aeads entries for a key MUST treat the key as unusable. AES-128-GCM and AES-256-GCM are mandatory to implement; AES-192-GCM is OPTIONAL because the 192-bit variant is rarely accelerated in hardware and provides no security advantage over AES-128-GCM in this setting. Implementations SHOULD prefer AES-256-GCM by default. AES-128-GCM is acceptable when interoperability or constrained-device performance takes precedence. Implementations MUST reject any single plaintext that exceeds the AES-GCM per-invocation input limit (approximately 2^39 - 256 bits per ). Deployments that reuse a client session across multiple requests SHOULD also enforce a maximum number of messages per direction-specific EK; with randomly generated 96-bit nonces, 2^32 messages under one direction-specific EK is an upper bound and is far above typical API usage.

Side Channels and Implementation X25519 implementations MUST be constant-time per . AES-GCM implementations SHOULD use hardware acceleration where available to reduce the risk of cache-timing leaks. HKDF and base64url implementations MUST validate input lengths to avoid out-of-bounds reads.

Denial of Service Decryption is comparatively cheap, but X25519 scalar multiplication is not free. Servers SHOULD rate-limit requests bearing unknown or expired kids, and SHOULD reject malformed bodies before performing key agreement.

Comparison with Transport-Layer Solutions This scheme is complementary to, and not a replacement for, alternatives such as mTLS or QUIC . It is specifically targeted at deployments where TLS-terminating intermediaries are part of the application architecture and removing them is not feasible.

Privacy Considerations This protocol improves payload confidentiality from the perspective of TLS-terminating intermediaries, but it does not hide HTTP metadata. Intermediaries can still observe the client and server endpoints, request timing, request method, target URI, status code, message sizes, and all unprotected HTTP fields. Applications that carry privacy-sensitive values in URIs or unprotected headers will still expose those values. The E2EE-Session field is also visible to intermediaries. Its kid, aead, ts, nid, epk, and cty parameters can reveal deployment state, timing, retry behavior, client session scope, and the media type of the inner plaintext. Clients that need to reduce linkability SHOULD use the default per-request client key scope and generate fresh nid values for every request. Plaintext error responses expose protocol failure information, as described in . Deployments SHOULD avoid putting user-specific or content-derived information in error details and SHOULD carry application-specific error information inside encrypted response payloads when feasible. These considerations are intended to supplement the privacy guidance in .

This memo specifies two elliptic curves over prime fields that offer a high level of practical security in cryptographic applications, including Transport Layer Security (TLS). These curves are intended to operate at the ~128-bit and ~224-bit security level, respectively, and are generated deterministically based on a list of required properties. This document specifies a simple Hashed Message Authentication Code (HMAC)-based key derivation function (HKDF), which can be used as a building block in various protocols and applications. The key derivation function (KDF) is intended to support a wide range of applications and requirements, and is conservative in its use of cryptographic hash functions. This document is not an Internet Standards Track specification; it is published for informational purposes. This memo defines a path prefix for "well-known locations", "/.well-known/", in selected Uniform Resource Identifier (URI) schemes. In doing so, it obsoletes RFC 5785 and updates the URI schemes defined in RFC 7230 to reserve that space. It also updates RFC 7595 to track URI schemes that support well-known URIs in their registry. This document describes the commonly used base 64, base 32, and base 16 encoding schemes. It also discusses the use of line-feeds in encoded data, use of padding in encoded data, use of non-alphabet characters in encoded data, use of different encoding alphabets, and canonical encodings. [STANDARDS-TRACK] The Hypertext Transfer Protocol (HTTP) is a stateless application-level protocol for distributed, collaborative, hypertext information systems. This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions. In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes. This document updates RFC 3864 and obsoletes RFCs 2818, 7231, 7232, 7233, 7235, 7538, 7615, 7694, and portions of 7230. This document specifies version 1.3 of the Transport Layer Security (TLS) protocol. TLS allows client/server applications to communicate over the Internet in a way that is designed to prevent eavesdropping, tampering, and message forgery. This document updates RFCs 5705 and 6066, and obsoletes RFCs 5077, 5246, and 6961. This document also specifies new requirements for TLS 1.2 implementations. This document defines a date and time format for use in Internet protocols that is a profile of the ISO 8601 standard for representation of dates and times using the Gregorian calendar. This document defines a "problem detail" to carry machine-readable details of errors in HTTP response content to avoid the need to define new error response formats for HTTP APIs. This document obsoletes RFC 7807. This document describes a set of data types and associated algorithms that are intended to make it easier and safer to define and handle HTTP header and trailer fields, known as "Structured Fields", "Structured Headers", or "Structured Trailers". It is intended for use by specifications of new HTTP fields. This document obsoletes RFC 8941. Transport Layer Security (TLS) and Datagram Transport Layer Security (DTLS) are used to protect data exchanged over a wide range of application protocols and can also form the basis for secure transport protocols. Over the years, the industry has witnessed several serious attacks on TLS and DTLS, including attacks on the most commonly used cipher suites and their modes of operation. This document provides the latest recommendations for ensuring the security of deployed services that use TLS and DTLS. These recommendations are applicable to the majority of use cases. RFC 7525, an earlier version of the TLS recommendations, was published when the industry was transitioning to TLS 1.2. Years later, this transition is largely complete, and TLS 1.3 is widely available. This document updates the guidance given the new environment and obsoletes RFC 7525. In addition, this document updates RFCs 5288 and 6066 in view of recent attacks. This document defines procedures for the specification and registration of media types for use in HTTP, MIME, and other Internet protocols. This memo documents an Internet Best Current Practice. Using TLS early data creates an exposure to the possibility of a replay attack. This document defines mechanisms that allow clients to communicate with servers about HTTP requests that are sent in early data. Techniques are described that use these mechanisms to mitigate the risk of replay. This document describes a mechanism for creating, encoding, and verifying digital signatures or message authentication codes over components of an HTTP message. This mechanism supports use cases where the full HTTP message may not be known to the signer and where the message may be transformed (e.g., by intermediaries) before reaching the verifier. This document also describes a means for requesting that a signature be applied to a subsequent HTTP message in an ongoing HTTP exchange. This document defines HTTP fields that support integrity digests. The Content-Digest field can be used for the integrity of HTTP message content. The Repr-Digest field can be used for the integrity of HTTP representations. Want-Content-Digest and Want-Repr-Digest can be used to indicate a sender's interest and preferences for receiving the respective Integrity fields. This document obsoletes RFC 3230 and the Digest and Want-Digest HTTP fields. This document describes a new sub-delegation for the 'ietf' URN namespace for registered protocol items. The 'ietf' URN namespace is defined in RFC 2648 as a root for persistent URIs that refer to IETF- defined resources. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. Many protocols make use of points of extensibility that use constants to identify various protocol parameters. To ensure that the values in these fields do not have conflicting uses and to promote interoperability, their allocations are often coordinated by a central record keeper. For IETF protocols, that role is filled by the Internet Assigned Numbers Authority (IANA). To make assignments in a given registry prudently, guidance describing the conditions under which new values should be assigned, as well as when and how modifications to existing values can be made, is needed. This document defines a framework for the documentation of these guidelines by specification authors, in order to assure that the provided guidance for the IANA Considerations is clear and addresses the various issues that are likely in the operation of a registry. This is the third edition of this document; it obsoletes RFC 5226. National Institute of Standards and Technology In many standards track documents several words are used to signify the requirements in the specification. These words are often capitalized. This document defines these words as they should be interpreted in IETF documents. This document specifies an Internet Best Current Practices for the Internet Community, and requests discussion and suggestions for improvements. RFC 2119 specifies common key words that may be used in protocol specifications. This document aims to reduce the ambiguity by clarifying that only UPPERCASE usage of the key words have the defined special meanings. This document offers guidance for developing privacy considerations for inclusion in protocol specifications. It aims to make designers, implementers, and users of Internet protocols aware of privacy-related design choices. It suggests that whether any individual RFC warrants a specific privacy considerations section will depend on the document's content. This document defines the core of the QUIC transport protocol. QUIC provides applications with flow-controlled streams for structured communication, low-latency connection establishment, and network path migration. QUIC includes security measures that ensure confidentiality, integrity, and availability in a range of deployment circumstances. Accompanying documents describe the integration of TLS for key negotiation, loss detection, and an exemplary congestion control algorithm.

Acknowledgments The protocol described in this document derives from an informal blog-post implementation of end-to-end encryption for HTTP APIs using X25519 and AES-GCM . This document formalizes the wire format, generalizes the cipher to AES-128/192/256-GCM with explicit negotiation, specifies additional authenticated data and replay protection, and defines key rotation semantics.

Worked Example This appendix shows one complete request/response pair using deterministic inputs. All values are hexadecimal unless noted; lines of the form = are byte-identical to what an interoperable implementation would compute. The inputs (private keys, AES-GCM nonces) are fixed so the example is reproducible; production code MUST NOT reuse these values.

Inputs

Key Agreement and Derivation

Request The serialized E2EE-Session field (single logical line):

The AAD is the ASCII string below, using deterministic Structured Fields serialization of the E2EE-Session field value:

(The :...: here stands for the full sf-binary form shown above and is shortened only for readability; the actual AAD contains the full deterministic serialization.)

The HTTP request body is nonce || ciphertext || tag, base64-encoded here for compactness:

Response The response uses a fresh nonce and a new ts, echoes kid, aead, and nid, and omits epk:

AAD (the request's deterministic field serialization followed by the response's deterministic field serialization):

plaintext = {"status":"ok","txid":"a1b2c3"} nonce = feedface0000000000000002 ciphertext = f111c0a217756b5f967108e32ce392d6 2f4de9380b2267c53b81cc4679bc59 tag = 5b64d39058d1bb23e2cec5f9c69880e1 body (base64) = /u36zgAAAAAAAAAC8RHAohd1a1+WcQjjLOOS1i9N6TgLImfFO4H MRnm8WVtk05BY0bsj4s7F+caYgOE= ]]>