Skip to content

Commit 9819d5e

Browse files
committed
Add TLSMaxVersion, TLSCipherSuites, and TLSCurvePreferences to webhook.Options for enhanced TLS control
1 parent 9cc8410 commit 9819d5e

3 files changed

Lines changed: 317 additions & 1 deletion

File tree

‎webhook/README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -78,6 +78,149 @@ func main() {
7878
There is also a config map validation admission controller built in under
7979
`knative.dev/pkg/webhook/configmaps`.
8080

81+
## TLS Configuration
82+
83+
The webhook server supports configuring TLS parameters through the `webhook.Options` struct. This allows you to control the TLS version, cipher suites, and elliptic curve preferences for enhanced security.
84+
85+
### Available TLS Options
86+
87+
```go
88+
type Options struct {
89+
// ... other fields ...
90+
91+
// TLSMinVersion contains the minimum TLS version that is acceptable.
92+
// Default is TLS 1.3 if not specified.
93+
// Supported values: tls.VersionTLS12, tls.VersionTLS13
94+
TLSMinVersion uint16
95+
96+
// TLSMaxVersion contains the maximum TLS version that is acceptable.
97+
// If not set (0), the maximum version supported by the implementation will be used.
98+
// Useful for enforcing Modern profile (TLS 1.3 only) by setting both
99+
// TLSMinVersion and TLSMaxVersion to tls.VersionTLS13.
100+
TLSMaxVersion uint16
101+
102+
// TLSCipherSuites specifies the list of enabled cipher suites.
103+
// If empty, a default list of secure cipher suites will be used.
104+
// Note: Cipher suites are not configurable in TLS 1.3; they are
105+
// determined by the implementation.
106+
TLSCipherSuites []uint16
107+
108+
// TLSCurvePreferences specifies the elliptic curves that will be used
109+
// in an ECDHE handshake. If empty, the default curves will be used.
110+
TLSCurvePreferences []tls.CurveID
111+
}
112+
```
113+
114+
### Environment Variable Configuration
115+
116+
You can also configure the minimum TLS version via the `WEBHOOK_TLS_MIN_VERSION` environment variable:
117+
118+
```yaml
119+
env:
120+
- name: WEBHOOK_TLS_MIN_VERSION
121+
value: "1.3" # or "1.2"
122+
```
123+
124+
### Usage Examples
125+
126+
#### Example 1: Default Configuration (Recommended)
127+
128+
By default, the webhook uses TLS 1.3 as the minimum version with secure defaults:
129+
130+
```go
131+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
132+
ServiceName: "webhook",
133+
Port: 8443,
134+
SecretName: "webhook-certs",
135+
// TLS defaults: MinVersion=1.3, secure cipher suites and curves
136+
})
137+
```
138+
139+
#### Example 2: Modern Profile (TLS 1.3 Only)
140+
141+
To enforce TLS 1.3 only (highest security profile):
142+
143+
```go
144+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
145+
ServiceName: "webhook",
146+
Port: 8443,
147+
SecretName: "webhook-certs",
148+
TLSMinVersion: tls.VersionTLS13,
149+
TLSMaxVersion: tls.VersionTLS13, // Enforce TLS 1.3 only
150+
})
151+
```
152+
153+
#### Example 3: Intermediate Profile (TLS 1.2+)
154+
155+
For broader compatibility while maintaining security:
156+
157+
```go
158+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
159+
ServiceName: "webhook",
160+
Port: 8443,
161+
SecretName: "webhook-certs",
162+
TLSMinVersion: tls.VersionTLS12,
163+
})
164+
```
165+
166+
#### Example 4: Custom Cipher Suites
167+
168+
To specify custom cipher suites (for TLS 1.2):
169+
170+
```go
171+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
172+
ServiceName: "webhook",
173+
Port: 8443,
174+
SecretName: "webhook-certs",
175+
TLSMinVersion: tls.VersionTLS12,
176+
TLSCipherSuites: []uint16{
177+
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
178+
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
179+
tls.TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256,
180+
tls.TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,
181+
},
182+
})
183+
```
184+
185+
#### Example 5: Custom Elliptic Curves
186+
187+
To specify elliptic curve preferences:
188+
189+
```go
190+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
191+
ServiceName: "webhook",
192+
Port: 8443,
193+
SecretName: "webhook-certs",
194+
TLSCurvePreferences: []tls.CurveID{
195+
tls.X25519, // Preferred
196+
tls.CurveP256,
197+
tls.CurveP384,
198+
},
199+
})
200+
```
201+
202+
#### Example 6: Complete Custom Configuration
203+
204+
For full control over TLS parameters:
205+
206+
```go
207+
ctx := webhook.WithOptions(signals.NewContext(), webhook.Options{
208+
ServiceName: "webhook",
209+
Port: 8443,
210+
SecretName: "webhook-certs",
211+
TLSMinVersion: tls.VersionTLS12,
212+
TLSMaxVersion: tls.VersionTLS13,
213+
TLSCipherSuites: []uint16{
214+
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
215+
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
216+
},
217+
TLSCurvePreferences: []tls.CurveID{
218+
tls.X25519,
219+
tls.CurveP256,
220+
},
221+
})
222+
```
223+
81224
## Writing new Admission Controllers
82225

83226
To implement your own admission controller akin to the resource defaulting and

‎webhook/webhook.go‎

Lines changed: 19 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,21 @@ type Options struct {
5252
// TLS 1.3 is the minimum version if not specified otherwise.
5353
TLSMinVersion uint16
5454

55+
// TLSMaxVersion contains the maximum TLS version that is acceptable.
56+
// If not set (0), the maximum version supported by the implementation will be used.
57+
// This is useful for enforcing Modern profile (TLS 1.3 only) by setting both
58+
// TLSMinVersion and TLSMaxVersion to tls.VersionTLS13.
59+
TLSMaxVersion uint16
60+
61+
// TLSCipherSuites specifies the list of enabled cipher suites.
62+
// If empty, a default list of secure cipher suites will be used.
63+
// Note: Cipher suites are not configurable in TLS 1.3; they are determined by the implementation.
64+
TLSCipherSuites []uint16
65+
66+
// TLSCurvePreferences specifies the elliptic curves that will be used in an ECDHE handshake.
67+
// If empty, the default curves will be used.
68+
TLSCurvePreferences []tls.CurveID
69+
5570
// ServiceName is the service name of the webhook.
5671
ServiceName string
5772

@@ -191,7 +206,10 @@ func New(
191206

192207
//nolint:gosec // operator configures TLS min version (default is 1.3)
193208
webhook.tlsConfig = &tls.Config{
194-
MinVersion: opts.TLSMinVersion,
209+
MinVersion: opts.TLSMinVersion,
210+
MaxVersion: opts.TLSMaxVersion,
211+
CipherSuites: opts.TLSCipherSuites,
212+
CurvePreferences: opts.TLSCurvePreferences,
195213

196214
// If we return (nil, error) the client sees - 'tls: internal error"
197215
// If we return (nil, nil) the client sees - 'tls: no certificates configured'

‎webhook/webhook_test.go‎

Lines changed: 155 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -124,3 +124,158 @@ func TestTLSMinVersionWebhookOption(t *testing.T) {
124124
}
125125
})
126126
}
127+
128+
func TestTLSMaxVersionWebhookOption(t *testing.T) {
129+
opts := newDefaultOptions()
130+
t.Run("when TLSMaxVersion is not configured, default is used", func(t *testing.T) {
131+
wh, err := newAdmissionControllerWebhook(t, opts)
132+
if err != nil {
133+
t.Fatal("Unexpected error", err)
134+
}
135+
136+
if wh.tlsConfig != nil && wh.tlsConfig.MaxVersion != 0 {
137+
t.Errorf("Expected MaxVersion to be 0 (default), got %d", wh.tlsConfig.MaxVersion)
138+
}
139+
})
140+
t.Run("when TLSMaxVersion is configured to TLS 1.3", func(t *testing.T) {
141+
opts.TLSMaxVersion = tls.VersionTLS13
142+
wh, err := newAdmissionControllerWebhook(t, opts)
143+
if err != nil {
144+
t.Fatal("Unexpected error", err)
145+
}
146+
if wh.tlsConfig == nil {
147+
t.Fatal("Expected tlsConfig to be set")
148+
}
149+
if wh.tlsConfig.MaxVersion != tls.VersionTLS13 {
150+
t.Errorf("Expected MaxVersion to be TLS 1.3, got %d", wh.tlsConfig.MaxVersion)
151+
}
152+
})
153+
t.Run("when both TLSMinVersion and TLSMaxVersion are TLS 1.3 (Modern profile)", func(t *testing.T) {
154+
opts.TLSMinVersion = tls.VersionTLS13
155+
opts.TLSMaxVersion = tls.VersionTLS13
156+
wh, err := newAdmissionControllerWebhook(t, opts)
157+
if err != nil {
158+
t.Fatal("Unexpected error", err)
159+
}
160+
if wh.tlsConfig == nil {
161+
t.Fatal("Expected tlsConfig to be set")
162+
}
163+
if wh.tlsConfig.MinVersion != tls.VersionTLS13 {
164+
t.Errorf("Expected MinVersion to be TLS 1.3, got %d", wh.tlsConfig.MinVersion)
165+
}
166+
if wh.tlsConfig.MaxVersion != tls.VersionTLS13 {
167+
t.Errorf("Expected MaxVersion to be TLS 1.3, got %d", wh.tlsConfig.MaxVersion)
168+
}
169+
})
170+
}
171+
172+
func TestTLSCipherSuitesWebhookOption(t *testing.T) {
173+
opts := newDefaultOptions()
174+
t.Run("when TLSCipherSuites is not configured", func(t *testing.T) {
175+
wh, err := newAdmissionControllerWebhook(t, opts)
176+
if err != nil {
177+
t.Fatal("Unexpected error", err)
178+
}
179+
180+
if wh.tlsConfig != nil && wh.tlsConfig.CipherSuites != nil {
181+
t.Errorf("Expected CipherSuites to be nil (default), got %v", wh.tlsConfig.CipherSuites)
182+
}
183+
})
184+
t.Run("when TLSCipherSuites is configured with specific ciphers", func(t *testing.T) {
185+
expectedCiphers := []uint16{
186+
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
187+
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
188+
}
189+
opts.TLSCipherSuites = expectedCiphers
190+
wh, err := newAdmissionControllerWebhook(t, opts)
191+
if err != nil {
192+
t.Fatal("Unexpected error", err)
193+
}
194+
if wh.tlsConfig == nil {
195+
t.Fatal("Expected tlsConfig to be set")
196+
}
197+
if len(wh.tlsConfig.CipherSuites) != len(expectedCiphers) {
198+
t.Errorf("Expected %d cipher suites, got %d", len(expectedCiphers), len(wh.tlsConfig.CipherSuites))
199+
}
200+
for i, cipher := range expectedCiphers {
201+
if wh.tlsConfig.CipherSuites[i] != cipher {
202+
t.Errorf("Expected cipher suite at index %d to be %d, got %d", i, cipher, wh.tlsConfig.CipherSuites[i])
203+
}
204+
}
205+
})
206+
}
207+
208+
func TestTLSCurvePreferencesWebhookOption(t *testing.T) {
209+
opts := newDefaultOptions()
210+
t.Run("when TLSCurvePreferences is not configured", func(t *testing.T) {
211+
wh, err := newAdmissionControllerWebhook(t, opts)
212+
if err != nil {
213+
t.Fatal("Unexpected error", err)
214+
}
215+
216+
if wh.tlsConfig != nil && wh.tlsConfig.CurvePreferences != nil {
217+
t.Errorf("Expected CurvePreferences to be nil (default), got %v", wh.tlsConfig.CurvePreferences)
218+
}
219+
})
220+
t.Run("when TLSCurvePreferences is configured with specific curves", func(t *testing.T) {
221+
expectedCurves := []tls.CurveID{
222+
tls.CurveP256,
223+
tls.CurveP384,
224+
tls.X25519,
225+
}
226+
opts.TLSCurvePreferences = expectedCurves
227+
wh, err := newAdmissionControllerWebhook(t, opts)
228+
if err != nil {
229+
t.Fatal("Unexpected error", err)
230+
}
231+
if wh.tlsConfig == nil {
232+
t.Fatal("Expected tlsConfig to be set")
233+
}
234+
if len(wh.tlsConfig.CurvePreferences) != len(expectedCurves) {
235+
t.Errorf("Expected %d curve preferences, got %d", len(expectedCurves), len(wh.tlsConfig.CurvePreferences))
236+
}
237+
for i, curve := range expectedCurves {
238+
if wh.tlsConfig.CurvePreferences[i] != curve {
239+
t.Errorf("Expected curve at index %d to be %d, got %d", i, curve, wh.tlsConfig.CurvePreferences[i])
240+
}
241+
}
242+
})
243+
}
244+
245+
func TestTLSConfigCombinedOptions(t *testing.T) {
246+
opts := newDefaultOptions()
247+
t.Run("when all TLS options are configured together", func(t *testing.T) {
248+
opts.TLSMinVersion = tls.VersionTLS12
249+
opts.TLSMaxVersion = tls.VersionTLS13
250+
opts.TLSCipherSuites = []uint16{
251+
tls.TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
252+
tls.TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
253+
}
254+
opts.TLSCurvePreferences = []tls.CurveID{
255+
tls.CurveP256,
256+
tls.X25519,
257+
}
258+
259+
wh, err := newAdmissionControllerWebhook(t, opts)
260+
if err != nil {
261+
t.Fatal("Unexpected error", err)
262+
}
263+
264+
if wh.tlsConfig == nil {
265+
t.Fatal("Expected tlsConfig to be set")
266+
}
267+
268+
if wh.tlsConfig.MinVersion != tls.VersionTLS12 {
269+
t.Errorf("Expected MinVersion to be TLS 1.2, got %d", wh.tlsConfig.MinVersion)
270+
}
271+
if wh.tlsConfig.MaxVersion != tls.VersionTLS13 {
272+
t.Errorf("Expected MaxVersion to be TLS 1.3, got %d", wh.tlsConfig.MaxVersion)
273+
}
274+
if len(wh.tlsConfig.CipherSuites) != 2 {
275+
t.Errorf("Expected 2 cipher suites, got %d", len(wh.tlsConfig.CipherSuites))
276+
}
277+
if len(wh.tlsConfig.CurvePreferences) != 2 {
278+
t.Errorf("Expected 2 curve preferences, got %d", len(wh.tlsConfig.CurvePreferences))
279+
}
280+
})
281+
}

0 commit comments

Comments
 (0)