kubernetes mutual (2-way) x509 comment

staging/src/k8s.io/apiserver/pkg/authentication/request/x509/x509.go

@@ -148,6 +148,33 @@ func (a *Authenticator) AuthenticateRequest(req *http.Request) (*authenticator.R
 		}
 	}
 
+	/*
+			kubernetes mutual (2-way) x509 between client and apiserver:
+
+				1. apiserver sending its apiserver certificate along with its publickey to client
+				2. client verifies the apiserver certificate sent against its cluster certificate authority data
+				3. client sending its client certificate along with its public key to the apiserver
+				>4. apiserver verifies the client certificate sent against its cluster certificate authority data
+
+		    	description:
+					here, with this function,
+					client certificate and pub key sent during the handshake process
+					are verified by apiserver against its cluster certificate authority data
+
+				normal args related to this stage:
+					--client-ca-file string   If set, any request presenting a client certificate signed by
+						one of the authorities in the client-ca-file is authenticated with an identity
+						corresponding to the CommonName of the client certificate.
+
+					(retrievable from "kube-apiserver --help" command)
+					(suggested by @deads2k)
+
+				see also:
+					- for the step 1, see: staging/src/k8s.io/apiserver/pkg/server/options/serving.go
+					- for the step 2, see: staging/src/k8s.io/client-go/transport/transport.go
+					- for the step 3, see: staging/src/k8s.io/client-go/transport/transport.go
+	*/
+
 	remaining := req.TLS.PeerCertificates[0].NotAfter.Sub(time.Now())
 	clientCertificateExpirationHistogram.WithContext(req.Context()).Observe(remaining.Seconds())
 	chains, err := req.TLS.PeerCertificates[0].Verify(optsCopy)

staging/src/k8s.io/apiserver/pkg/server/options/serving.go

@@ -260,7 +260,39 @@ func (s *SecureServingOptions) ApplyTo(config **server.SecureServingInfo) error
 	c := *config
 
 	serverCertFile, serverKeyFile := s.ServerCert.CertKey.CertFile, s.ServerCert.CertKey.KeyFile
-	// load main cert
+	// load main cert *original description until 2023-08-18*
+
+	/*
+		kubernetes mutual (2-way) x509 between client and apiserver:
+
+			>1. apiserver sending its apiserver certificate along with its publickey to client
+			2. client verifies the apiserver certificate sent against its cluster certificate authority data
+			3. client sending its client certificate along with its public key to the apiserver
+			4. apiserver verifies the client certificate sent against its cluster certificate authority data
+
+			description:
+				here, with this block,
+				apiserver certificate and pub key data (along with priv key)get loaded into server.SecureServingInfo
+				for client to later in the step 2 verify the apiserver certificate during the handshake
+				when making a request
+
+			normal args related to this stage:
+				--tls-cert-file string  File containing the default x509 Certificate for HTTPS.
+					(CA cert, if any, concatenated after server cert). If HTTPS serving is enabled, and
+					--tls-cert-file and --tls-private-key-file are not provided, a self-signed certificate
+					and key are generated for the public address and saved to the directory specified by
+					--cert-dir
+				--tls-private-key-file string  File containing the default x509 private key matching --tls-cert-file.
+
+				(retrievable from "kube-apiserver --help" command)
+				(suggested by @deads2k)
+
+			see also:
+				- for the step 2, see: staging/src/k8s.io/client-go/transport/transport.go
+				- for the step 3, see: staging/src/k8s.io/client-go/transport/transport.go
+				- for the step 4, see: staging/src/k8s.io/apiserver/pkg/authentication/request/x509/x509.go
+	*/
+
 	if len(serverCertFile) != 0 || len(serverKeyFile) != 0 {
 		var err error
 		c.Cert, err = dynamiccertificates.NewDynamicServingContentFromFiles("serving-cert", serverCertFile, serverKeyFile)

staging/src/k8s.io/client-go/transport/transport.go

@@ -96,6 +96,32 @@ func TLSConfigFor(c *Config) (*tls.Config, error) {
 	}
 
 	if c.HasCA() {
+		/*
+			kubernetes mutual (2-way) x509 between client and apiserver:
+
+				1. apiserver sending its apiserver certificate along with its publickey to client
+				>2. client verifies the apiserver certificate sent against its cluster certificate authority data
+				3. client sending its client certificate along with its public key to the apiserver
+				4. apiserver verifies the client certificate sent against its cluster certificate authority data
+
+				description:
+					here, with this block,
+					cluster certificate authority data gets loaded into TLS before the handshake process
+					for client to later during the handshake verify the apiserver certificate
+
+				normal args related to this stage:
+					--certificate-authority='':
+						Path to a cert file for the certificate authority
+
+					(retrievable from "kubectl options" command)
+					(suggested by @deads2k)
+
+				see also:
+					- for the step 1, see: staging/src/k8s.io/apiserver/pkg/server/options/serving.go
+					- for the step 3, see: a few lines below in this file
+					- for the step 4, see: staging/src/k8s.io/apiserver/pkg/authentication/request/x509/x509.go
+		*/
+
 		rootCAs, err := rootCertPool(c.TLS.CAData)
 		if err != nil {
 			return nil, fmt.Errorf("unable to load root certificates: %w", err)
@@ -121,6 +147,35 @@ func TLSConfigFor(c *Config) (*tls.Config, error) {
 	}
 
 	if c.HasCertAuth() || c.HasCertCallback() {
+
+		/*
+			    kubernetes mutual (2-way) x509 between client and apiserver:
+
+					1. apiserver sending its apiserver certificate along with its publickey to client
+					2. client verifies the apiserver certificate sent against its cluster certificate authority data
+					>3. client sending its client certificate along with its public key to the apiserver
+					4. apiserver verifies the client certificate sent against its cluster certificate authority data
+
+					description:
+						here, with this callback function,
+						client certificate and pub key get loaded into TLS during the handshake process
+						for apiserver to later in the step 4 verify the client certificate
+
+					normal args related to this stage:
+						--client-certificate='':
+							Path to a client certificate file for TLS
+						--client-key='':
+							Path to a client key file for TLS
+
+						(retrievable from "kubectl options" command)
+						(suggested by @deads2k)
+
+					see also:
+						- for the step 1, see: staging/src/k8s.io/apiserver/pkg/server/options/serving.go
+						- for the step 2, see: a few lines above in this file
+						- for the step 4, see: staging/src/k8s.io/apiserver/pkg/authentication/request/x509/x509.go
+		*/
+
 		tlsConfig.GetClientCertificate = func(*tls.CertificateRequestInfo) (*tls.Certificate, error) {
 			// Note: static key/cert data always take precedence over cert
 			// callback.