Debian Codegraph @

pkg/authentication/request/x509/x509.go

raw
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 }