Document that PKI objects marshal for OpenSSL

PostgreSQL, Patroni, pgBackRest, and PgBouncer all use certificates
through OpenSSL bindings. The format emitted by "MarshalText" is already
compatible with OpenSSL, so document that and add tests to enforce it.

Author: cbandy

internal/patroni/certificates.go

@@ -16,9 +16,9 @@
 package patroni
 
 import (
-	corev1 "k8s.io/api/core/v1"
+	"encoding"
 
-	"github.com/crunchydata/postgres-operator/internal/pki"
+	corev1 "k8s.io/api/core/v1"
 )
 
 const (
@@ -29,12 +29,12 @@ const (
 	certServerFileKey    = "patroni.crt-combined"
 )
 
-// certAuthorities encodes roots in a format suitable for Patroni's TLS verification.
-func certAuthorities(roots ...pki.Certificate) ([]byte, error) {
+// certFile concatenates the results of multiple PEM-encoding marshalers.
+func certFile(texts ...encoding.TextMarshaler) ([]byte, error) {
 	var out []byte
 
-	for i := range roots {
-		if b, err := roots[i].MarshalText(); err == nil {
+	for i := range texts {
+		if b, err := texts[i].MarshalText(); err == nil {
 			out = append(out, b...)
 		} else {
 			return nil, err
@@ -44,26 +44,6 @@ func certAuthorities(roots ...pki.Certificate) ([]byte, error) {
 	return out, nil
 }
 
-// certFile encodes cert and key as a combination suitable for
-// Patroni's TLS identification. It can be used by both the client and the server.
-func certFile(key pki.PrivateKey, cert pki.Certificate) ([]byte, error) {
-	var out []byte
-
-	if b, err := key.MarshalText(); err == nil {
-		out = append(out, b...)
-	} else {
-		return nil, err
-	}
-
-	if b, err := cert.MarshalText(); err == nil {
-		out = append(out, b...)
-	} else {
-		return nil, err
-	}
-
-	return out, nil
-}
-
 // instanceCertificates returns projections of Patroni's CAs, keys, and
 // certificates to include in the instance configuration volume.
 func instanceCertificates(certificates *corev1.Secret) []corev1.VolumeProjection {

internal/patroni/certificates_test.go

@@ -16,62 +16,31 @@
 package patroni
 
 import (
+	"errors"
 	"testing"
 
 	"gotest.tools/v3/assert"
 	corev1 "k8s.io/api/core/v1"
 
-	"github.com/crunchydata/postgres-operator/internal/pki"
 	"github.com/crunchydata/postgres-operator/internal/testing/cmp"
 )
 
-const rootPEM = `-----BEGIN CERTIFICATE-----
-MIIBgTCCASigAwIBAgIRAO0NXdQ5ZtvI26doDvj9Dx8wCgYIKoZIzj0EAwMwHzEd
-MBsGA1UEAxMUcG9zdGdyZXMtb3BlcmF0b3ItY2EwHhcNMjEwMTI3MjEyNTU0WhcN
-MzEwMTI1MjIyNTU0WjAfMR0wGwYDVQQDExRwb3N0Z3Jlcy1vcGVyYXRvci1jYTBZ
-MBMGByqGSM49AgEGCCqGSM49AwEHA0IABL0xD8B6ZQHPscklofw2hpEN1F8h06Ys
-IRhK2xoy8ASkiKOkzXVs22R/Wnv/+jAMVf9rit0vhblZlvn2yP7e29WjRTBDMA4G
-A1UdDwEB/wQEAwIBBjASBgNVHRMBAf8ECDAGAQH/AgECMB0GA1UdDgQWBBQjfqdS
-Ynr3rFHMLd3fHO79tH3w5DAKBggqhkjOPQQDAwNHADBEAiA41LbQXeC0G/AyOHgs
-gaUp3fzHKSsrTGhzA8+dK2mnSgIgEKnv1FquJBJuXRBAxzrmnt0nJPiTWB926iNE
-BY8V4Ag=
------END CERTIFICATE-----`
+type funcMarshaler func() ([]byte, error)
 
-func TestCertAuthorities(t *testing.T) {
-	root := pki.Certificate{}
-	assert.NilError(t, root.UnmarshalText([]byte(rootPEM)))
-
-	data, err := certAuthorities(root)
-	assert.NilError(t, err)
-
-	// PEM-encoded certificates.
-	assert.DeepEqual(t, string(data), rootPEM+"\n")
-}
+func (f funcMarshaler) MarshalText() ([]byte, error) { return f() }
 
 func TestCertFile(t *testing.T) {
-	root, err := pki.NewRootCertificateAuthority()
-	assert.NilError(t, err)
-
-	instance, err := root.GenerateLeafCertificate("instance.pod-dns", nil)
-	assert.NilError(t, err)
+	expected := errors.New("boom")
+	var short funcMarshaler = func() ([]byte, error) { return []byte(`one`), nil }
+	var fail funcMarshaler = func() ([]byte, error) { return nil, expected }
 
-	data, err := certFile(instance.PrivateKey, instance.Certificate)
+	text, err := certFile(short, short, short)
 	assert.NilError(t, err)
+	assert.DeepEqual(t, text, []byte(`oneoneone`))
 
-	// PEM-encoded key followed by the certificate
-	// - https://docs.python.org/3/library/ssl.html#combined-key-and-certificate
-	// - https://docs.python.org/3/library/ssl.html#certificate-chains
-	assert.Assert(t,
-		cmp.Regexp(`^`+
-			`-----BEGIN [^ ]+ PRIVATE KEY-----\n`+
-			`([^-]+\n)+`+
-			`-----END [^ ]+ PRIVATE KEY-----\n`+
-			`-----BEGIN CERTIFICATE-----\n`+
-			`([^-]+\n)+`+
-			`-----END CERTIFICATE-----\n`+
-			`$`,
-			string(data),
-		))
+	text, err = certFile(short, fail, short)
+	assert.Equal(t, err, expected)
+	assert.DeepEqual(t, text, []byte(nil))
 }
 
 func TestInstanceCertificates(t *testing.T) {

internal/patroni/reconcile.go

@@ -80,12 +80,10 @@ func InstanceCertificates(ctx context.Context,
 	initialize.ByteMap(&outInstanceCertificates.Data)
 
 	var err error
-	outInstanceCertificates.Data[certAuthorityFileKey], err =
-		certAuthorities(inRoot)
+	outInstanceCertificates.Data[certAuthorityFileKey], err = certFile(inRoot)
 
 	if err == nil {
-		outInstanceCertificates.Data[certServerFileKey], err =
-			certFile(inDNSKey, inDNS)
+		outInstanceCertificates.Data[certServerFileKey], err = certFile(inDNSKey, inDNS)
 	}
 
 	return err

internal/patroni/reconcile_test.go

@@ -61,22 +61,44 @@ func TestReconcileInstanceCertificates(t *testing.T) {
 	leaf, err := root.GenerateLeafCertificate("any", nil)
 	assert.NilError(t, err, "bug in test")
 
+	dataCA, _ := certFile(root.Certificate)
+	assert.Assert(t,
+		cmp.Regexp(`^`+
+			`-----BEGIN CERTIFICATE-----\n`+
+			`([^-]+\n)+`+
+			`-----END CERTIFICATE-----\n`+
+			`$`, string(dataCA),
+		),
+		"expected a PEM-encoded certificate bundle")
+
+	dataCert, _ := certFile(leaf.PrivateKey, leaf.Certificate)
+	assert.Assert(t,
+		cmp.Regexp(`^`+
+			`-----BEGIN [^ ]+ PRIVATE KEY-----\n`+
+			`([^-]+\n)+`+
+			`-----END [^ ]+ PRIVATE KEY-----\n`+
+			`-----BEGIN CERTIFICATE-----\n`+
+			`([^-]+\n)+`+
+			`-----END CERTIFICATE-----\n`+
+			`$`, string(dataCert),
+		),
+		// - https://docs.python.org/3/library/ssl.html#combined-key-and-certificate
+		// - https://docs.python.org/3/library/ssl.html#certificate-chains
+		"expected a PEM-encoded key followed by the certificate")
+
 	ctx := context.Background()
 	secret := new(corev1.Secret)
-	cert := leaf.Certificate
-	key := leaf.PrivateKey
-
-	dataCA, _ := certAuthorities(root.Certificate)
-	dataCert, _ := certFile(key, cert)
 
-	assert.NilError(t, InstanceCertificates(ctx, root.Certificate, cert, key, secret))
+	assert.NilError(t, InstanceCertificates(ctx,
+		root.Certificate, leaf.Certificate, leaf.PrivateKey, secret))
 
 	assert.DeepEqual(t, secret.Data["patroni.ca-roots"], dataCA)
 	assert.DeepEqual(t, secret.Data["patroni.crt-combined"], dataCert)
 
 	// No change when called again.
 	before := secret.DeepCopy()
-	assert.NilError(t, InstanceCertificates(ctx, root.Certificate, cert, key, secret))
+	assert.NilError(t, InstanceCertificates(ctx,
+		root.Certificate, leaf.Certificate, leaf.PrivateKey, secret))
 	assert.DeepEqual(t, secret, before)
 }
 

internal/pgbackrest/certificates.go

@@ -16,11 +16,12 @@
 package pgbackrest
 
 import (
+	"encoding"
+
 	corev1 "k8s.io/api/core/v1"
 	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
 
 	"github.com/crunchydata/postgres-operator/internal/initialize"
-	"github.com/crunchydata/postgres-operator/internal/pki"
 )
 
 const (
@@ -47,13 +48,12 @@ const (
 	certRepoSecretKey           = "pgbackrest-repo-host.crt" // #nosec G101 this is a name, not a credential
 )
 
-// certAuthorities returns the PEM encoding of roots that can be read by OpenSSL
-// for TLS verification.
-func certAuthorities(roots ...pki.Certificate) ([]byte, error) {
+// certFile concatenates the results of multiple PEM-encoding marshalers.
+func certFile(texts ...encoding.TextMarshaler) ([]byte, error) {
 	var out []byte
 
-	for i := range roots {
-		if b, err := roots[i].MarshalText(); err == nil {
+	for i := range texts {
+		if b, err := texts[i].MarshalText(); err == nil {
 			out = append(out, b...)
 		} else {
 			return nil, err
@@ -63,18 +63,6 @@ func certAuthorities(roots ...pki.Certificate) ([]byte, error) {
 	return out, nil
 }
 
-// certFile returns the PEM encoding of cert that can be read by OpenSSL
-// for TLS identification.
-func certFile(cert pki.Certificate) ([]byte, error) {
-	return cert.MarshalText()
-}
-
-// certPrivateKey returns the PEM encoding of key that can be read by OpenSSL
-// for TLS identification.
-func certPrivateKey(key pki.PrivateKey) ([]byte, error) {
-	return key.MarshalText()
-}
-
 // clientCertificates returns projections of CAs, keys, and certificates to
 // include in a configuration volume from the pgBackRest Secret.
 func clientCertificates() []corev1.KeyToPath {

internal/pgbackrest/certificates_test.go

@@ -16,6 +16,7 @@
 package pgbackrest
 
 import (
+	"errors"
 	"strings"
 	"testing"
 
@@ -26,6 +27,24 @@ import (
 	"github.com/crunchydata/postgres-operator/internal/testing/cmp"
 )
 
+type funcMarshaler func() ([]byte, error)
+
+func (f funcMarshaler) MarshalText() ([]byte, error) { return f() }
+
+func TestCertFile(t *testing.T) {
+	expected := errors.New("boom")
+	var short funcMarshaler = func() ([]byte, error) { return []byte(`one`), nil }
+	var fail funcMarshaler = func() ([]byte, error) { return nil, expected }
+
+	text, err := certFile(short, short, short)
+	assert.NilError(t, err)
+	assert.DeepEqual(t, text, []byte(`oneoneone`))
+
+	text, err = certFile(short, fail, short)
+	assert.Equal(t, err, expected)
+	assert.DeepEqual(t, text, []byte(nil))
+}
+
 func TestClientCommonName(t *testing.T) {
 	t.Parallel()
 

internal/pgbackrest/reconcile.go

@@ -390,7 +390,7 @@ func InstanceCertificates(ctx context.Context,
 			outInstanceCertificates.Data[certInstanceSecretKey], err = certFile(inDNS)
 		}
 		if err == nil {
-			outInstanceCertificates.Data[certInstancePrivateKeySecretKey], err = certPrivateKey(inDNSKey)
+			outInstanceCertificates.Data[certInstancePrivateKeySecretKey], err = certFile(inDNSKey)
 		}
 	}
 
@@ -510,10 +510,10 @@ func Secret(ctx context.Context,
 		}
 
 		if err == nil {
-			outSecret.Data[certAuthoritySecretKey], err = certAuthorities(inRoot.Certificate)
+			outSecret.Data[certAuthoritySecretKey], err = certFile(inRoot.Certificate)
 		}
 		if err == nil {
-			outSecret.Data[certClientPrivateKeySecretKey], err = certPrivateKey(leaf.PrivateKey)
+			outSecret.Data[certClientPrivateKeySecretKey], err = certFile(leaf.PrivateKey)
 		}
 		if err == nil {
 			outSecret.Data[certClientSecretKey], err = certFile(leaf.Certificate)
@@ -537,7 +537,7 @@ func Secret(ctx context.Context,
 		}
 
 		if err == nil {
-			outSecret.Data[certRepoPrivateKeySecretKey], err = certPrivateKey(leaf.PrivateKey)
+			outSecret.Data[certRepoPrivateKeySecretKey], err = certFile(leaf.PrivateKey)
 		}
 		if err == nil {
 			outSecret.Data[certRepoSecretKey], err = certFile(leaf.Certificate)

internal/pki/encoding.go

@@ -39,7 +39,7 @@ var (
 	_ encoding.TextUnmarshaler = (*Certificate)(nil)
 )
 
-// MarshalText returns a PEM encoding of c.
+// MarshalText returns a PEM encoding of c that OpenSSL understands.
 func (c Certificate) MarshalText() ([]byte, error) {
 	if c.x509 == nil || len(c.x509.Raw) == 0 {
 		_, err := x509.ParseCertificate(nil)
@@ -73,7 +73,7 @@ var (
 	_ encoding.TextUnmarshaler = (*PrivateKey)(nil)
 )
 
-// MarshalText returns a PEM encoding of k.
+// MarshalText returns a PEM encoding of k that OpenSSL understands.
 func (k PrivateKey) MarshalText() ([]byte, error) {
 	if k.ecdsa == nil {
 		k.ecdsa = new(ecdsa.PrivateKey)

internal/pki/encoding_test.go

@@ -17,9 +17,14 @@ package pki
 
 import (
 	"bytes"
+	"os"
+	"os/exec"
+	"path/filepath"
 	"testing"
 
 	"gotest.tools/v3/assert"
+
+	"github.com/crunchydata/postgres-operator/internal/testing/require"
 )
 
 func TestCertificateTextMarshaling(t *testing.T) {
@@ -75,6 +80,23 @@ func TestCertificateTextMarshaling(t *testing.T) {
 		var sink Certificate
 		assert.ErrorContains(t, sink.UnmarshalText(txt), "malformed")
 	})
+
+	t.Run("ReadByOpenSSL", func(t *testing.T) {
+		openssl := require.OpenSSL(t)
+		dir := t.TempDir()
+
+		certFile := filepath.Join(dir, "cert.pem")
+		certBytes, err := cert.MarshalText()
+		assert.NilError(t, err)
+		assert.NilError(t, os.WriteFile(certFile, certBytes, 0o600))
+
+		// The "openssl x509" command parses X.509 certificates.
+		cmd := exec.Command(openssl, "x509",
+			"-in", certFile, "-inform", "PEM", "-noout", "-text")
+
+		output, err := cmd.CombinedOutput()
+		assert.NilError(t, err, "%q\n%s", cmd.Args, output)
+	})
 }
 
 func TestPrivateKeyTextMarshaling(t *testing.T) {
@@ -130,4 +152,29 @@ func TestPrivateKeyTextMarshaling(t *testing.T) {
 		var sink PrivateKey
 		assert.ErrorContains(t, sink.UnmarshalText(txt), "asn1")
 	})
+
+	t.Run("ReadByOpenSSL", func(t *testing.T) {
+		openssl := require.OpenSSL(t)
+		dir := t.TempDir()
+
+		keyFile := filepath.Join(dir, "key.pem")
+		keyBytes, err := key.MarshalText()
+		assert.NilError(t, err)
+		assert.NilError(t, os.WriteFile(keyFile, keyBytes, 0o600))
+
+		// The "openssl pkey" command processes public and private keys.
+		cmd := exec.Command(openssl, "pkey",
+			"-check", "-in", keyFile, "-inform", "PEM", "-noout", "-text")
+
+		output, err := cmd.CombinedOutput()
+		assert.NilError(t, err, "%q\n%s", cmd.Args, output)
+
+		assert.Assert(t,
+			bytes.Contains(output, []byte("is valid")),
+			"expected valid private key, got:\n%s", output)
+
+		assert.Assert(t,
+			bytes.Contains(output, []byte("\nPrivate-Key:")),
+			"expected valid private key, got:\n%s", output)
+	})
 }