diff options
Diffstat (limited to 'doc/rfc/rfc9258.txt')
| -rw-r--r-- | doc/rfc/rfc9258.txt | 549 |
1 files changed, 549 insertions, 0 deletions
diff --git a/doc/rfc/rfc9258.txt b/doc/rfc/rfc9258.txt new file mode 100644 index 0000000..913f316 --- /dev/null +++ b/doc/rfc/rfc9258.txt @@ -0,0 +1,549 @@ + + + + +Internet Engineering Task Force (IETF) D. Benjamin +Request for Comments: 9258 Google, LLC. +Category: Standards Track C. A. Wood +ISSN: 2070-1721 Cloudflare + July 2022 + + + Importing External Pre-Shared Keys (PSKs) for TLS 1.3 + +Abstract + + This document describes an interface for importing external Pre- + Shared Keys (PSKs) into TLS 1.3. + +Status of This Memo + + This is an Internet Standards Track document. + + This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by the + Internet Engineering Steering Group (IESG). Further information on + Internet Standards is available in Section 2 of RFC 7841. + + Information about the current status of this document, any errata, + and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9258. + +Copyright Notice + + Copyright (c) 2022 IETF Trust and the persons identified as the + document authors. All rights reserved. + + This document is subject to BCP 78 and the IETF Trust's Legal + Provisions Relating to IETF Documents + (https://trustee.ietf.org/license-info) in effect on the date of + publication of this document. Please review these documents + carefully, as they describe your rights and restrictions with respect + to this document. Code Components extracted from this document must + include Revised BSD License text as described in Section 4.e of the + Trust Legal Provisions and are provided without warranty as described + in the Revised BSD License. + +Table of Contents + + 1. Introduction + 2. Conventions and Definitions + 3. Terminology + 4. Overview + 5. PSK Importer + 5.1. External PSK Diversification + 5.2. Binder Key Derivation + 6. Deprecating Hash Functions + 7. Incremental Deployment + 8. Security Considerations + 9. Privacy Considerations + 10. IANA Considerations + 11. References + 11.1. Normative References + 11.2. Informative References + Appendix A. Addressing Selfie + Acknowledgements + Authors' Addresses + +1. Introduction + + TLS 1.3 [RFC8446] supports Pre-Shared Key (PSK) authentication, + wherein PSKs can be established via session tickets from prior + connections or via some external, out-of-band mechanism. The + protocol mandates that each PSK only be used with a single hash + function. This was done to simplify protocol analysis. TLS 1.2 + [RFC5246], in contrast, has no such requirement, as a PSK may be used + with any hash algorithm and the TLS 1.2 pseudorandom function (PRF). + While there is no known way in which the same external PSK might + produce related output in TLS 1.3 and prior versions, only limited + analysis has been done. Applications SHOULD provision separate PSKs + for (D)TLS 1.3 and prior versions. In cases where this is not + possible (e.g., there are already-deployed external PSKs or + provisioning is otherwise limited), reusing external PSKs across + different versions of TLS may produce related outputs, which may, in + turn, lead to security problems; see Appendix E.7 of [RFC8446]. + + To mitigate such problems, this document specifies a PSK importer + interface by which external PSKs may be imported and subsequently + bound to a specific key derivation function (KDF) and hash function + for use in TLS 1.3 [RFC8446] and DTLS 1.3 [RFC9147]. In particular, + it describes a mechanism for importing PSKs derived from external + PSKs by including the target KDF, (D)TLS protocol version, and an + optional context string to ensure uniqueness. This process yields a + set of candidate PSKs, each of which are bound to a target KDF and + protocol, that are separate from those used in (D)TLS 1.2 and prior + versions. This expands what would normally have been a single PSK + and identity into a set of PSKs and identities. + +2. 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 [RFC2119] [RFC8174] when, and only when, they appear in all + capitals, as shown here. + +3. Terminology + + The following terms are used throughout this document: + + External PSK (EPSK): A PSK established or provisioned out of band + (i.e., not from a TLS connection) that is a tuple of (Base Key, + External Identity, Hash). + + Base Key: The secret value of an EPSK. + + External Identity: A sequence of bytes used to identify an EPSK. + + Target protocol: The protocol for which a PSK is imported for use. + + Target KDF: The KDF for which a PSK is imported for use. + + Imported PSK (IPSK): A TLS PSK derived from an EPSK, optional + context string, target protocol, and target KDF. + + Non-imported PSK: An EPSK that is used directly as a TLS PSK without + being imported. + + Imported Identity: A sequence of bytes used to identify an IPSK. + + This document uses presentation language from Section 3 of [RFC8446]. + +4. Overview + + The PSK importer interface mirrors that of the TLS exporter interface + (see [RFC8446]) in that it diversifies a key based on some contextual + information. In contrast to the exporter interface, wherein output + uniqueness is achieved via an explicit label and context string, the + PSK importer interface defined herein takes an external PSK and + identity and "imports" it into TLS, creating a set of "derived" PSKs + and identities that are each unique. Each of these derived PSKs are + bound to a target protocol, KDF identifier, and optional context + string. Additionally, the resulting PSK binder keys are modified + with a new derivation label to prevent confusion with non-imported + PSKs. Through this interface, importing external PSKs with different + identities yields distinct PSK binder keys. + + Imported keys do not require negotiation for use since a client and + server will not agree upon identities if imported incorrectly. + Endpoints may incrementally deploy PSK importer support by offering + non-imported PSKs for TLS versions prior to TLS 1.3. Non-imported + and imported PSKs are not equivalent since their identities are + different. See Section 7 for more details. + + Endpoints that import external keys MUST NOT use the keys that are + input to the import process for any purpose other than the importer, + and they MUST NOT use the derived keys for any purpose other than TLS + PSKs. Moreover, each external PSK fed to the importer process MUST + be associated with one hash function at most. This is analogous to + the rules in Section 4.2.11 of [RFC8446]. See Section 8 for more + discussion. + +5. PSK Importer + + This section describes the PSK importer interface and its underlying + diversification mechanism and binder key computation modification. + +5.1. External PSK Diversification + + As input, the PSK importer interface takes an EPSK with External + Identity external_identity and base key epsk (as defined in + Section 3) along with an optional context. It then transforms the + input into a set of PSKs and imported identities for use in a + connection based on target protocols and KDFs. In particular, for + each supported target protocol target_protocol and KDF target_kdf, + the importer constructs an ImportedIdentity structure as follows: + + struct { + opaque external_identity<1...2^16-1>; + opaque context<0..2^16-1>; + uint16 target_protocol; + uint16 target_kdf; + } ImportedIdentity; + + The list of ImportedIdentity.target_kdf values is maintained by IANA + as described in Section 10. External PSKs MUST NOT be imported for + (D)TLS 1.2 or prior versions. See Section 7 for discussion on how + imported PSKs for TLS 1.3 and non-imported PSKs for earlier versions + coexist for incremental deployment. + + ImportedIdentity.context MUST include the context used to determine + the EPSK, if any exists. For example, ImportedIdentity.context may + include information about peer roles or identities to mitigate + Selfie-style reflection attacks [Selfie]. See Appendix A for more + details. Since the EPSK is a key derived from an external protocol + or sequence of protocols, ImportedIdentity.context MUST include a + channel binding for the deriving protocols [RFC5056]. The details of + this binding are protocol specific and out of scope for this + document. + + ImportedIdentity.target_protocol MUST be the (D)TLS protocol version + for which the PSK is being imported. For example, TLS 1.3 [RFC8446] + uses 0x0304, which will therefore also be used by QUICv1 [QUIC]. + Note that this means the number of PSKs derived from an EPSK is a + function of the number of target protocols. + + Given an ImportedIdentity and corresponding EPSK with base key epsk, + an imported PSK IPSK with base key ipskx is computed as follows: + + epskx = HKDF-Extract(0, epsk) + ipskx = HKDF-Expand-Label(epskx, "derived psk", + Hash(ImportedIdentity), L) + + L corresponds to the KDF output length of ImportedIdentity.target_kdf + as defined in Section 10. For hash-based KDFs, such as HKDF_SHA256 + (0x0001), this is the length of the hash function output, e.g., 32 + octets for SHA256. This is required for the IPSK to be of length + suitable for supported ciphersuites. Internally, HKDF-Expand-Label + uses a label corresponding to ImportedIdentity.target_protocol (e.g., + "tls13" for TLS 1.3, as per Section 7.1 of [RFC8446] or "dtls13" for + DTLS 1.3, as per Section 5.10 of [RFC9147]). + + The identity of ipskx as sent on the wire is ImportedIdentity, i.e., + the serialized content of ImportedIdentity is used as the content of + PskIdentity.identity in the PSK extension. The corresponding PSK + input for the TLS 1.3 key schedule is "ipskx". + + As the maximum size of the PSK extension is 2^16 - 1 octets, an + Imported Identity that exceeds this size is likely to cause a + decoding error. Therefore, the PSK importer interface SHOULD reject + any ImportedIdentity that exceeds this size. + + The hash function used for HMAC-based Key Derivation Function (HKDF) + [RFC5869] is that which is associated with the EPSK. It is not the + hash function associated with ImportedIdentity.target_kdf. If the + EPSK does not have such an associated hash function, SHA-256 [SHA2] + SHOULD be used. Diversifying EPSK by ImportedIdentity.target_kdf + ensures that an IPSK is only used as input keying material to one KDF + at most, thus satisfying the requirements in [RFC8446]. See + Section 8 for more details. + + Endpoints SHOULD generate a compatible ipskx for each target + ciphersuite they offer. For example, importing a key for + TLS_AES_128_GCM_SHA256 and TLS_AES_256_GCM_SHA384 would yield two + PSKs: one for HKDF-SHA256 and another for HKDF-SHA384. In contrast, + if TLS_AES_128_GCM_SHA256 and TLS_CHACHA20_POLY1305_SHA256 are + supported, only one derived key is necessary. Each ciphersuite + uniquely identifies the target KDF. Future specifications that + change the way the KDF is negotiated will need to update this + specification to make clear how target KDFs are determined for the + import process. + + EPSKs MAY be imported before the start of a connection if the target + KDFs, protocols, and context string(s) are known a priori. EPSKs MAY + also be imported for early data use if they are bound to the protocol + settings and configuration that are required for sending early data. + Minimally, this means that the Application-Layer Protocol Negotiation + (ALPN) value [RFC7301], QUIC transport parameters (if used for QUIC), + and any other relevant parameters that are negotiated for early data + MUST be provisioned alongside these EPSKs. + +5.2. Binder Key Derivation + + To prevent confusion between imported and non-imported PSKs, imported + PSKs change the PSK binder key derivation label. In particular, the + standard TLS 1.3 PSK binder key computation is defined as follows: + + 0 + | + v + PSK -> HKDF-Extract = Early Secret + | + +-----> Derive-Secret(., "ext binder" | "res binder", "") + | = binder_key + V + + Imported PSKs use the string "imp binder" rather than "ext binder" or + "res binder" when deriving binder_key. This means the binder key is + computed as follows: + + 0 + | + v + PSK -> HKDF-Extract = Early Secret + | + +-----> Derive-Secret(., "ext binder" + | | "res binder" + | | "imp binder", "") + | = binder_key + V + + This new label ensures a client and server will negotiate use of an + external PSK if and only if (a) both endpoints import the PSK or (b) + neither endpoint imports the PSK. As binder_key is a leaf key, + changing its computation does not affect any other key. + +6. Deprecating Hash Functions + + If a client or server wishes to deprecate a hash function and no + longer use it for TLS 1.3, it removes the corresponding KDF from the + set of target KDFs used for importing keys. This does not affect the + KDF operation used to derive imported PSKs. + +7. Incremental Deployment + + In deployments that already have PSKs provisioned and in use with TLS + 1.2, attempting to incrementally deploy the importer mechanism would + result in concurrent use of the already-provisioned PSK directly as + both a TLS 1.2 PSK and an EPSK, which, in turn, could mean that the + same KDF and key would be used in two different protocol contexts. + This is not a recommended configuration; see Section 8 for more + details. However, the benefits of using TLS 1.3 and PSK importers + may prove sufficiently compelling that existing deployments choose to + enable this noncompliant configuration for a brief transition period + while new software (using TLS 1.3 and importers) is deployed. + Operators are advised to make any such transition period as short as + possible. + +8. Security Considerations + + The PSK importer security goals can be roughly stated as follows: + avoid PSK reuse across KDFs while properly authenticating endpoints. + When modeled as computational extractors, KDFs assume that input + keying material (IKM) is sampled from some "source" probability + distribution and that any two IKM values are chosen independently of + each other [Kraw10]. This source-independence requirement implies + that the same IKM value cannot be used for two different KDFs. + + PSK-based authentication is functionally equivalent to session + resumption in that a connection uses existing key material to + authenticate both endpoints. Following the work of [BAA15], this is + a form of compound authentication. Loosely speaking, compound + authentication is the property that an execution of multiple + authentication protocols, wherein at least one is uncompromised, + jointly authenticates all protocols. Therefore, authenticating with + an externally provisioned PSK should ideally authenticate both the + TLS connection and the external provisioning process. Typically, the + external provisioning process produces a PSK and corresponding + context from which the PSK was derived and in which it should be + used. If available, this is used as the ImportedIdentity.context + value. We refer to an external PSK without such context as "context- + free". + + Thus, in considering the source-independence and compound + authentication requirements, the PSK importer interface described in + this document aims to achieve the following goals: + + 1. Externally provisioned PSKs imported into a TLS connection + achieve compound authentication of the provisioning process and + connection. + + 2. Context-free PSKs only achieve authentication within the context + of a single connection. + + 3. Imported PSKs are not used as IKM for two different KDFs. + + 4. Imported PSKs do not collide with future protocol versions and + KDFs. + + There are no known related outputs or security issues caused from the + process for computing imported PSKs from an external PSK and the + processing of existing external PSKs used in (D)TLS 1.2 and below, as + noted in Section 7. However, only limited analysis has been done, + which is an additional reason why applications SHOULD provision + separate PSKs for (D)TLS 1.3 and prior versions, even when the + importer interface is used in (D)TLS 1.3. + + The PSK importer does not prevent applications from constructing non- + importer PSK identities that collide with imported PSK identities. + +9. Privacy Considerations + + External PSK identities are commonly static by design so that + endpoints may use them to look up keying material. As a result, for + some systems and use cases, this identity may become a persistent + tracking identifier. + + Note also that ImportedIdentity.context is visible in cleartext on + the wire as part of the PSK identity. Unless otherwise protected by + a mechanism such as TLS Encrypted ClientHello [ECH], applications + SHOULD NOT put sensitive information in this field. + +10. IANA Considerations + + IANA has created the "TLS KDF Identifiers" registry under the + existing "Transport Layer Security (TLS) Parameters" registry. + + The entries in the registry are as follows: + + +========+=================+===========+ + | Value | KDF Description | Reference | + +========+=================+===========+ + | 0x0000 | Reserved | RFC 9258 | + +--------+-----------------+-----------+ + | 0x0001 | HKDF_SHA256 | [RFC5869] | + +--------+-----------------+-----------+ + | 0x0002 | HKDF_SHA384 | [RFC5869] | + +--------+-----------------+-----------+ + + Table 1: TLS KDF Identifiers Registry + + New target KDF values are allocated according to the following + process: + + * Values in the range 0x0000-0xfeff are assigned via Specification + Required [RFC8126]. + + * Values in the range 0xff00-0xffff are reserved for Private Use + [RFC8126]. + + The procedures for requesting values in the Specification Required + space are specified in Section 17 of [RFC8447]. + +11. References + +11.1. Normative References + + [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate + Requirement Levels", BCP 14, RFC 2119, + DOI 10.17487/RFC2119, March 1997, + <https://www.rfc-editor.org/info/rfc2119>. + + [RFC5056] Williams, N., "On the Use of Channel Bindings to Secure + Channels", RFC 5056, DOI 10.17487/RFC5056, November 2007, + <https://www.rfc-editor.org/info/rfc5056>. + + [RFC5869] Krawczyk, H. and P. Eronen, "HMAC-based Extract-and-Expand + Key Derivation Function (HKDF)", RFC 5869, + DOI 10.17487/RFC5869, May 2010, + <https://www.rfc-editor.org/info/rfc5869>. + + [RFC8126] Cotton, M., Leiba, B., and T. Narten, "Guidelines for + Writing an IANA Considerations Section in RFCs", BCP 26, + RFC 8126, DOI 10.17487/RFC8126, June 2017, + <https://www.rfc-editor.org/info/rfc8126>. + + [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC + 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, + May 2017, <https://www.rfc-editor.org/info/rfc8174>. + + [RFC8446] Rescorla, E., "The Transport Layer Security (TLS) Protocol + Version 1.3", RFC 8446, DOI 10.17487/RFC8446, August 2018, + <https://www.rfc-editor.org/info/rfc8446>. + + [RFC8447] Salowey, J. and S. Turner, "IANA Registry Updates for TLS + and DTLS", RFC 8447, DOI 10.17487/RFC8447, August 2018, + <https://www.rfc-editor.org/info/rfc8447>. + + [RFC9147] Rescorla, E., Tschofenig, H., and N. Modadugu, "The + Datagram Transport Layer Security (DTLS) Protocol Version + 1.3", RFC 9147, DOI 10.17487/RFC9147, April 2022, + <https://www.rfc-editor.org/info/rfc9147>. + +11.2. Informative References + + [BAA15] Bhargavan, K., Delignat-Lavaud, A., and A. Pironti, + "Verified Contributive Channel Bindings for Compound + Authentication", Proceedings 2015 Network and Distributed + System Security, DOI 10.14722/ndss.2015.23277, February + 2015, <https://doi.org/10.14722/ndss.2015.23277>. + + [ECH] Rescorla, E., Oku, K., Sullivan, N., and C. A. Wood, "TLS + Encrypted Client Hello", Work in Progress, Internet-Draft, + draft-ietf-tls-esni-14, 13 February 2022, + <https://datatracker.ietf.org/doc/html/draft-ietf-tls- + esni-14>. + + [Kraw10] Krawczyk, H., "Cryptographic Extraction and Key + Derivation: The HKDF Scheme", Proceedings of Crypto 2010, + May 2010, <https://eprint.iacr.org/2010/264>. + + [QUIC] Iyengar, J., Ed. and M. Thomson, Ed., "QUIC: A UDP-Based + Multiplexed and Secure Transport", RFC 9000, + DOI 10.17487/RFC9000, May 2021, + <https://www.rfc-editor.org/info/rfc9000>. + + [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security + (TLS) Protocol Version 1.2", RFC 5246, + DOI 10.17487/RFC5246, August 2008, + <https://www.rfc-editor.org/info/rfc5246>. + + [RFC7301] Friedl, S., Popov, A., Langley, A., and E. Stephan, + "Transport Layer Security (TLS) Application-Layer Protocol + Negotiation Extension", RFC 7301, DOI 10.17487/RFC7301, + July 2014, <https://www.rfc-editor.org/info/rfc7301>. + + [Selfie] Drucker, N. and S. Gueron, "Selfie: reflections on TLS 1.3 + with PSK", DOI 10.1007/s00145-021-09387-y, May 2021, + <https://eprint.iacr.org/2019/347.pdf>. + + [SHA2] National Institute of Standards and Technology, "Secure + Hash Standard (SHS)", FIPS PUB 180-4, + DOI 10.6028/NIST.FIPS.180-4, August 2015, + <https://doi.org/10.6028/NIST.FIPS.180-4>. + +Appendix A. Addressing Selfie + + The Selfie attack [Selfie] relies on a misuse of the PSK interface. + The PSK interface makes the implicit assumption that each PSK is + known only to one client and one server. If multiple clients or + multiple servers with distinct roles share a PSK, TLS only + authenticates the entire group. A node successfully authenticates + its peer as being in the group whether the peer is another node or + itself. Note that this case can also occur when there are two nodes + sharing a PSK without predetermined roles. + + Applications that require authenticating finer-grained roles while + still configuring a single shared PSK across all nodes can resolve + this mismatch either by exchanging roles over the TLS connection + after the handshake or by incorporating the roles of both the client + and the server into the IPSK context string. For instance, if an + application identifies each node by the Media Access Control (MAC) + address, it could use the following context string. + + struct { + opaque client_mac<0..2^8-1>; + opaque server_mac<0..2^8-1>; + } Context; + + If an attacker then redirects a ClientHello intended for one node to + a different node, including the node that generated the ClientHello, + the receiver will compute a different context string and the + handshake will not complete. + + Note that, in this scenario, there is still a single shared PSK + across all nodes, so each node must be trusted not to impersonate + another node's role. + +Acknowledgements + + The authors thank Eric Rescorla and Martin Thomson for discussions + that led to the production of this document, as well as Christian + Huitema for input regarding privacy considerations of external PSKs. + John Preuß Mattsson provided input regarding PSK importer deployment + considerations. Hugo Krawczyk provided guidance for the security + considerations. Martin Thomson, Jonathan Hoyland, Scott Hollenbeck, + Benjamin Kaduk, and others all provided reviews, feedback, and + suggestions for improving the document. + +Authors' Addresses + + David Benjamin + Google, LLC. + Email: davidben@google.com + + + Christopher A. Wood + Cloudflare + Email: caw@heapingbits.net |