Merge pull request #28 from tlswg/caw/edits

Editorial pass to simplify text and unify terminology.

draft-ietf-tls-external-psk-importer.md

@@ -21,8 +21,7 @@ author:
   -
     ins: C. A. Wood
     name: Christopher A. Wood
-    organization: Apple, Inc.
-    email: cawood@apple.com
+    email: caw@heapingbits.net
 
 
 normative:
@@ -54,14 +53,14 @@ informative:
 
 --- abstract
 
-This document describes an interface for importing external PSK (Pre-Shared Key) into
-TLS 1.3.
+This document describes an interface for importing external Pre-Shared Keys (PSKs)
+into TLS 1.3.
 
 --- middle
 
 # Introduction
 
-TLS 1.3 {{!RFC8446}} supports pre-shared key (PSK) authentication, wherein PSKs
+TLS 1.3 {{!RFC8446}} supports Pre-Shared Key (PSK) authentication, wherein PSKs
 can be established via session tickets from prior connections or externally via some 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
@@ -70,13 +69,13 @@ could possibly be re-used in two different contexts with the same hash functions
 derivation. Moreover, it requires external PSKs to be provisioned for specific hash
 functions.
 
-To mitigate these problems, external PSKs can be bound to a specific KDF and hash function
-when used in TLS 1.3, even if they are associated with a different hash function when provisioned.
-This document specifies an interface by which external PSKs may be imported for use in a TLS 1.3 connection
-to achieve this goal. In particular, it describes how KDF-bound PSKs can be differentiated by
-the target (D)TLS protocol version and KDF for which the PSK will be used. This produces a set
-of candidate PSKs, each of which are bound to a specific target protocol and KDF. This expands what
-would normally have been a single PSK identity into a set of PSK identities.
+To mitigate these problems, this document specifies a PSK Importer interface by which
+external PSKs may be imported and subsequently bound to a specific KDF and hash function
+for use in TLS 1.3. In particular, it describes a mechanism for differentiating
+external PSKs by the target KDF, (D)TLS protocol version, and an optional context
+string. This process yields a set of candidate PSKs, each of which are bound
+to a target KDF and protocol. This expands what would normally have been a single
+PSK and identity into a set of PSKs and identities.
 
 # Conventions and Definitions
 
@@ -87,20 +86,24 @@ when, and only when, they appear in all capitals, as shown here.
 
 # Overview
 
-Key importers mirror the concept of key exporters in TLS in that they diversify a key
-based on some contextual information before use in a connection. In contrast to key exporters,
-wherein differentiation is done via an explicit label and context string, the key importer
-defined herein diversifies external one PSK into one or more PSKs for use via a target protocol,
-KDF identifier, and optional context string. Additionally, the resulting PSK binder key is modified
-with a new derivation label to prevent confusion with non-imported PSKs.
-
-Imported keys do not require negotiation for use, as a client and server will not agree upon
-identities if not imported correctly. Endpoints may incrementally deploy PSK importer support
+The PSK Importer interface mirrors that of the TLS Exporters interface in that
+it diversifies a key based on some contextual information. In contrast to the Exporters
+interface, wherein differentiation is done 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. Each of these
+derived PSKs are bound 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.
+
+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 keys for TLS versions prior to TLS 1.3. Non-imported and imported PSKs
 are distinct since their identities are different on the wire. See {{rollout}} for more details.
 
-Clients which import external keys TLS MUST NOT use these keys for any other purpose.
-Moreover, each external PSK MUST be associated with at most one hash function.
+Clients which import external keys MUST NOT use either the external keys or the derived
+keys for any other purpose. Moreover, each external PSK MUST be associated with at most
+one hash function, as per the rules in Section 4.2.11 from {{!RFC8446}}.
+See {{security-considerations}} for more discussion.
 
 ## Terminology {#terminology}
 
@@ -110,24 +113,22 @@ connection, which is a tuple of (Base Key, External Identity, Hash).
 - 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 PSK derived from an EPSK, external identity, optional context string,
+- Imported PSK (IPSK): A PSK derived from an EPSK, External Identity, optional context string,
 and target protocol and KDF.
 - Imported Identity: A sequence of bytes used to identify an IPSK.
 
-# Key Import
+# PSK Import
 
-A key importer diversifies an input EPSK into one or more PSKs advertised on the wire via
-a target protocol, KDF identifier, and optional context string. Additionally, the resulting
-PSK binder key is modified with a new derivation label to prevent confusion with non-imported
-PSKs. This section describes the diversification mechanism and binder key computation change.
+This section describes the PSK Importer interface and its underlying diversification
+mechanism and binder key computation modification.
 
 ## External PSK Diversification
 
-A key importer takes as input an EPSK with external identity `external_identity` and base key `epsk`,
+The PSK Importer interface takes as input an EPSK with External Identity `external_identity` and base key `epsk`,
 as defined in {{terminology}}, along with an optional context, and transforms it into a set of PSKs
