Skip to content

NO-JIRA: update TLS security profile documentation for clarity and consistency #2595

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sanchezl wants to merge 2 commits into
base: master
Choose a base branch
from
Open

NO-JIRA: update TLS security profile documentation for clarity and consistency #2595

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
9f622cd
update TLS security profile documentation for clarity and consistency
sanchezl Nov 20, 2025
92bb14e
regenerate CRDs
sanchezl Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
152 changes: 55 additions & 97 deletions config/v1/types_tlssecurityprofile.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 "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 and want to 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 "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
// do not need backward compatibility for older clients.
//
// 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
Expand All @@ -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"
)

Expand All @@ -219,8 +174,6 @@ type TLSProfileSpec struct {
//
// minTLSVersion: VersionTLS11
//
// NOTE: currently the highest minTLSVersion allowed is VersionTLS12
//
MinTLSVersion TLSProtocolVersion `json:"minTLSVersion"`
}

Expand All @@ -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 include only
// valid entries and everything will be ok.
var TLSProfiles = map[TLSProfileType]*TLSProfileSpec{
TLSProfileOldType: {
Ciphers: []string{
Expand Down
Loading