From 9a7a1dec4e27012c804762bb79d4847ee7e23d2f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C3=A9ter=20Dimitrov?= Date: Wed, 20 Mar 2019 17:10:26 +0100 Subject: ssl: Update standards compliance Change-Id: I365965750e4b9747bf1fb8560f34afe6eecf7f02 --- lib/ssl/doc/src/Makefile | 1 + lib/ssl/doc/src/ssl_app.xml | 41 +- lib/ssl/doc/src/standards_compliance.xml | 2312 ++++++++++++++++++++++++++++++ lib/ssl/doc/src/usersguide.xml | 1 + 4 files changed, 2317 insertions(+), 38 deletions(-) create mode 100644 lib/ssl/doc/src/standards_compliance.xml (limited to 'lib/ssl/doc/src') diff --git a/lib/ssl/doc/src/Makefile b/lib/ssl/doc/src/Makefile index 7cf251d8f9..064131944c 100644 --- a/lib/ssl/doc/src/Makefile +++ b/lib/ssl/doc/src/Makefile @@ -47,6 +47,7 @@ XML_CHAPTER_FILES = \ ssl_protocol.xml \ using_ssl.xml \ ssl_distribution.xml \ + standards_compliance.xml \ notes.xml BOOK_FILES = book.xml diff --git a/lib/ssl/doc/src/ssl_app.xml b/lib/ssl/doc/src/ssl_app.xml index 893919aeb4..b05caf44ea 100644 --- a/lib/ssl/doc/src/ssl_app.xml +++ b/lib/ssl/doc/src/ssl_app.xml @@ -35,45 +35,10 @@

- The ssl application is an implementation of the SSL/TLS/DTLS protocol in Erlang. + The ssl application is an implementation of the SSL, TLS and DTLS protocols in Erlang.

- - Supported SSL/TLS/DTLS-versions are SSL-3.0, TLS-1.0, - TLS-1.1, TLS-1.2, DTLS-1.0 (based on TLS-1.1), DTLS-1.2 (based on TLS-1.2) - For security reasons SSL-2.0 is not supported. - Interoperability with SSL-2.0 enabled clients dropped. (OTP 21) - For security reasons SSL-3.0 is no longer supported by default, - but can be configured. (OTP 19) - For security reasons RSA key exchange cipher suites are no longer supported by default, - but can be configured. (OTP 21) - For security reasons DES cipher suites are no longer supported by default, - but can be configured. (OTP 20) - For security reasons 3DES cipher suites are no longer supported by default, - but can be configured. (OTP 21) - Renegotiation Indication Extension RFC 5746 is supported - - Ephemeral Diffie-Hellman cipher suites are supported, - but not Diffie Hellman Certificates cipher suites. - Elliptic Curve cipher suites are supported if the Crypto - application supports it and named curves are used. - - Export cipher suites are not supported as the - U.S. lifted its export restrictions in early 2000. - IDEA cipher suites are not supported as they have - become deprecated by the latest TLS specification so it is not - motivated to implement them. - Compression is not supported. - CRL validation is supported. - Policy certificate extensions are not supported. - 'Server Name Indication' extension - (RFC 6066) is supported. - Application Layer Protocol Negotiation (ALPN) and its successor Next Protocol Negotiation (NPN) - are supported. - It is possible to use Pre-Shared Key (PSK) and Secure Remote Password (SRP) - cipher suites, but they are not enabled by default. - - - +

For current statement of standards compliance see the User's Guide.

+
DEPENDENCIES diff --git a/lib/ssl/doc/src/standards_compliance.xml b/lib/ssl/doc/src/standards_compliance.xml new file mode 100644 index 0000000000..c20bab4e50 --- /dev/null +++ b/lib/ssl/doc/src/standards_compliance.xml @@ -0,0 +1,2312 @@ + + + + +
+ + 2015 + 2019 + Ericsson AB, All Rights Reserved + + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. + + The Initial Developer of the Original Code is Ericsson AB. + + + Standards Compliance + OTP team + + 2019-03-20 + A + standards_compliance.xml +
+ +
+ Purpose +

