pkg/tlsutil: add tls util interface and config definition

Author: fanminshi

pkg/tlsutil/tls.go

@@ -0,0 +1,112 @@
+// Copyright 2018 The Operator-SDK Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package tlsutil
+
+import (
+	"k8s.io/api/core/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+)
+
+// CertType defines the type of the cert.
+type CertType int
+
+const (
+	// ClientCert defines a client cert.
+	ClientCert CertType = iota
+	// ServingCert defines a serving cert.
+	ServingCert
+	// ClientAndServingCert defines both client and serving cert.
+	ClientAndServingCert
+)
+
+// CertConfig configures how to generate the Cert.
+type CertConfig struct {
+	// CertName is the name of the cert.
+	CertName string
+	// Optional CertType. Serving, client or both; defaults to both.
+	CertType CertType
+	// Optional CommonName is the common name of the cert; defaults to "".
+	CommonName string
+	// Optional Organization is Organization of the cert; defaults to "".
+	Organization []string
+	// Optional CA Key, if user wants to provide custom CA key via a file path.
+	CAKey string
+	// Optional CA Certificate, if user wants to provide custom CA cert via file path.
+	CACert string
+	// TODO: consider to add passed in SAN fields.
+}
+
+// CertGenerator is an operator specific TLS tool that generates TLS assets for the deploying a user's application.
+type CertGenerator interface {
+	// GenerateCert generates a secret containing TLS encryption key and cert, a Secret
+	// containing the CA key, and a ConfigMap containing the CA Certificate given the Custom
+	// Resource(CR) "cr", the Kubernetes Service "Service", and the CertConfig "config".
+	//
+	// GenerateCert creates and manages TLS key and cert and CA with the following:
+	// CA creation and management:
+	// - If CA is not given:
+	//		-	a unique CA is generated for the CR.
+	//		-	CA's key is packaged into a Secret as shown below.
+	//		-	CA's cert is packaged in a ConfigMap as shown below.
+	//		-	The CA Secret and ConfigMap are then put into the Cluster before returning then to
+	//			the user.
+	// - If CA is given:
+	//		-	CA's key is packaged into a Secret as shown below.
+	// 		-	CA's cert is packaged in a ConfigMap as shown below.
+	//		-	The CA Secret and ConfigMap are returned to the user without putting them into the
+	//			cluster; the reason behind this is that we don't know how to manage the passed in
+	//			CA. Hence, we simply return them as in Kubernetes Objects, and let the user decides
+	//			what to do such as whether to put them into kubernte or not.
+	//
+	// TLS Key and Cert Creation and Management:
+	// - A unique TLS key is generated per CR + CertConfig.CertName. For instance, calling
+	// 	 GenerateCert twice on the same CR + CertConfig.CertName returns the same TLS secret.
+	// - We use the CA determined from the above to generate and to sign the cert of the TLS key.
+	// - The signing process uses the passed in "service" to set the Subject Alternative Names(SAN)
+	//	 for the certificate. We assume that the deployed applications are typically communicated
+	//	 with via a Kubernetes Service. The SAN is set to the FQDN of the service
+	//	 `<service-name>.<service-namespace>.svc.cluster.local`.
+	// - Once TLS key and and Cert are created, they are packaged into a secret as shown below.
+	// - Finally, the secret are put into the Kuberntes before returning it to the user.
+	//
+	// TLS encryption key and cert Secret format:
+	// kind: Secret
+	// apiVersion: v1
+	// metadata:
+	//  name: <cr-kind>-<cr-name>-<CertConfig.CertName>
+	//  namespace: <cr-namespace>
+	// data:
+	//  tls.crt: ...
+	//  tls.key: ...
+	//
+	// CA Certificate ConfigMap format:
+	// kind: ConfigMap
+	//   apiVersion: v1
+	//   metadata:
+	//     name: <cr-kind>-<cr-name>-ca
+	//     namespace: <cr-namespace>
+	//   data:
+	//     ca.crt: ...
+	//
+	// CA Key Secret format:
+	//  kind: Secret
+	//  apiVersion: v1
+	//  metadata:
+	//   name: <cr-kind>-<cr-name>-ca
+	//   namespace: <cr-namespace>
+	//  data:
+	//   ca.key: ..
+	GenerateCert(cr runtime.Object, service *v1.Service, config *CertConfig) (*v1.Secret, *v1.ConfigMap, *v1.Secret, error)
+}