update TLS security profile documentation for clarity and consistency

Author: sanchezl

config/v1/types_tlssecurityprofile.go

@@ -4,178 +4,130 @@ package v1
 // is used by operators to apply TLS security settings to operands.
 // +union
 type TLSSecurityProfile struct {
-	// type is one of Old, Intermediate, Modern or Custom. Custom provides
-	// the ability to specify individual TLS security profile parameters.
-	// Old, Intermediate and Modern are TLS security profiles based on:
+	// type is one of Old, Intermediate, Modern or Custom. Custom provides the
+	// ability to specify individual TLS security profile parameters.
 	//
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations
+	// The profiles are currently based on version 5.0 of the Mozilla Server Side TLS
+	// configuration guidelines (released 2019-06-28) with TLS 1.3 ciphers added for
+	// forward compatibility. See: https://ssl-config.mozilla.org/guidelines/5.0.json
 	//
-	// The profiles are intent based, so they may change over time as new ciphers are developed and existing ciphers
-	// are found to be insecure.  Depending on precisely which ciphers are available to a process, the list may be
-	// reduced.
-	//
-	// Note that the Modern profile is currently not supported because it is not
-	// yet well adopted by common software libraries.
+	// The profiles are intent based, so they may change over time as new ciphers are
+	// developed and existing ciphers are found to be insecure. Depending on
+	// precisely which ciphers are available to a process, the list may be reduced.
 	//
 	// +unionDiscriminator
 	// +optional
 	Type TLSProfileType `json:"type"`
-	// old is a TLS security profile based on:
-	//
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility
+
+	// old is a TLS profile for use when services need to be accessed by very old
+	// clients or libraries and should be used only as a last resort.
 	//
-	// and looks like this (yaml):
+	// The cipher list includes TLS 1.3 ciphers for forward compatibility, followed by
+	// the Mozilla 5.0 "old" profile ciphers.
 	//
+	// This profile is equivalent to a Custom profile specified as:
+	//   minTLSVersion: VersionTLS10
 	//   ciphers:
-	//
 	//     - TLS_AES_128_GCM_SHA256
-	//
 	//     - TLS_AES_256_GCM_SHA384
-	//
 	//     - TLS_CHACHA20_POLY1305_SHA256
-	//
 	//     - ECDHE-ECDSA-AES128-GCM-SHA256
-	//
 	//     - ECDHE-RSA-AES128-GCM-SHA256
-	//
 	//     - ECDHE-ECDSA-AES256-GCM-SHA384
-	//
 	//     - ECDHE-RSA-AES256-GCM-SHA384
-	//
 	//     - ECDHE-ECDSA-CHACHA20-POLY1305
-	//
 	//     - ECDHE-RSA-CHACHA20-POLY1305
-	//
 	//     - DHE-RSA-AES128-GCM-SHA256
-	//
 	//     - DHE-RSA-AES256-GCM-SHA384
-	//
 	//     - DHE-RSA-CHACHA20-POLY1305
-	//
 	//     - ECDHE-ECDSA-AES128-SHA256
-	//
 	//     - ECDHE-RSA-AES128-SHA256
-	//
 	//     - ECDHE-ECDSA-AES128-SHA
-	//
 	//     - ECDHE-RSA-AES128-SHA
-	//
 	//     - ECDHE-ECDSA-AES256-SHA384
-	//
 	//     - ECDHE-RSA-AES256-SHA384
-	//
 	//     - ECDHE-ECDSA-AES256-SHA
-	//
 	//     - ECDHE-RSA-AES256-SHA
-	//
 	//     - DHE-RSA-AES128-SHA256
-	//
 	//     - DHE-RSA-AES256-SHA256
-	//
 	//     - AES128-GCM-SHA256
-	//
 	//     - AES256-GCM-SHA384
-	//
 	//     - AES128-SHA256
-	//
 	//     - AES256-SHA256
-	//
 	//     - AES128-SHA
-	//
 	//     - AES256-SHA
-	//
 	//     - DES-CBC3-SHA
 	//
-	//   minTLSVersion: VersionTLS10
-	//
 	// +optional
 	// +nullable
 	Old *OldTLSProfile `json:"old,omitempty"`
-	// intermediate is a TLS security profile based on:
-	//
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28recommended.29
+
+	// intermediate is a TLS profile for use when you do not need compatibility with
+	// legacy clients such as Windows XP or old versions of OpenSSL and want remain
+	// highly secure while being compatible with most clients currently in use.
 	//
-	// and looks like this (yaml):
+	// The cipher list includes TLS 1.3 ciphers for forward compatibility, followed by
+	// the Mozilla 5.0 "intermediate" profile ciphers.
 	//
+	// This profile is equivalent to a Custom profile specified as:
+	//   minTLSVersion: VersionTLS12
 	//   ciphers:
-	//
 	//     - TLS_AES_128_GCM_SHA256
-	//
 	//     - TLS_AES_256_GCM_SHA384
-	//
 	//     - TLS_CHACHA20_POLY1305_SHA256
-	//
 	//     - ECDHE-ECDSA-AES128-GCM-SHA256
-	//
 	//     - ECDHE-RSA-AES128-GCM-SHA256
-	//
 	//     - ECDHE-ECDSA-AES256-GCM-SHA384
-	//
 	//     - ECDHE-RSA-AES256-GCM-SHA384
-	//
 	//     - ECDHE-ECDSA-CHACHA20-POLY1305
-	//
 	//     - ECDHE-RSA-CHACHA20-POLY1305
-	//
 	//     - DHE-RSA-AES128-GCM-SHA256
-	//
 	//     - DHE-RSA-AES256-GCM-SHA384
 	//
-	//   minTLSVersion: VersionTLS12
-	//
 	// +optional
 	// +nullable
 	Intermediate *IntermediateTLSProfile `json:"intermediate,omitempty"`
-	// modern is a TLS security profile based on:
-	//
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility
-	//
-	// and looks like this (yaml):
+
+	// modern is a TLS security profile for use with clients that support TLS 1.3 and
+	// don't need backward compatibility.
 	//
+	// This profile is equivalent to a Custom profile specified as:
+	//   minTLSVersion: VersionTLS13
 	//   ciphers:
-	//
 	//     - TLS_AES_128_GCM_SHA256
-	//
 	//     - TLS_AES_256_GCM_SHA384
-	//
 	//     - TLS_CHACHA20_POLY1305_SHA256
 	//
-	//   minTLSVersion: VersionTLS13
-	//
 	// +optional
 	// +nullable
 	Modern *ModernTLSProfile `json:"modern,omitempty"`
+
 	// custom is a user-defined TLS security profile. Be extremely careful using a custom
 	// profile as invalid configurations can be catastrophic. An example custom profile
 	// looks like this:
 	//
+	//   minTLSVersion: VersionTLS11
 	//   ciphers:
-	//
 	//     - ECDHE-ECDSA-CHACHA20-POLY1305
-	//
 	//     - ECDHE-RSA-CHACHA20-POLY1305
-	//
 	//     - ECDHE-RSA-AES128-GCM-SHA256
-	//
 	//     - ECDHE-ECDSA-AES128-GCM-SHA256
 	//
-	//   minTLSVersion: VersionTLS11
-	//
 	// +optional
 	// +nullable
 	Custom *CustomTLSProfile `json:"custom,omitempty"`
 }
 