This section describes the current state of standards compliance of the ssl application.

+
+ +
+ Common (pre TLS 1.3) + + For security reasons RSA key exchange cipher suites are no longer supported by default, + but can be configured. (OTP 21) + + For security reasons DES cipher suites are no longer supported by default, + but can be configured. (OTP 20) + + For security reasons 3DES cipher suites are no longer supported by default, + but can be configured. (OTP 21) + + Renegotiation Indication Extension RFC 5746 is supported + + Ephemeral Diffie-Hellman cipher suites are supported, + but not Diffie Hellman Certificates cipher suites. + + Elliptic Curve cipher suites are supported if the Crypto + application supports it and named curves are used. + + Export cipher suites are not supported as the + U.S. lifted its export restrictions in early 2000. + + IDEA cipher suites are not supported as they have + become deprecated by the TLS 1.2 specification so it is not + motivated to implement them. + + Compression is not supported. + + +
+ +
+ Common + + CRL validation is supported. + Policy certificate extensions are not supported. + 'Server Name Indication' extension + (RFC 6066) is supported. + Application Layer Protocol Negotiation (ALPN) and its successor Next Protocol Negotiation (NPN) are supported. + It is possible to use Pre-Shared Key (PSK) and Secure Remote Password (SRP) + cipher suites, but they are not enabled by default. + + +
+ + +
+ SSL 2.0 +

For security reasons SSL-2.0 is not supported. Interoperability with SSL-2.0 enabled clients dropped. (OTP 21)

+
+ +
+ SSL 3.0 +

For security reasons SSL-3.0 is no longer supported by default, but can be configured. (OTP 19)

+
+ +
+ TLS 1.0 +

For security reasons TLS-1.0 is no longer supported by default, but can be configured. (OTP 22)

+
+ +
+ TLS 1.1 +

For security reasons TLS-1.1 is no longer supported by default, but can be configured. (OTP 22)

+
+ +
+ TLS 1.2 +

Supported

+
+ +
+ DTLS 1.0 +

For security reasons DTLS-1.0 (based on TLS 1.1) is no longer supported by default, but can be configured. (OTP 22)

+
+ +
+ DTLS 1.2 +

Supported (based on TLS 1.2)

+
+ +
+ DTLS 1.3 +

Not yet supported

+
+ +
+ TLS 1.3 +

This section describes the current state of standards compliance for TLS 1.3.

+

(C = Compliant, NC = Non-Compliant, P = Partially-Compliant, NA = Not Applicable)

