proposal: crypto/tls: Profiles

[thatnealpatel]

crypto/tls: Profiles

tls.Config has a lot of knobs. Each allow for an extra dimension of configuration that places the burden of decision and maintenance on the user. Over time, we have moved towards reducing this surface area in pointed ways (#45430, #69393).

These changes brought us closer to a safe-by-default API; however, this still does not alleviate the N independent choices a user must make. Instead, a safe-by-default crypto/tls configuration API should express a posture over a precommitted universe of parameters, namely crypto/tls.Config.

In general, we should aim to provide useful defaults over the N-dimensional configuration space such that evolution does not conflict with language and ecosystem needs.

I propose we add TLS Profiles: named, opaque security configurations that define the maximal set of acceptable parameters for a connection. All existing Config fields continue to work; subsequent mutations of the Config cannot weaken the security posture given by active Profile.

This proposal explicitly makes no statements about the contents of each profile; where necessary, examples referencing parameters are illustrative only and do not reflect opinions about which profiles should contain which parameters. @FiloSottile will own a different proposal that addresses these points.

Profile Shape

type Config struct {
    // Profile describes the maximal set of parameters
    // that the Config is allowed to use; mutating any
    // fields within Config cannot weaken the properties
    // guaranteed by the Profile.
    Profile Profile

    // ... existing fields ...
}

// Profile describes a security posture that applies to
// all TLS connections. By definition, no operation is
// permitted to weaken the security properties of a Profile.
//
// [ProfileDefault] is safe-by-default, and it is recommended
// for use in most applications.
type Profile int

const (
    // ProfileDefault is the default profile safe for general purpose
    // use and can evolve with each Go release.
    ProfileDefault       Profile = iota

    // ProfileCompatibility includes a more permissive set of legacy
    // parameters that are generally discouraged for use outside 
    // of deployments with demonstrated interoperability needs.
    ProfileCompatibility

    // ProfileModern includes a more restrictive set of parameters
    // that generally foreshadow what future [ProfileDefault] might
    // look like.
    ProfileModern

    // ProfileFIPS140 exactly matches GODEBUG=fips140=on.
    ProfileFIPS140
)

Profiles guarantee a minimum security posture that is enforced at runtime. All knobs exposed by crypto/tls.Config can only intersect with a given Profile; unions are impossible by definition.

Profiles are not given version numbers. Their behavior and configuration are bound to the version of Go that is used to compile a given program. Any set of behaviors that can be expressed through a versioned Profile are equivalently expressible by narrowing the crypto/tls.Config beyond its default or application-selected Profile.

In addition to providing a safe-by-default TLS configuration, Profiles naturally provide a mechanism for quickly and safely disabling parameters that may be obsoleted by CRQCs.

For example, applications setting CurvePreferences today will, in effect, opt out of future PQ functionality. With Profiles, any such application will now be using ProfileDefault which provides PQ-inclusive parameters.

ProfileCompatibility replaces the accumulating non-feature GODEBUGs. Instead of knowing which combination of tlsrsakex=1, tls3des=1, tlssha1=1, and tls10server=1 you need, you select one profile which includes them all. If an application desires to further narrow this set to restore previous behavior, it may do so by setting the appropriate fields in Config.

Regarding X.509 certificates, profiles will narrow the set of acceptable certificates through their stated security posture similarly to how TLS 1.3 implies a set of invalid and valid X.509 certificates.

Somewhat notably, Profiles imply that session resumption can fail if a tightened server profile encounters a more relaxed client session. For example, a future release of Go may trigger a renegotiation of a session without application code changes. This behavior is considered to be working as intended under profiles.

Profiles are not made to be observable in ConnectionState.

Open Questions

• Further considerations about the behavior of X.509 certificates with Profiles?

/cc @FiloSottile @golang/security @golang/proposal-review

[mateusz834]

Sometimes we regret making such types int, instead of uint8, i don't think that this will be the case here, but just noting.

-type Profile int
+type Profile uint8

[thatnealpatel]

@mateusz834 Given >=16 floating profiles would be virtually self-defeating, uint8 sounds perfectly reasonable.

[kortschak]

If the Profile type were int8 (rather than the unsigned suggestion) and the const enumeration were

const (
    // ProfileCompatibility includes a more permissive set of legacy
    // parameters that are generally discouraged for use outside 
    // of deployments with demonstrated interoperability needs.
    ProfileCompatibility Profile = iota-1

    // ProfileDefault is the default profile safe for general purpose
    // use and can evolve with each Go release.
    ProfileDefault

...

Then we'd have the same safe default, but a nice property that the greater the Profile the more restrictive it would be.

@jfbus Structs cannot be consts.

[thatnealpatel]

@kortschak I do like the property as presented; however, Profiles are meant to be opaque.

We likely do not want to lock ourselves into a notion of "ordered by restrictiveness." This would in effect "leak" O(Profiles) internal details through ordering, whereas the safe-by-default zero-value only "leaks" O(1) of the internals.

I am open to being convinced otherwise.

[tmthrgd]

To stop people relying on the specific numeric values or doing math on them, perhaps it's better to make these completely opaque:

// Profile describes a security posture that applies to
// all TLS connections. By definition, no operation is
// permitted to weaken the security properties of a Profile.
//
// [ProfileDefault] is safe-by-default, and it is recommended
// for use in most applications.
type Profile struct { ... }

// ProfileDefault is the default profile safe for general purpose
// use and can evolve with each Go release.
//
// Multiple invocations of this function will return the same value, which can
// be used for equality checks and switch statements. The returned value is safe
// for concurrent use.
func ProfileDefault() Profile

// ProfileCompatibility includes a more permissive set of legacy
// parameters that are generally discouraged for use outside 
// of deployments with demonstrated interoperability needs.
//
// Multiple invocations of this function will return the same value, which can
// be used for equality checks and switch statements. The returned value is safe
// for concurrent use.
func ProfileCompatibility() Profile

// ProfileModern includes a more restrictive set of parameters
// that generally foreshadow what future [ProfileDefault] might
// look like.
//
// Multiple invocations of this function will return the same value, which can
// be used for equality checks and switch statements. The returned value is safe
// for concurrent use.
func ProfileModern() Profile

// ProfileFIPS140 exactly matches GODEBUG=fips140=on.
//
// Multiple invocations of this function will return the same value, which can
// be used for equality checks and switch statements. The returned value is safe
// for concurrent use.
func ProfileFIPS140() Profile

(Inspired by the API in #77626).

I'm sure somebody will serialise the values in a configuration file otherwise. Or try to +1 to a different profile.

[thatnealpatel]

@tmthrgd Thank you for raising this concern.

Initially, I sketched Profile as a struct; however,
I changed it due to the copy semantics of tls.Config.

I take your point that we do not want to allow arithmetic
with Profiles, for similar reasons contained in my comment
above yours. What if we instead made it:

type Profile string

What you sketched out is virtually what the internals
look like in my sketch implementation. I'm trying to
avoid leaking those internals.

[mateusz834]

Initially, I sketched Profile as a struct; however,
I changed it due to the copy semantics of tls.Config.

The struct can just have an internal enum inside, i don't see any drawback with such approach, but also i am fine with just uint8, since this is what we do most of the time.

FYI lets remember to have a:

func (Profile) String() string

[rbqvq]

I perfer returns a default security config, it allow user modify some fields.

---

Three designs:

• A default configs with profile

func ProfileCompatibility() *Config {
   return &tls.Config{...}
}

• A default configs for multi profile

type Profile func(cfg *Config)

func DefaultConfig(profiles ...Profile) *Config {
	cfg := new(Config)

	for profile := range profiles {
		profile(cfg)
	}

	return cfg
}

• Defaults option

In my fork stack:

// A Defaults structure is used to configure a TLS client or server defaults.
type Defaults struct {
	// By default, only the cipher suites used by the standard library are sent.
	// When true, all secure cipher suites will be sent, including locale-specific suites.
	// For suites deemed unsafe by the standard library, you still need to manually add them.
	AllSecureCipherSuites bool

	// By default, only the curves used by the standard library are sent.
	// When true, all secure curves will be sent.
	AllSecureCurves bool

	// For client:
	// By default, only the extensions used by the standard library are sent.
	// When true, If features was enabled, the extension will be sent.
	//
	// For server:
	// If features was enabled and offered by client, the extension will be sent.
	// So this option
	AllSupportedExtensions bool
}

func (c *Config) curvePreferences(version uint16) []CurveID {
	var curvePreferences []CurveID
	if len(c.CurvePreferences) != 0 {
		curvePreferences = slices.Clone(c.CurvePreferences)
	} else if c.Defaults.AllSecureCurves {
		curvePreferences = fullCurvePreferences()
	} else {
		curvePreferences = defaultCurvePreferences()
	}
	if version < VersionTLS13 {
		curvePreferences = slices.DeleteFunc(curvePreferences, isTLS13OnlyKeyExchange)
	}
	return curvePreferences
}

For std:

package main

type Mode uint8

const (
	ModeUnset Mode = iota
	ModeDefault
	ModeModern
	ModeCompatibility
	...
)

// A Defaults structure is used to configure a TLS client or server defaults.
type Defaults struct {
	// if other fields are ModeUnset, Default will as default baseline
	// Otherwise the specialed mode will override it.
	Default      Mode
	CipherSuites Mode
	Curves       Mode
	...
}

func (c *Config) curvePreferences(version uint16) []CurveID {
	var curvePreferences []CurveID
	if len(c.CurvePreferences) != 0 {
		curvePreferences = slices.Clone(c.CurvePreferences)
	} else {
		switch c.Defaults.Curves {
		case ModeUnset, ModeDefault:
			curvePreferences = defaultCurvePreferences()
		}
	}
	if version < VersionTLS13 {
		curvePreferences = slices.DeleteFunc(curvePreferences, isTLS13OnlyKeyExchange)
	}
	return curvePreferences
}

---

Hybrid these deisng also good.

func ProfileMutualAuthentication(cfg *Config) {
	cfg.DisableSessionTicket = true
}

func ProfileServer(cfg *Config) {
	cfg.Defaults.Default = ModeCompatibility
}

func ProfileClient(cfg *Config) {
	cfg.Defaults.Default = ModeDefault
}

---

Configurations are always diverse. For compatibility configuration files, most users need RSA KEX, but not necessarily TLS 1.0. Most users probably only want to compromise a little on compatibility for strict configurations, not all of them.

The end result is that besides having one more field, everyone still has to write a bunch of other fields.

Secure by Default is not Secure by Force, Profile is not Policy

If this proposal is called Policy, I fully support it. Of course, I suggest that we provide a set of default values to replace GODEBUG.

I don't think forcibly overriding fields explicitly configured by the user is a good idea.

"We are hackers. We don't need some toys that are safe for children." -
szmcdull

"We (i.e. the Linux kernel CVE team) have NO IDEA HOW LINUX IS USED, nor does any other open source project, and as such, can not assign CVSS scores reliably to any of our CVE entries. It's all up to the user who takes our code and does something with it to be able to properly decide this." - Greg-KH

---

Additionally, Profile might conflict with this proposal (#75086).

[qmuntal]

I would want to change TLS profile without changing source code. The same binary might run on different contexts that have their own compatibility/policy requirements, and the easiest way to achieve it would be changing an environment variable, e.g. a GODEBUG setting.

I propose extending this proposal to also allow setting TLS profiles using a new inmutable GODEBUG, let's call it tlsprofile, which would be used like GODEBUG=tlsprofile=compatibity. This setting would override any TLS profile set in source code. All the other TLS profile rules apply.

[mateusz834]

This setting would override any TLS profile set in source code

Potentially only if Profile is unset i.e. ProfileDefault?

[thatnealpatel]

@mateusz834 My read of @qmuntal's comment is that GODEBUG=tlsprofile=X overrides unconditionally; for example, if a large set of deployments use ProfileDefault or ProfileCompatibility in source, you would likely not want to edit source code where you otherwise previously would not have. In this case, you can use GODEBUG=tlsprofile=modern to unconditionally specify that to meet an organizational compliance requirement.

This looks quite similarly in form (not function) to the GODEBUG=fips140=X. If I am not mistaken, this does not change the scope or intentions of this proposal; it simply provides a way to configure the same Profiles behavior without modifying source.