-and imported identities for use in a connection based on supported (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:
+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 {
@@ -138,8 +139,8 @@ struct {
 } ImportedIdentity;
 ~~~
 
-The list of `target_kdf` values is maintained by IANA as described in {{IANA}}. External PSKs MUST NOT
-be imported for (D)TLS 1.2 or prior versions. See {{rollout}} for discussion on
+The list of `target_kdf` values is maintained by IANA as described in {{IANA}}.
+External PSKs MUST NOT be imported for (D)TLS 1.2 or prior versions. See {{rollout}} for discussion on
 how imported PSKs for TLS 1.3 and non-imported PSKs for earlier versions co-exist for incremental
 deployment.
 
@@ -155,47 +156,48 @@ PSK is being imported. For example, TLS 1.3 {{!RFC8446}} and QUICv1 {{!QUIC=I-D.
 use 0x0304. Note that this means future versions of TLS will increase the number of PSKs
 derived from an external PSK.
 
-An Imported PSK derived from an EPSK with base key 'epsk' bound to this identity is then
-computed as follows:
+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 is corresponds to the KDF output length of ImportedIdentity.target_kdf as defined in {{IANA}}.
+L corresponds to the KDF output length of ImportedIdentity.target_kdf as defined in {{IANA}}.
 For hash-based KDFs, such as HKDF_SHA256(0x0001), this is the length of the hash function
 output, i.e., 32 octets. This is required for the IPSK to be of length suitable for supported
 ciphersuites.
 
-The identity of 'ipskx' as sent on the wire is ImportedIdentity, i.e., the serialized content
+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 TLS 1.3 binder key is `ipskx`.
 
 The hash function used for HKDF {{!RFC5869}} is that which is associated with the EPSK.
 It is not the hash function associated with ImportedIdentity.target_kdf. If no hash function
 is specified, SHA-256 MUST be used. Diversifying EPSK by ImportedIdentity.target_kdf ensures
 that an IPSK is only used as input keying material to at most one KDF, thus satisfying
-the requirements in {{!RFC8446}}.
-
-Endpoints 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.
+the requirements in {{!RFC8446}}. See {{security-considerations}} for more details.
 
-The resulting IPSK base key 'ipskx' is then used as the binder key in TLS 1.3 with identity
-ImportedIdentity. With knowledge of the supported KDFs, one may import PSKs before the start
-of a connection.
+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.
 
-EPSKs may be imported for early data use if they are bound to protocol settings and configurations that would
-otherwise be required for early data with normal (ticket-based PSK) resumption. Minimally, that means ALPN,
-QUIC transport settings, etc., must be provisioned alongside these EPSKs.
+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 protocol settings and configurations that would otherwise be
+required for early data with normal (ticket-based PSK) resumption. Minimally, that
+means ALPN, QUIC transport parameters (if used for QUIC), etc., must be provisioned
+alongside these EPSKs.
 
 ## Binder Key Derivation
 
-To prevent PSK Importers from being confused with standard out-of-band 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:
+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
@@ -209,7 +211,7 @@ computation is defined as follows:
 ~~~
 
 Imported PSKs replace the string "ext binder" with "imp binder" when deriving `binder_key`.
-This means the binder key is now computed as follows:
+This means the binder key is computed as follows:
 
 ~~~
              0
@@ -224,10 +226,10 @@ This means the binder key is now computed as follows:
              V
 ~~~
 
-This new label differentiates non-imported and imported external PSKs. Specifically, 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.
+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.
 
 # Deprecating Hash Functions
 
@@ -240,14 +242,14 @@ This does not affect the KDF operation used to derive Imported PSKs.
 Recall that TLS 1.2 permits computing the TLS PRF with any hash algorithm and PSK.
 Thus, an EPSK may be used with the same KDF (and underlying HMAC hash algorithm)
 as TLS 1.3 with importers. However, critically, the derived PSK will not be the same since
-the importer differentiates the PSK via the identity, target protocol, and target KDF. Thus,
+the importer differentiates the PSK via the identity and target KDF and protocol. Thus,
 PSKs imported for TLS 1.3 are distinct from those used in TLS 1.2, and thereby avoid
 cross-protocol collisions. Note that this does not preclude endpoints from using non-imported
 PSKs for TLS 1.2. Indeed, this is necessary for incremental deployment.
 
 # Security Considerations
 
-The Key Importer security goals can be roughly stated as follows: avoid PSK re-use across
+The PSK Importer security goals can be roughly stated as follows: avoid PSK re-use 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
@@ -260,17 +262,18 @@ uses existing key material to authenticate both endpoints. Following the work of
 speaking, compound authentication is the property that an execution of multiple authentication
 protocols, wherein at least one is uncompromised, jointly authenticates all protocols.
 Authenticating with an externally provisioned PSK, therefore, should ideally authenticate both
-the TLS connection and the external provision process. Typically, the external provision process
+the TLS connection and the external provisioning process. Typically, the external provision process
 produces a PSK and corresponding context from which the PSK was derived and in which it should
-be used. We refer to an external PSK without such context as "context free".
+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 Key
-Import API described in this document aims to achieve the following goals:
+Thus, in considering the source-independence and compound authentication requirements, the PSK
+Import interface described in this document aims to achieve the following goals:
 
-1. Externally provisioned PSKs imported into TLS achieve compound authentication of the
-provision step(s) and connection.
+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 used as IKM for two different KDFs.
+3. Imported PSKs are not used as IKM for two different KDFs.
 4. Imported PSKs do not collide with existing PSKs used for TLS 1.2 and below.
 5. Imported PSKs do not collide with future protocol versions and KDFs.