-// OldTLSProfile is a TLS security profile based on:
-// https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility
+// OldTLSProfile is a TLS security profile based on the "old" configuration of
+// the Mozilla Server Side TLS configuration guidelines.
 type OldTLSProfile struct{}
 
-// IntermediateTLSProfile is a TLS security profile based on:
-// https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29
+// IntermediateTLSProfile is a TLS security profile based on the "intermediate"
+// configuration of the Mozilla Server Side TLS configuration guidelines.
 type IntermediateTLSProfile struct{}
 
-// ModernTLSProfile is a TLS security profile based on:
-// https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility
+// ModernTLSProfile is a TLS security profile based on the "modern" configuration
+// of the Mozilla Server Side TLS configuration guidelines.
 type ModernTLSProfile struct{}
 
 // CustomTLSProfile is a user-defined TLS security profile. Be extremely careful
@@ -189,16 +141,19 @@ type CustomTLSProfile struct {
 type TLSProfileType string
 
 const (
-	// Old is a TLS security profile based on:
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Old_backward_compatibility
+	// TLSProfileOldType sets parameters based on the "old" configuration of
+	// the Mozilla Server Side TLS configuration guidelines.
 	TLSProfileOldType TLSProfileType = "Old"
-	// Intermediate is a TLS security profile based on:
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Intermediate_compatibility_.28default.29
+
+	// TLSProfileIntermediateType sets parameters based on the "intermediate"
+	// configuration of the Mozilla Server Side TLS configuration guidelines.
 	TLSProfileIntermediateType TLSProfileType = "Intermediate"
-	// Modern is a TLS security profile based on:
-	// https://wiki.mozilla.org/Security/Server_Side_TLS#Modern_compatibility
+
+	// TLSProfileModernType sets parameters based on the "modern" configuration
+	// of the Mozilla Server Side TLS configuration guidelines.
 	TLSProfileModernType TLSProfileType = "Modern"
-	// Custom is a TLS security profile that allows for user-defined parameters.
+
+	// TLSProfileCustomType is a TLS security profile that allows for user-defined parameters.
 	TLSProfileCustomType TLSProfileType = "Custom"
 )
 
@@ -219,8 +174,6 @@ type TLSProfileSpec struct {
 	//
 	//   minTLSVersion: VersionTLS11
 	//
-	// NOTE: currently the highest minTLSVersion allowed is VersionTLS12
-	//
 	MinTLSVersion TLSProtocolVersion `json:"minTLSVersion"`
 }
 
@@ -245,11 +198,16 @@ const (
 	VersionTLS13 TLSProtocolVersion = "VersionTLS13"
 )
 
-// TLSProfiles Contains a map of TLSProfileType names to TLSProfileSpec.
+// TLSProfiles contains a map of TLSProfileType names to TLSProfileSpec.
+//
+// These profiles are based on version 5.0 of the Mozilla Server Side TLS
+// configuration guidelines (2019-06-28) with TLS 1.3 cipher suites prepended for
+// forward compatibility. See: https://ssl-config.mozilla.org/guidelines/5.0.json
 //
-// NOTE: The caller needs to make sure to check that these constants are valid for their binary. Not all
-// entries map to values for all binaries.  In the case of ties, the kube-apiserver wins.  Do not fail,
-// just be sure to whitelist only and everything will be ok.
+// NOTE: The caller needs to make sure to check that these constants are valid
+// for their binary. Not all entries map to values for all binaries. In the case
+// of ties, the kube-apiserver wins. Do not fail, just be sure to whitelist only
+// and everything will be ok.
 var TLSProfiles = map[TLSProfileType]*TLSProfileSpec{
 	TLSProfileOldType: {
 		Ciphers: []string{