Add comments to pkg/util functions

Signed-off-by: James Munnelly <james@munnelly.eu>

pkg/util/context.go

@@ -20,6 +20,9 @@ import (
 	"context"
 )
 
+// ContextWithStopCh will wrap a context with a stop channel.
+// When the provided stopCh closes, the cancel() will be called on the context.
+// This provides a convinient way to represent a stop channel as a context.
 func ContextWithStopCh(ctx context.Context, stopCh <-chan struct{}) context.Context {
 	ctx, cancel := context.WithCancel(ctx)
 	go func() {

pkg/util/pki/csr.go

@@ -31,6 +31,8 @@ import (
 	"github.com/jetstack/cert-manager/pkg/util"
 )
 
+// CommonNameForCertificate returns the common name that should be used for the
+// given Certificate resource, by inspecting the CommonName and DNSNames fields.
 func CommonNameForCertificate(crt *v1alpha1.Certificate) string {
 	if crt.Spec.CommonName != "" {
 		return crt.Spec.CommonName
@@ -41,6 +43,8 @@ func CommonNameForCertificate(crt *v1alpha1.Certificate) string {
 	return crt.Spec.DNSNames[0]
 }
 
+// DNSNamesForCertificate returns the DNS names that should be used for the
+// given Certificate resource, by inspecting the CommonName and DNSNames fields.
 func DNSNamesForCertificate(crt *v1alpha1.Certificate) []string {
 	if len(crt.Spec.DNSNames) == 0 {
 		if crt.Spec.CommonName == "" {
@@ -56,6 +60,9 @@ func DNSNamesForCertificate(crt *v1alpha1.Certificate) []string {
 
 const defaultOrganization = "cert-manager"
 
+// OrganizationForCertificate will return the Organization to set for the
+// Certificate resource.
+// If an Organization is not specifically set, a default will be used.
 func OrganizationForCertificate(crt *v1alpha1.Certificate) []string {
 	if len(crt.Spec.Organization) == 0 {
 		return []string{defaultOrganization}
@@ -69,6 +76,10 @@ var serialNumberLimit = new(big.Int).Lsh(big.NewInt(1), 128)
 // default certification duration is 1 year
 const defaultNotAfter = time.Hour * 24 * 365
 
+// GenerateCSR will generate a new *x509.CertificateRequest template to be used
+// by issuers that utilise CSRs to obtain Certificates.
+// The CSR will not be signed, and should be passed to either EncodeCSR or
+// to the x509.CreateCertificateRequest function.
 func GenerateCSR(issuer v1alpha1.GenericIssuer, crt *v1alpha1.Certificate) (*x509.CertificateRequest, error) {
 	commonName := CommonNameForCertificate(crt)
 	dnsNames := DNSNamesForCertificate(crt)
@@ -145,6 +156,8 @@ func GenerateTemplate(issuer v1alpha1.GenericIssuer, crt *v1alpha1.Certificate,
 // *v1alpha1.Certificate crt.
 // publicKey is the public key of the signee, and signerKey is the private
 // key of the signer.
+// It returns a PEM encoded copy of the Certificate as well as a *x509.Certificate
+// which can be used for reading the encoded values.
 func SignCertificate(template *x509.Certificate, issuerCert *x509.Certificate, publicKey interface{}, signerKey interface{}) ([]byte, *x509.Certificate, error) {
 	derBytes, err := x509.CreateCertificate(rand.Reader, template, issuerCert, publicKey, signerKey)
 
@@ -177,6 +190,8 @@ func SignCertificate(template *x509.Certificate, issuerCert *x509.Certificate, p
 	return pemBytes.Bytes(), cert, err
 }
 
+// EncodeCSR calls x509.CreateCertificateRequest to sign the given CSR template.
+// It returns a DER encoded signed CSR.
 func EncodeCSR(template *x509.CertificateRequest, key crypto.Signer) ([]byte, error) {
 	derBytes, err := x509.CreateCertificateRequest(rand.Reader, template, key)
 	if err != nil {
@@ -186,6 +201,7 @@ func EncodeCSR(template *x509.CertificateRequest, key crypto.Signer) ([]byte, er
 	return derBytes, nil
 }
 
+// EncodeX509 will encode a *x509.Certificate into PEM format.
 func EncodeX509(cert *x509.Certificate) ([]byte, error) {
 	caPem := bytes.NewBuffer([]byte{})
 	err := pem.Encode(caPem, &pem.Block{Type: "CERTIFICATE", Bytes: cert.Raw})
@@ -196,7 +212,8 @@ func EncodeX509(cert *x509.Certificate) ([]byte, error) {
 	return caPem.Bytes(), nil
 }
 
-// Return the appropriate signature algorithm for the certificate
+// SignatureAlgorithm will determine the appropriate signature algorithm for
+// the given certificate.
 // Adapted from https://github.com/cloudflare/cfssl/blob/master/csr/csr.go#L102
 func SignatureAlgorithm(crt *v1alpha1.Certificate) (x509.SignatureAlgorithm, error) {
 	switch crt.Spec.KeyAlgorithm {

pkg/util/pki/parse.go

@@ -25,6 +25,8 @@ import (
 	"github.com/jetstack/cert-manager/pkg/util/errors"
 )
 
+// DecodePrivateKeyBytes will decode a PEM encoded private key into a crypto.Signer.
+// It supports ECDSA and RSA private keys only. All other types will return err.
 func DecodePrivateKeyBytes(keyBytes []byte) (crypto.Signer, error) {
 	// decode the private key pem
 	block, _ := pem.Decode(keyBytes)
@@ -57,6 +59,7 @@ func DecodePrivateKeyBytes(keyBytes []byte) (crypto.Signer, error) {
 	}
 }
 
+// DecodePKCS1PrivateKeyBytes will decode a PEM encoded RSA private key.
 func DecodePKCS1PrivateKeyBytes(keyBytes []byte) (*rsa.PrivateKey, error) {
 	// decode the private key pem
 	block, _ := pem.Decode(keyBytes)
@@ -75,6 +78,7 @@ func DecodePKCS1PrivateKeyBytes(keyBytes []byte) (*rsa.PrivateKey, error) {
 	return key, nil
 }
 
+// DecodeX509CertificateBytes will decode a PEM encoded x509 Certificate.
 func DecodeX509CertificateBytes(certBytes []byte) (*x509.Certificate, error) {
 	// decode the tls certificate pem
 	block, _ := pem.Decode(certBytes)