From 58cf7476f9a14e6daa4022af8ea540e9f1b0b74d Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Thu, 11 Jan 2024 09:45:50 -0800 Subject: [PATCH 1/4] Clarify status of security parameters Closes #1462 --- draft-ietf-taps-interface.md | 211 +++++++++++++++++++++++------------ 1 file changed, 142 insertions(+), 69 deletions(-) diff --git a/draft-ietf-taps-interface.md b/draft-ietf-taps-interface.md index 14a6e60e..3d83ffb9 100644 --- a/draft-ietf-taps-interface.md +++ b/draft-ietf-taps-interface.md @@ -353,12 +353,11 @@ LocalSpecifier.WithInterface("any") LocalSpecifier.WithService("https") TransportProperties := NewTransportProperties() -TransportProperties.Require(preserve-msg-boundaries) +TransportProperties.Require(preserveMsgBoundaries) // Reliable Data Transfer and Preserve Order are Required by default SecurityParameters := NewSecurityParameters() -SecurityParameters.Set(identity, myIdentity) -SecurityParameters.Set(server-certificate, myCertificate) +SecurityParameters.Set(serverCertificate, myCertificate) // Specifying a Remote Endpoint is optional when using Listen Preconnection := NewPreconnection(LocalSpecifier, @@ -1564,117 +1563,191 @@ This document specifies an abstract API, which could appear to conflict with the for security parameters to be unambiguous. The Transport Services System SHOULD provide reasonable, secure defaults for each enumerated security parameter, such that users of the system only need to specify parameters required to establish a secure connection -(e.g., 'server-certificate', 'client-certificate'). Specifying specific security parameters +(e.g., `ServerCertificate`, `ClientCertificate`). Specifying specific security parameters from enumerated values (e.g., specific ciphersuites) might constrain the Transport Protocols that can be selected during connection establishment. -Except as noted below, as with the rest of the Transport Services API, exact names of parameters and/or -values of enumerations (e.g., ciphersuites) used in the security parameters are system -and implementation specific, and ought to be chosen to follow the principle of least +Security configuration parameters are specified in the pre-connection phase +and are created as follows: + +~~~ +SecurityParameters := NewSecurityParameters() +~~~ + +Specific parameters are added using a call to `Set()` on the `SecurityParameters`. + +As with the rest of the Transport Services API, the exact names of parameters and/or +values of enumerations (e.g., ciphersuites) used in the security parameters are system- +and implementation-specific, and ought to be chosen to follow the principle of least surprise for users of the platform / language environment in question. -### Specifying Security Parameters on a Preconnection +For security parameters that are enumerations of known values, such as TLS +ciphersuites, implementations are responsible for exposing the set of values +they support. For security parameters that are not simple value types, such +as certificates and keys, implementations are responsible for exposing +types appropriate for the platform / language environment. -Common security parameters such as TLS ciphersuites are known to implementations. -Applications SHOULD use common safe defaults for these values whenever possible. -However, as discussed in {{?RFC8922}}, many transport security protocols require specific -security parameters and constraints from the client at the time of configuration and -actively during a handshake. +Applications SHOULD use common safe defaults for values such as TLS ciphersuite +whenever possible. However, as discussed in {{?RFC8922}}, many transport security protocols +require specific security parameters and constraints from the client at the time of +configuration and actively during a handshake. -The configuration parameters need to be specified in the pre-connection phase -and are created as follows: +The set of security parameters defined here are not exhaustive, but illustrative. +Implementations SHOULD expose an equivalent to the parameters listed below to allow for +sufficient configuration of security parameters, but the details are expected +to vary based on platform and implementation constraints. + +Representation of security parameters in implementations ought to parallel +that chosen for Transport Property names as suggested in {{scope-of-interface-defn}}. + +Connections that use Transport Services SHOULD use security in general. However, for +compatibility with endpoints that do not support transport security protocols (such +as a TCP endpoint that does not support TLS), applications can initialize their +security parameters to indicate that security can be disabled, or can be opportunistic. +If security is disabled, the Transport Services system will not attempt to add +transport security automatically. If security is opportunistic, it will allow +Connections without transport security, but will still attempt to use unauthenticated +security if available. ~~~ -SecurityParameters := NewSecurityParameters() +SecurityParameters := NewDisabledSecurityParameters() + +SecurityParameters := NewOpportunisticSecurityParameters() ~~~ -Security configuration parameters and sample usage follow: +### Certificate bundles + +Names: +: serverCertificate, clientCertificate -- One or more certificate bundles identifying the Local Endpoint, whether - as a server certificate or a client certificate. Multiple bundles may - be provided to allow selection among different protocol stacks that may - require differently formatted bundles. The form and format of the - certificate bundle is implementation-specific. Note that if the private - keys associated with a bundle are not available, e.g., since they are stored in hardware - security modules (HSMs), handshake callbacks are necessary. See below for details. +Type: +: Array of certificate objects + +Default: +: Empty array + +One or more certificate bundles identifying the Local Endpoint, whether +as a server certificate or a client certificate. Multiple bundles may +be provided to allow selection among different protocol stacks that may +require differently formatted bundles. The form and format of the +certificate bundle is implementation-specific. Note that if the private +keys associated with a bundle are not available, e.g., since they are stored in hardware +security modules (HSMs), handshake callbacks are necessary. See below for details. ~~~ -SecurityParameters.Set(server-certificate, myCertificateBundle[]) -SecurityParameters.Set(client-certificate, myCertificateBundle[]) +SecurityParameters.Set(serverCertificate, myCertificateBundle[]) +SecurityParameters.Set(clientCertificate, myCertificateBundle[]) ~~~ -- One or more certificate chains to use as pinned server - certificates, such that connecting will fail if the presented server - certificate does not match one of the supplied pinned certificates. - The form and format of the certificate chain is implementation-specific. +### Pinned server certificate + +Name: +: pinnedServerCertificate + +Type: +: Array of certificate chain objects + +Default: +: Empty array + +Zero or more certificate chains to use as pinned server +certificates, such that connecting will fail if the presented server +certificate does not match one of the supplied pinned certificates. +The form and format of the certificate chain is implementation-specific. ~~~ -SecurityParameters.Set(pinned-server-certificate, yourCertificateChain[]) +SecurityParameters.Set(pinnedServerCertificate, yourCertificateChain[]) ~~~ -- Application-layer protocol negotiation (ALPN) values: used to indicate which - application-layer protocols are negotiated by the security protocol layer. - See {{!ALPN=RFC7301}} for definition of the ALPN field. Note that the Transport - Services System can provide ALPN values automatically, based on - the protocols being used, if not explicitly specified by the application. +### Application-layer protocol negotiation + +Name: +: alpn + +Type: +: Array of Strings + +Default: +: Automatic selection + +Application-layer protocol negotiation (ALPN) values: used to indicate which +application-layer protocols are negotiated by the security protocol layer. +See {{!ALPN=RFC7301}} for definition of the ALPN field. Note that the Transport +Services System can provide ALPN values automatically, based on +the protocols being used, if not explicitly specified by the application. ~~~ -SecurityParameters.Set(alpn, "h2") +SecurityParameters.Set(alpn, ["h2"]) ~~~ -- Supported groups, ciphersuites, algorithms: Used to restrict what parameters - are used by underlying transport security protocols. When not specified, - these algorithms should use known and safe defaults for the system. +### Groups, ciphersuites, and signature algorithms + +Names: +: supportedGroup, ciphersuite, signatureAlgorithm + +Types: +: Arrays of implementation-specific enumerations + +Default: +: Automatic selection + +These are used to restrict what cryptographic parameters +are used by underlying transport security protocols. When not specified, +these algorithms should use known and safe defaults for the system. ~~~ -SecurityParameters.Set(supported-group, "secp256r1") -SecurityParameters.Set(ciphersuite, "TLS_AES_128_GCM_SHA256") -SecurityParameters.Set(signature-algorithm, "ecdsa_secp256r1_sha256") +SecurityParameters.Set(supportedGroup, secp256r1) +SecurityParameters.Set(ciphersuite, TLS_AES_128_GCM_SHA256) +SecurityParameters.Set(signatureAlgorithm, ecdsa_secp256r1_sha256) ~~~ -- Session cache management: Used to tune session cache capacity, lifetime, and -other policies. +### Session cache options -~~~ -SecurityParameters.Set(max-cached-sessions, 16) +Names: +: maxCachedSessions, cachedSessionLifetimeSeconds + +Type: +: Integer + +Default: +: Automatic selection -SecurityParameters.Set(cached-session-lifetime-seconds, 3600) +These values are used to tune session cache capacity and lifetime, and +can be extended to include other policies. + +~~~ +SecurityParameters.Set(maxCachedSessions, 16) +SecurityParameters.Set(cachedSessionLifetimeSeconds, 3600) ~~~ -- Pre-Shared Key import: Used to install pre-shared keying material established +### Pre-shared key + +Name: +: preSharedKey + +Type: +: Key and identity (platform-specific) + +Default: +: None + +Used to install pre-shared keying material established out-of-band. Each instance of pre-shared keying material is associated with some identity that typically identifies its use or has some protocol-specific meaning to the Remote Endpoint. Note that use of a pre-shared key will tend to select a single security protocol, and therefore directly select a single underlying protocol stack. ~~~ -SecurityParameters.Set(pre-shared-key, key, myIdentity) -~~~ - -Connections that use Transport Services SHOULD use security in general. However, for -compatibility with endpoints that do not support transport security protocols (such -as a TCP endpoint that does not support TLS), applications can initialize their -security parameters to indicate that security can be disabled, or can be opportunistic. -If security is disabled, the Transport Services system will not attempt to add -transport security automatically. If security is opportunistic, it will allow -Connections without transport security, but will still attempt to use unauthenticated -security if available. - -~~~ -SecurityParameters := NewDisabledSecurityParameters() - -SecurityParameters := NewOpportunisticSecurityParameters() +SecurityParameters.Set(preSharedKey, key, myIdentity) ~~~ -Representation of security parameters in implementations ought to parallel -that chosen for Transport Property names as suggested in {{scope-of-interface-defn}}. - ### Connection Establishment Callbacks Security decisions, especially pertaining to trust, are not static. Once configured, parameters can also be supplied during Connection establishment. These are best handled as client-provided callbacks. -Callbacks block the progress of the Connection establishment, which distinguishes them from other events in the transport system. How callbacks and events are implemented is specific to each implementation. +Callbacks block the progress of the Connection establishment, which distinguishes them +from other events in the transport system. How callbacks and events are implemented is specific to each implementation. Security handshake callbacks that could be invoked during Connection establishment include: - Trust verification callback: Invoked when a Remote Endpoint's trust must be verified before the From 863b38b5864f0546c4a76eab103784217fdb4ecf Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Mon, 15 Jan 2024 07:26:06 -0800 Subject: [PATCH 2/4] Update draft-ietf-taps-interface.md Co-authored-by: mwelzl --- draft-ietf-taps-interface.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/draft-ietf-taps-interface.md b/draft-ietf-taps-interface.md index 3d83ffb9..a2ac8cf0 100644 --- a/draft-ietf-taps-interface.md +++ b/draft-ietf-taps-interface.md @@ -1563,7 +1563,7 @@ This document specifies an abstract API, which could appear to conflict with the for security parameters to be unambiguous. The Transport Services System SHOULD provide reasonable, secure defaults for each enumerated security parameter, such that users of the system only need to specify parameters required to establish a secure connection -(e.g., `ServerCertificate`, `ClientCertificate`). Specifying specific security parameters +(e.g., `serverCertificate`, `clientCertificate`). Specifying security parameters from enumerated values (e.g., specific ciphersuites) might constrain the Transport Protocols that can be selected during connection establishment. From 57eb4ddaaf49c0b2fe6e82027be3e3da8238cbd1 Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Mon, 15 Jan 2024 07:27:07 -0800 Subject: [PATCH 3/4] Apply suggestions from code review Co-authored-by: mwelzl --- draft-ietf-taps-interface.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/draft-ietf-taps-interface.md b/draft-ietf-taps-interface.md index a2ac8cf0..bd0ce5a3 100644 --- a/draft-ietf-taps-interface.md +++ b/draft-ietf-taps-interface.md @@ -1564,10 +1564,10 @@ for security parameters to be unambiguous. The Transport Services System SHOULD secure defaults for each enumerated security parameter, such that users of the system only need to specify parameters required to establish a secure connection (e.g., `serverCertificate`, `clientCertificate`). Specifying security parameters -from enumerated values (e.g., specific ciphersuites) might constrain the Transport -Protocols that can be selected during connection establishment. +from enumerated values (e.g., specific ciphersuites) might constrain which transport +protocols can be selected during Connection establishment. -Security configuration parameters are specified in the pre-connection phase +Security configuration parameters are specified in the pre-establishment phase and are created as follows: ~~~ @@ -1587,12 +1587,12 @@ they support. For security parameters that are not simple value types, such as certificates and keys, implementations are responsible for exposing types appropriate for the platform / language environment. -Applications SHOULD use common safe defaults for values such as TLS ciphersuite +Applications SHOULD use common safe defaults for values such as TLS ciphersuites whenever possible. However, as discussed in {{?RFC8922}}, many transport security protocols require specific security parameters and constraints from the client at the time of configuration and actively during a handshake. -The set of security parameters defined here are not exhaustive, but illustrative. +The set of security parameters defined here is not exhaustive, but illustrative. Implementations SHOULD expose an equivalent to the parameters listed below to allow for sufficient configuration of security parameters, but the details are expected to vary based on platform and implementation constraints. From d53797f74ae1f1f648cd88e71ddb5d700e44e4a7 Mon Sep 17 00:00:00 2001 From: Tommy Pauly Date: Mon, 15 Jan 2024 07:27:38 -0800 Subject: [PATCH 4/4] Update draft-ietf-taps-interface.md Co-authored-by: mwelzl --- draft-ietf-taps-interface.md | 1 + 1 file changed, 1 insertion(+) diff --git a/draft-ietf-taps-interface.md b/draft-ietf-taps-interface.md index bd0ce5a3..6d057a50 100644 --- a/draft-ietf-taps-interface.md +++ b/draft-ietf-taps-interface.md @@ -1736,6 +1736,7 @@ out-of-band. Each instance of pre-shared keying material is associated with some that typically identifies its use or has some protocol-specific meaning to the Remote Endpoint. Note that use of a pre-shared key will tend to select a single security protocol, and therefore directly select a single underlying protocol stack. +A Transport Services API could express `None` in an environment-typical way, e.g., as a Union type or special value. ~~~ SecurityParameters.Set(preSharedKey, key, myIdentity)