+ + + Section + Feature + State + Since + + + + + + 1.3. Updates Affecting TLS 1.2 + + + + C + 22 + + + + Version downgrade protection mechanism + C + 22 + + + + RSASSA-PSS signature schemes + P + 22 + + + + supported_versions (ClientHello) extension + C + 22 + + + + signature_algorithms_cert extension + C + 22 + + + + + + 2. Protocol Overview + + + + P + 22 + + + + (EC)DHE + C + 22 + + + + PSK-only + NC + + + + + PSK with (EC)DHE + NC + + + + + + + 2.1. Incorrect DHE share + + + HelloRetryRequest + C + 22 + + + + + + 2.2. Resumption and Pre-Shared Key (PSK) + + + + NC + + + + + + + 2.3. 0-RTT Data + + + + NC + + + + + + + 4.1.1. Cryptographic Negotiation + + + + P + 22 + + + + supported_groups extension + C + + + + + signature_algorithms extension + C + + + + + pre_shared_key extension + NC + + + + + + + 4.1.2. Client Hello + + + Client + NC + + + + + server_name (RFC6066) + NC + + + + + max_fragment_length (RFC6066) + NC + + + + + status_request (RFC6066) + NC + + + + + supported_groups (RFC7919) + NC + + + + + signature_algorithms (RFC8446) + NC + + + + + use_srtp (RFC5764) + NC + + + + + heartbeat (RFC6520) + NC + + + + + application_layer_protocol_negotiation (RFC7301) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + client_certificate_type (RFC7250) + NC + + + + + server_certificate_type (RFC7250) + NC + + + + + padding (RFC7685) + NC + + + + + key_share (RFC8446) + NC + + + + + pre_shared_key (RFC8446) + NC + + + + + psk_key_exchange_modes (RFC8446) + NC + + + + + early_data (RFC8446) + NC + + + + + cookie (RFC8446) + NC + + + + + supported_versions (RFC8446) + NC + + + + + certificate_authorities (RFC8446) + NC + + + + + oid_filters (RFC8446) + NC + + + + + post_handshake_auth (RFC8446) + NC + + + + + signature_algorithms_cert (RFC8446) + NC + + + + + + Server + PC + 22 + + + + server_name (RFC6066) + NC + + + + + max_fragment_length (RFC6066) + NC + + + + + status_request (RFC6066) + NC + + + + + supported_groups (RFC7919) + C + 22 + + + + signature_algorithms (RFC8446) + C + 22 + + + + use_srtp (RFC5764) + NC + + + + + heartbeat (RFC6520) + NC + + + + + application_layer_protocol_negotiation (RFC7301) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + client_certificate_type (RFC7250) + NC + + + + + server_certificate_type (RFC7250) + NC + + + + + padding (RFC7685) + NC + + + + + key_share (RFC8446) + C + 22 + + + + pre_shared_key (RFC8446) + NC + + + + + psk_key_exchange_modes (RFC8446) + NC + + + + + early_data (RFC8446) + NC + + + + + cookie (RFC8446) + NC + + + + + supported_versions (RFC8446) + C + 22 + + + + certificate_authorities (RFC8446) + NC + + + + + oid_filters (RFC8446) + NC + + + + + post_handshake_auth (RFC8446) + NC + + + + + signature_algorithms_cert (RFC8446) + C + 22 + + + + + + 4.1.3. Server Hello + + + Client + NC + + + + + Version downgrade protection + NC + + + + + key_share (RFC8446) + NC + + + + + pre_shared_key (RFC8446) + NC + + + + + supported_versions (RFC8446) + NC + + + + + + Server + PC + 22 + + + + Version downgrade protection + C + 22 + + + + key_share (RFC8446) + C + 22 + + + + pre_shared_key (RFC8446) + NC + + + + + supported_versions (RFC8446) + C + 22 + + + + + + 4.1.4. Hello Retry Request + + + Server + PC + 22 + + + + key_share (RFC8446) + C + 22 + + + + cookie (RFC8446) + NC + + + + + supported_versions (RFC8446) + C + 22 + + + + + + 4.2.1. Supported Versions + + + Client + NC + + + + + Server + C + 22 + + + + + + 4.2.2. Cookie + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.3. Signature Algorithms + + + Client + NC + + + + + rsa_pkcs1_sha256 + NC + + + + + rsa_pkcs1_sha384 + NC + + + + + rsa_pkcs1_sha512 + NC + + + + + ecdsa_secp256r1_sha256 + NC + + + + + ecdsa_secp384r1_sha384 + NC + + + + + ecdsa_secp521r1_sha512 + NC + + + + + rsa_pss_rsae_sha256 + NC + + + + + rsa_pss_rsae_sha384 + NC + + + + + rsa_pss_rsae_sha512 + NC + + + + + ed25519 + NC + + + + + ed448 + NC + + + + + rsa_pss_pss_sha256 + NC + + + + + rsa_pss_pss_sha384 + NC + + + + + rsa_pss_pss_sha512 + NC + + + + + rsa_pkcs1_sha1 + NC + + + + + ecdsa_sha1 + NC + + + + + + Server + P + 22 + + + + rsa_pkcs1_sha256 + C + 22 + + + + rsa_pkcs1_sha384 + C + 22 + + + + rsa_pkcs1_sha512 + C + 22 + + + + ecdsa_secp256r1_sha256 + NC + + + + + ecdsa_secp384r1_sha384 + NC + + + + + ecdsa_secp521r1_sha512 + NC + + + + + rsa_pss_rsae_sha256 + C + 22 + + + + rsa_pss_rsae_sha384 + C + 22 + + + + rsa_pss_rsae_sha512 + C + 22 + + + + ed25519 + NC + + + + + ed448 + NC + + + + + rsa_pss_pss_sha256 + NC + + + + + rsa_pss_pss_sha384 + NC + + + + + rsa_pss_pss_sha512 + NC + + + + + rsa_pkcs1_sha1 + C + 22 + + + + ecdsa_sha1 + C + 22 + + + + + + 4.2.4. Certificate Authorities + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.5. OID Filters + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.6. Post-Handshake Client Authentication + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.7. Supported Groups + + + Client + NC + + + + + secp256r1 + NC + + + + + secp384r1 + NC + + + + + secp521r1 + NC + + + + + x25519 + NC + + + + + x448 + NC + + + + + ffdhe2048 + NC + + + + + ffdhe3072 + NC + + + + + ffdhe4096 + NC + + + + + ffdhe6144 + NC + + + + + ffdhe8192 + NC + + + + + + Server + C + 22 + + + + secp256r1 + C + 22 + + + + secp384r1 + C + 22 + + + + secp521r1 + C + 22 + + + + x25519 + C + 22 + + + + x448 + C + 22 + + + + ffdhe2048 + C + 22 + + + + ffdhe3072 + C + 22 + + + + ffdhe4096 + C + 22 + + + + ffdhe6144 + C + 22 + + + + ffdhe8192 + C + 22 + + + + + + 4.2.8. Key Share + + + Client + NC + + + + + Server + C + 22 + + + + + + 4.2.9. Pre-Shared Key Exchange Modes + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.10. Early Data Indication + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.11. Pre-Shared Key Extension + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.11.1. Ticket Age + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.11.2. PSK Binder + + + Client + NC + + + + + Server + NC + + + + + + + 4.2.11.3. Processing Order + + + Client + NC + + + + + Server + NC + + + + + + + 4.3.1. Encrypted Extensions + + + Client + NC + + + + + server_name (RFC6066) + NC + + + + + max_fragment_length (RFC6066) + NC + + + + + supported_groups (RFC7919) + NC + + + + + use_srtp (RFC5764) + NC + + + + + heartbeat (RFC6520) + NC + + + + + application_layer_protocol_negotiation (RFC7301) + NC + + + + + client_certificate_type (RFC7250) + NC + + + + + server_certificate_type (RFC7250) + NC + + + + + early_data (RFC8446) + NC + + + + + supported_versions (RFC8446) + NC + + + + + + Server + P + 22 + + + + server_name (RFC6066) + NC + + + + + max_fragment_length (RFC6066) + NC + + + + + supported_groups (RFC7919) + NC + + + + + use_srtp (RFC5764) + NC + + + + + heartbeat (RFC6520) + NC + + + + + application_layer_protocol_negotiation (RFC7301) + NC + + + + + client_certificate_type (RFC7250) + NC + + + + + server_certificate_type (RFC7250) + NC + + + + + early_data (RFC8446) + NC + + + + + supported_versions (RFC8446) + NC + + + + + + + 4.3.2. Certificate Request + + + Client + NC + + + + + status_request (RFC6066) + NC + + + + + signature_algorithms (RFC8446) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + certificate_authorities (RFC8446) + NC + + + + + oid_filters (RFC8446) + NC + + + + + signature_algorithms_cert (RFC8446) + NC + + + + + + Server + P + 22 + + + + status_request (RFC6066) + NC + + + + + signature_algorithms (RFC8446) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + certificate_authorities (RFC8446) + NC + + + + + oid_filters (RFC8446) + NC + + + + + signature_algorithms_cert (RFC8446) + NC + + + + + + + 4.4.1. The Transcript Hash + + + + C + 22 + + + + + + 4.4.2. Certificate + + + Client + NC + + + + + status_request (RFC6066) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + + Server + P + 22 + + + + status_request (RFC6066) + NC + + + + + signed_certificate_timestamp (RFC6962) + NC + + + + + + + 4.4.2.1. OCSP Status and SCT Extensions + + + Client + NC + + + + + Server + NC + + + + + + + 4.4.2.2. Server Certificate Selection + + + Client + NC + + + + + certificate type MUST be X.509v3 + NC + + + + + certificate's public key is compatible + NC + + + + + The certificate MUST allow the key to be used for signing + NC + + + + + server_name and certificate_authorities are used + NC + + + + + + Server + P + + + + + certificate type MUST be X.509v3 + C + 22 + + + + certificate's public key is compatible + C + 22 + + + + The certificate MUST allow the key to be used for signing + C + 22 + + + + server_name and certificate_authorities are used + NC + + + + + + + 4.4.2.3. Client Certificate Selection + + + + NC + + + + + + + 4.4.2.4. Receiving a Certificate Message + + + Client + NC + + + + + Server + C + 22 + + + + + + 4.4.3. Certificate Verify + + + Client + NC + + + + + Server + C + 22 + + + + + + 4.4.4. Finished + + + Client + NC + + + + + Server + C + 22 + + + + + + 4.5. End of Early Data + + + Client + NC + + + + + Server + NC + + + + + + + 4.6.1. New Session Ticket Message + + + Client + NC + + + + + early_data (RFC8446) + NC + + + + + + Server + NC + + + + + early_data (RFC8446) + NC + + + + + + + 4.6.2. Post-Handshake Authentication + + + Client + NC + + + + + Server + NC + + + + + + + 4.6.3. Key and Initialization Vector Update + + + Client + NC + + + + + Server + NC + + + + + + + 5.1. Record Layer + + + + C + 22 + + + + MUST NOT be interleaved with other record types + C + 22 + + + + MUST NOT span key changes + C + 22 + + + + MUST NOT send zero-length fragments + C + 22 + + + + Alert messages MUST NOT be fragmented + C + 22 + + + + + + 5.2. Record Payload Protection + + + + C + 22 + + + + + + 5.3. Per-Record Nonce + + + + C + 22 + + + + + + 5.4. Record Padding + + + + P + 22 + + + + MAY choose to pad + NC + + + + + MUST NOT send Handshake and Alert records that have a zero-length TLSInnerPlaintext.content + NC + + + + + The padding sent is automatically verified + C + 22 + + + + + + 5.5. Limits on Key Usage + + + + NC + + + + + + + 6.1. Closure Alerts + + + + NC + + + + + close_notify + NC + + + + + user_cancelled + NC + + + + + + + 6.2. Error Alerts + + + + PC + 22 + + + + + + 7.1. Key Schedule + + + + C + 22 + + + + + + 7.2. Updating Traffic Secrets + + + + C + 22 + + + + + + 7.3. Traffic Key Calculation + + + + C + 22 + + + + + + 7.5. Exporters + + + + NC + + + + + + + 8. 0-RTT and Anti-Replay + + + + NC + + + + + + + 8.1. Single-Use Tickets + + + + NC + + + + + + + 8.2. Client Hello Recording + + + + NC + + + + + + + 8.3. Freshness Checks + + + + NC + + + + + + + 9.1. Mandatory-to-Implement Cipher Suites + + + + P + 22 + + + + MUST implement the TLS_AES_128_GCM_SHA256 + C + 22 + + + + SHOULD implement the TLS_AES_256_GCM_SHA384 + C + 22 + + + + SHOULD implement the TLS_CHACHA20_POLY1305_SHA256 + NC + + + + + + Digital signatures + P + 22 + + + + MUST support rsa_pkcs1_sha256 (for certificates) + C + 22 + + + + MUST support rsa_pss_rsae_sha256 (for CertificateVerify and certificates) + C + 22 + + + + MUST support ecdsa_secp256r1_sha256 + NC + + + + + + Key Exchange + C + 22 + + + + MUST support key exchange with secp256r1 + C + 22 + + + + SHOULD support key exchange with X25519 + C + 22 + + + + + + 9.2. Mandatory-to-Implement Extensions + + + + P + 22 + + + + Supported Versions + C + 22 + + + + Cookie + NC + + + + + Signature Algorithms + C + 22 + + + + Signature Algorithms Certificate + C + 22 + + + + Negotiated Groups + C + 22 + + + + Key Share + C + 22 + + + + Server Name Indication + NC + + + + + + MUST send and use these extensions + C + 22 + + + + "supported_versions" is REQUIRED for ClientHello, ServerHello and HelloRetryRequest + PC + 22 + + + + "signature_algorithms" is REQUIRED for certificate authentication + C + 22 + + + + "supported_groups" is REQUIRED for ClientHello messages using (EC)DHE key exchange + C + 22 + + + + "key_share" is REQUIRED for (EC)DHE key exchange + C + 22 + + + + "pre_shared_key" is REQUIRED for PSK key agreement + NC + + + + + "psk_key_exchange_modes" is REQUIRED for PSK key agreement + NC + + + + + + TLS 1.3 ClientHello + NC + + + + + If not containing a "pre_shared_key" extension, it MUST contain both a "signature_algorithms" extension and a "supported_groups" extension. + NC + + + + + If containing a "supported_groups" extension, it MUST also contain a "key_share" extension, and vice versa. An empty KeyShare.client_shares vector is permitted. + NC + + + + + + TLS 1.3 ServerHello + P + 22 + + + + MUST support the use of the "server_name" extension + NC + + + + + + + 9.3. Protocol Invariants + + + + NC + + + + + MUST correctly handle extensible fields + NC + + + + + A client sending a ClientHello MUST support all parameters advertised in it. + NC + + + + + A middlebox which terminates a TLS connection MUST behave as a compliant TLS server + NA + + + + + A middlebox which forwards ClientHello parameters it does not understand MUST NOT process any messages beyond that ClientHello. + NA + + + + + + + B.4. Cipher Suites + + + + P + 22 + + + + TLS_AES_128_GCM_SHA256 + C + 22 + + + + TLS_AES_256_GCM_SHA384 + C + 22 + + + + TLS_CHACHA20_POLY1305_SHA256 + NC + + + + + TLS_AES_128_CCM_SHA256 + NC + + + + + TLS_AES_128_CCM_8_SHA256 + NC + + + + + + + C.1. Random Number Generation and Seeding + + + + C + 22 + + + + + + C.2. Certificates and Authentication + + + + C + 22 + + + + + + C.3. Implementation Pitfalls + + + + P + 22 + + + + + + C.4. Client Tracking Prevention + + + + NC + + + + + + + C.5. Unauthenticated Operation + + + + C + 22 + + + + + + D.1. Negotiating with an Older Server + + + + NC + + + + + + + D.2. Negotiating with an Older Client + + + + C + 22 + + + + + + D.3. 0-RTT Backward Compatibility + + + + NC + + + + + + + D.4. Middlebox Compatibility Mode + + + + P + 22 + + + + + + D.5. Security Restrictions Related to Backward Compatibility + + + + C + 22 + + + Standards Compliance +
+ +
+ + diff --git a/lib/ssl/doc/src/usersguide.xml b/lib/ssl/doc/src/usersguide.xml index 23ccf668c3..b22b2456e4 100644 --- a/lib/ssl/doc/src/usersguide.xml +++ b/lib/ssl/doc/src/usersguide.xml @@ -38,6 +38,7 @@ + -- cgit v1.2.3