| 1 |
/* |
| 2 |
Copyright 2014 The Kubernetes Authors. |
| 3 |
|
| 4 |
Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 |
you may not use this file except in compliance with the License. |
| 6 |
You may obtain a copy of the License at |
| 7 |
|
| 8 |
http://www.apache.org/licenses/LICENSE-2.0 |
| 9 |
|
| 10 |
Unless required by applicable law or agreed to in writing, software |
| 11 |
distributed under the License is distributed on an "AS IS" BASIS, |
| 12 |
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 |
See the License for the specific language governing permissions and |
| 14 |
limitations under the License. |
| 15 |
*/ |
| 16 |
|
| 17 |
package x509 |
| 18 |
|
| 19 |
import ( |
| 20 |
"crypto/sha256" |
| 21 |
"crypto/x509" |
| 22 |
"crypto/x509/pkix" |
| 23 |
"encoding/hex" |
| 24 |
"errors" |
| 25 |
"fmt" |
| 26 |
"net/http" |
| 27 |
"strings" |
| 28 |
"time" |
| 29 |
|
| 30 |
asn1util "k8s.io/apimachinery/pkg/apis/asn1" |
| 31 |
utilerrors "k8s.io/apimachinery/pkg/util/errors" |
| 32 |
"k8s.io/apimachinery/pkg/util/sets" |
| 33 |
"k8s.io/apiserver/pkg/authentication/authenticator" |
| 34 |
"k8s.io/apiserver/pkg/authentication/user" |
| 35 |
"k8s.io/apiserver/pkg/features" |
| 36 |
utilfeature "k8s.io/apiserver/pkg/util/feature" |
| 37 |
"k8s.io/component-base/metrics" |
| 38 |
"k8s.io/component-base/metrics/legacyregistry" |
| 39 |
) |
| 40 |
|
| 41 |
/* |
| 42 |
* By default, the following metric is defined as falling under |
| 43 |
* ALPHA stability level https://github.com/kubernetes/enhancements/blob/master/keps/sig-instrumentation/1209-metrics-stability/kubernetes-control-plane-metrics-stability.md#stability-classes) |
| 44 |
* |
| 45 |
* Promoting the stability level of the metric is a responsibility of the component owner, since it |
| 46 |
* involves explicitly acknowledging support for the metric across multiple releases, in accordance with |
| 47 |
* the metric stability policy. |
| 48 |
*/ |
| 49 |
var clientCertificateExpirationHistogram = metrics.NewHistogram( |
| 50 |
&metrics.HistogramOpts{ |
| 51 |
Namespace: "apiserver", |
| 52 |
Subsystem: "client", |
| 53 |
Name: "certificate_expiration_seconds", |
| 54 |
Help: "Distribution of the remaining lifetime on the certificate used to authenticate a request.", |
| 55 |
Buckets: []float64{ |
| 56 |
0, |
| 57 |
1800, // 30 minutes |
| 58 |
3600, // 1 hour |
| 59 |
7200, // 2 hours |
| 60 |
21600, // 6 hours |
| 61 |
43200, // 12 hours |
| 62 |
86400, // 1 day |
| 63 |
172800, // 2 days |
| 64 |
345600, // 4 days |
| 65 |
604800, // 1 week |
| 66 |
2592000, // 1 month |
| 67 |
7776000, // 3 months |
| 68 |
15552000, // 6 months |
| 69 |
31104000, // 1 year |
| 70 |
}, |
| 71 |
StabilityLevel: metrics.ALPHA, |
| 72 |
}, |
| 73 |
) |
| 74 |
|
| 75 |
func init() { |
| 76 |
legacyregistry.MustRegister(clientCertificateExpirationHistogram) |
| 77 |
} |
| 78 |
|
| 79 |
// UserConversion defines an interface for extracting user info from a client certificate chain |
| 80 |
type UserConversion interface { |
| 81 |
User(chain []*x509.Certificate) (*authenticator.Response, bool, error) |
| 82 |
} |
| 83 |
|
| 84 |
// UserConversionFunc is a function that implements the UserConversion interface. |
| 85 |
type UserConversionFunc func(chain []*x509.Certificate) (*authenticator.Response, bool, error) |
| 86 |
|
| 87 |
// User implements x509.UserConversion |
| 88 |
func (f UserConversionFunc) User(chain []*x509.Certificate) (*authenticator.Response, bool, error) { |
| 89 |
return f(chain) |
| 90 |
} |
| 91 |
|
| 92 |
func columnSeparatedHex(d []byte) string { |
| 93 |
h := strings.ToUpper(hex.EncodeToString(d)) |
| 94 |
var sb strings.Builder |
| 95 |
for i, r := range h { |
| 96 |
sb.WriteRune(r) |
| 97 |
if i%2 == 1 && i != len(h)-1 { |
| 98 |
sb.WriteRune(':') |
| 99 |
} |
| 100 |
} |
| 101 |
return sb.String() |
| 102 |
} |
| 103 |
|
| 104 |
func certificateIdentifier(c *x509.Certificate) string { |
| 105 |
return fmt.Sprintf( |
| 106 |
"SN=%d, SKID=%s, AKID=%s", |
| 107 |
c.SerialNumber, |
| 108 |
columnSeparatedHex(c.SubjectKeyId), |
| 109 |
columnSeparatedHex(c.AuthorityKeyId), |
| 110 |
) |
| 111 |
} |
| 112 |
|
| 113 |
// VerifyOptionFunc is function which provides a shallow copy of the VerifyOptions to the authenticator. This allows |
| 114 |
// for cases where the options (particularly the CAs) can change. If the bool is false, then the returned VerifyOptions |
| 115 |
// are ignored and the authenticator will express "no opinion". This allows a clear signal for cases where a CertPool |
| 116 |
// is eventually expected, but not currently present. |
| 117 |
type VerifyOptionFunc func() (x509.VerifyOptions, bool) |
| 118 |
|
| 119 |
// Authenticator implements request.Authenticator by extracting user info from verified client certificates |
| 120 |
type Authenticator struct { |
| 121 |
verifyOptionsFn VerifyOptionFunc |
| 122 |
user UserConversion |
| 123 |
} |
| 124 |
|
| 125 |
// New returns a request.Authenticator that verifies client certificates using the provided |
| 126 |
// VerifyOptions, and converts valid certificate chains into user.Info using the provided UserConversion |
| 127 |
func New(opts x509.VerifyOptions, user UserConversion) *Authenticator { |
| 128 |
return NewDynamic(StaticVerifierFn(opts), user) |
| 129 |
} |
| 130 |
|
| 131 |
// NewDynamic returns a request.Authenticator that verifies client certificates using the provided |
| 132 |
// VerifyOptionFunc (which may be dynamic), and converts valid certificate chains into user.Info using the provided UserConversion |
| 133 |
func NewDynamic(verifyOptionsFn VerifyOptionFunc, user UserConversion) *Authenticator { |
| 134 |
return &Authenticator{verifyOptionsFn, user} |
| 135 |
} |
| 136 |
|
| 137 |
// AuthenticateRequest authenticates the request using presented client certificates |
| 138 |
func (a *Authenticator) AuthenticateRequest(req *http.Request) (*authenticator.Response, bool, error) { |
| 139 |
if req.TLS == nil || len(req.TLS.PeerCertificates) == 0 { |
| 140 |
return nil, false, nil |
| 141 |
} |
| 142 |
|
| 143 |
// Use intermediates, if provided |
| 144 |
optsCopy, ok := a.verifyOptionsFn() |
| 145 |
// if there are intentionally no verify options, then we cannot authenticate this request |
| 146 |
if !ok { |
| 147 |
return nil, false, nil |
| 148 |
} |
| 149 |
if optsCopy.Intermediates == nil && len(req.TLS.PeerCertificates) > 1 { |
| 150 |
optsCopy.Intermediates = x509.NewCertPool() |
| 151 |
for _, intermediate := range req.TLS.PeerCertificates[1:] { |
| 152 |
optsCopy.Intermediates.AddCert(intermediate) |
| 153 |
} |
| 154 |
} |
| 155 |
|
| 156 |
/* |
| 157 |
kubernetes mutual (2-way) x509 between client and apiserver: |
| 158 |
|
| 159 |
1. apiserver sending its apiserver certificate along with its publickey to client |
| 160 |
2. client verifies the apiserver certificate sent against its cluster certificate authority data |
| 161 |
3. client sending its client certificate along with its public key to the apiserver |
| 162 |
>4. apiserver verifies the client certificate sent against its cluster certificate authority data |
| 163 |
|
| 164 |
description: |
| 165 |
here, with this function, |
| 166 |
client certificate and pub key sent during the handshake process |
| 167 |
are verified by apiserver against its cluster certificate authority data |
| 168 |
|
| 169 |
normal args related to this stage: |
| 170 |
--client-ca-file string If set, any request presenting a client certificate signed by |
| 171 |
one of the authorities in the client-ca-file is authenticated with an identity |
| 172 |
corresponding to the CommonName of the client certificate. |
| 173 |
|
| 174 |
(retrievable from "kube-apiserver --help" command) |
| 175 |
(suggested by @deads2k) |
| 176 |
|
| 177 |
see also: |
| 178 |
- for the step 1, see: staging/src/k8s.io/apiserver/pkg/server/options/serving.go |
| 179 |
- for the step 2, see: staging/src/k8s.io/client-go/transport/transport.go |
| 180 |
- for the step 3, see: staging/src/k8s.io/client-go/transport/transport.go |
| 181 |
*/ |
| 182 |
|
| 183 |
remaining := req.TLS.PeerCertificates[0].NotAfter.Sub(time.Now()) |
| 184 |
clientCertificateExpirationHistogram.WithContext(req.Context()).Observe(remaining.Seconds()) |
| 185 |
chains, err := req.TLS.PeerCertificates[0].Verify(optsCopy) |
| 186 |
if err != nil { |
| 187 |
return nil, false, fmt.Errorf( |
| 188 |
"verifying certificate %s failed: %w", |
| 189 |
certificateIdentifier(req.TLS.PeerCertificates[0]), |
| 190 |
err, |
| 191 |
) |
| 192 |
} |
| 193 |
|
| 194 |
var errlist []error |
| 195 |
for _, chain := range chains { |
| 196 |
user, ok, err := a.user.User(chain) |
| 197 |
if err != nil { |
| 198 |
errlist = append(errlist, err) |
| 199 |
continue |
| 200 |
} |
| 201 |
|
| 202 |
if ok { |
| 203 |
return user, ok, err |
| 204 |
} |
| 205 |
} |
| 206 |
return nil, false, utilerrors.NewAggregate(errlist) |
| 207 |
} |
| 208 |
|
| 209 |
// Verifier implements request.Authenticator by verifying a client cert on the request, then delegating to the wrapped auth |
| 210 |
type Verifier struct { |
| 211 |
verifyOptionsFn VerifyOptionFunc |
| 212 |
auth authenticator.Request |
| 213 |
|
| 214 |
// allowedCommonNames contains the common names which a verified certificate is allowed to have. |
| 215 |
// If empty, all verified certificates are allowed. |
| 216 |
allowedCommonNames StringSliceProvider |
| 217 |
} |
| 218 |
|
| 219 |
// NewVerifier create a request.Authenticator by verifying a client cert on the request, then delegating to the wrapped auth |
| 220 |
func NewVerifier(opts x509.VerifyOptions, auth authenticator.Request, allowedCommonNames sets.String) authenticator.Request { |
| 221 |
return NewDynamicCAVerifier(StaticVerifierFn(opts), auth, StaticStringSlice(allowedCommonNames.List())) |
| 222 |
} |
| 223 |
|
| 224 |
// NewDynamicCAVerifier create a request.Authenticator by verifying a client cert on the request, then delegating to the wrapped auth |
| 225 |
func NewDynamicCAVerifier(verifyOptionsFn VerifyOptionFunc, auth authenticator.Request, allowedCommonNames StringSliceProvider) authenticator.Request { |
| 226 |
return &Verifier{verifyOptionsFn, auth, allowedCommonNames} |
| 227 |
} |
| 228 |
|
| 229 |
// AuthenticateRequest verifies the presented client certificate, then delegates to the wrapped auth |
| 230 |
func (a *Verifier) AuthenticateRequest(req *http.Request) (*authenticator.Response, bool, error) { |
| 231 |
if req.TLS == nil || len(req.TLS.PeerCertificates) == 0 { |
| 232 |
return nil, false, nil |
| 233 |
} |
| 234 |
|
| 235 |
// Use intermediates, if provided |
| 236 |
optsCopy, ok := a.verifyOptionsFn() |
| 237 |
// if there are intentionally no verify options, then we cannot authenticate this request |
| 238 |
if !ok { |
| 239 |
return nil, false, nil |
| 240 |
} |
| 241 |
if optsCopy.Intermediates == nil && len(req.TLS.PeerCertificates) > 1 { |
| 242 |
optsCopy.Intermediates = x509.NewCertPool() |
| 243 |
for _, intermediate := range req.TLS.PeerCertificates[1:] { |
| 244 |
optsCopy.Intermediates.AddCert(intermediate) |
| 245 |
} |
| 246 |
} |
| 247 |
|
| 248 |
if _, err := req.TLS.PeerCertificates[0].Verify(optsCopy); err != nil { |
| 249 |
return nil, false, err |
| 250 |
} |
| 251 |
if err := a.verifySubject(req.TLS.PeerCertificates[0].Subject); err != nil { |
| 252 |
return nil, false, err |
| 253 |
} |
| 254 |
return a.auth.AuthenticateRequest(req) |
| 255 |
} |
| 256 |
|
| 257 |
func (a *Verifier) verifySubject(subject pkix.Name) error { |
| 258 |
// No CN restrictions |
| 259 |
if len(a.allowedCommonNames.Value()) == 0 { |
| 260 |
return nil |
| 261 |
} |
| 262 |
// Enforce CN restrictions |
| 263 |
for _, allowedCommonName := range a.allowedCommonNames.Value() { |
| 264 |
if allowedCommonName == subject.CommonName { |
| 265 |
return nil |
| 266 |
} |
| 267 |
} |
| 268 |
return fmt.Errorf("x509: subject with cn=%s is not in the allowed list", subject.CommonName) |
| 269 |
} |
| 270 |
|
| 271 |
// DefaultVerifyOptions returns VerifyOptions that use the system root certificates, current time, |
| 272 |
// and requires certificates to be valid for client auth (x509.ExtKeyUsageClientAuth) |
| 273 |
func DefaultVerifyOptions() x509.VerifyOptions { |
| 274 |
return x509.VerifyOptions{ |
| 275 |
KeyUsages: []x509.ExtKeyUsage{x509.ExtKeyUsageClientAuth}, |
| 276 |
} |
| 277 |
} |
| 278 |
|
| 279 |
// CommonNameUserConversion builds user info from a certificate chain using the subject's CommonName |
| 280 |
var CommonNameUserConversion = UserConversionFunc(func(chain []*x509.Certificate) (*authenticator.Response, bool, error) { |
| 281 |
if len(chain[0].Subject.CommonName) == 0 { |
| 282 |
return nil, false, nil |
| 283 |
} |
| 284 |
|
| 285 |
fp := sha256.Sum256(chain[0].Raw) |
| 286 |
id := "X509SHA256=" + hex.EncodeToString(fp[:]) |
| 287 |
|
| 288 |
uid, err := parseUIDFromCert(chain[0]) |
| 289 |
if err != nil { |
| 290 |
return nil, false, err |
| 291 |
} |
| 292 |
return &authenticator.Response{ |
| 293 |
User: &user.DefaultInfo{ |
| 294 |
Name: chain[0].Subject.CommonName, |
| 295 |
UID: uid, |
| 296 |
Groups: chain[0].Subject.Organization, |
| 297 |
Extra: map[string][]string{ |
| 298 |
user.CredentialIDKey: {id}, |
| 299 |
}, |
| 300 |
}, |
| 301 |
}, true, nil |
| 302 |
}) |
| 303 |
|
| 304 |
var uidOID = asn1util.X509UID() |
| 305 |
|
| 306 |
func parseUIDFromCert(cert *x509.Certificate) (string, error) { |
| 307 |
if !utilfeature.DefaultFeatureGate.Enabled(features.AllowParsingUserUIDFromCertAuth) { |
| 308 |
return "", nil |
| 309 |
} |
| 310 |
|
| 311 |
uids := []string{} |
| 312 |
for _, name := range cert.Subject.Names { |
| 313 |
if !name.Type.Equal(uidOID) { |
| 314 |
continue |
| 315 |
} |
| 316 |
uid, ok := name.Value.(string) |
| 317 |
if !ok { |
| 318 |
return "", fmt.Errorf("unable to parse UID into a string") |
| 319 |
} |
| 320 |
uids = append(uids, uid) |
| 321 |
} |
| 322 |
if len(uids) == 0 { |
| 323 |
return "", nil |
| 324 |
} |
| 325 |
if len(uids) != 1 { |
| 326 |
return "", fmt.Errorf("expected 1 UID, but found multiple: %v", uids) |
| 327 |
} |
| 328 |
if uids[0] == "" { |
| 329 |
return "", errors.New("UID cannot be an empty string") |
| 330 |
} |
| 331 |
return uids[0], nil |
| 332 |
} |