pki

Documentation

Overview

Package pki is CypherPanel's certificate authority and mTLS toolkit.

It implements the trust model of ADR-002 and the threat model (§5.1–5.4):

• The control plane holds one CA (a self-signed ECDSA P-256 cert + key).
• Agents generate their own private key locally and send only a CSR; the plane signs a short-lived client certificate whose CommonName is the server ID. The agent's private key never crosses the wire (§5.1).
• All agent↔plane transport is mTLS, TLS 1.3, verified against the pinned CA in both directions (§5.4; ENGINEERING rule 23).

Nothing here logs, and no function returns secret bytes in an error.

Index

• func BootstrapClientTLSConfig(caPEM []byte, serverName string) (*tls.Config, error)
• func CertPool(caPEM []byte) (*x509.CertPool, error)
• func ClientTLSConfig(clientCertPEM, clientKeyPEM, caPEM []byte, serverName string) (*tls.Config, error)
• func GenerateAgentKey(commonName string) (keyPEM, csrPEM []byte, err error)
• func ServerBootstrapTLSConfig(serverCertPEM, serverKeyPEM []byte) (*tls.Config, error)
• func ServerTLSConfig(serverCertPEM, serverKeyPEM, caPEM []byte) (*tls.Config, error)
• type CA
  • func Load(certPEM, keyPEM []byte) (*CA, error)
  • func NewCA(now time.Time) (*CA, error)
  • func (c *CA) CertPEM() []byte
  • func (c *CA) IssueServerCert(dnsNames []string, ipAddrs []net.IP, ttl time.Duration, now time.Time) (certPEM, keyPEM []byte, err error)
  • func (c *CA) KeyPEM() ([]byte, error)
  • func (c *CA) SignAgentCSR(csrPEM []byte, serverID string, ttl time.Duration, now time.Time) ([]byte, error)

Functions

func BootstrapClientTLSConfig

func BootstrapClientTLSConfig(caPEM []byte, serverName string) (*tls.Config, error)

BootstrapClientTLSConfig builds the agent's config for the enrollment call: it pins the plane's CA (verifying it is talking to the real plane) but presents no client cert, because it does not have one yet.

func CertPool

func CertPool(caPEM []byte) (*x509.CertPool, error)

CertPool returns an x509 pool containing exactly the given CA PEM, for pinning. Callers use it as both RootCAs (verify the plane) and ClientCAs (verify agents).

func ClientTLSConfig

func ClientTLSConfig(clientCertPEM, clientKeyPEM, caPEM []byte, serverName string) (*tls.Config, error)

ClientTLSConfig builds the agent's mTLS config: it presents the agent cert and verifies the plane against the pinned CA. serverName must match a SAN on the plane's server cert.

func GenerateAgentKey

func GenerateAgentKey(commonName string) (keyPEM, csrPEM []byte, err error)

GenerateAgentKey creates a fresh agent private key and a CSR to send to the plane. commonName is advisory (the plane overrides it with the server ID). The returned keyPEM stays on the agent host and is never transmitted.

func ServerBootstrapTLSConfig

func ServerBootstrapTLSConfig(serverCertPEM, serverKeyPEM []byte) (*tls.Config, error)

ServerBootstrapTLSConfig builds the enrollment endpoint's config: server-auth only. The enrolling agent has no client cert yet (it is bootstrapping), so this listener authenticates callers by join token at the application layer, not by client cert (threat-model §5.3).

func ServerTLSConfig

func ServerTLSConfig(serverCertPEM, serverKeyPEM, caPEM []byte) (*tls.Config, error)

ServerTLSConfig builds the plane's mTLS listener config: it presents the server cert and requires a client cert signed by the CA (§5.4). TLS 1.3 only.

Types

type CA

type CA struct {
	// contains filtered or unexported fields
}

CA is the control plane's certificate authority. Construct it with NewCA on first boot and persist the PEM material (KeyPEM encrypted at rest — the CA key is asset A2, threat-model §2); reload it thereafter with Load.

func Load

func Load(certPEM, keyPEM []byte) (*CA, error)

Load reconstructs a CA from persisted PEM material.

func NewCA

func NewCA(now time.Time) (*CA, error)

NewCA generates a fresh CA valid for ten years from now.

func (*CA) CertPEM

func (c *CA) CertPEM() []byte

CertPEM returns the CA certificate in PEM form (safe to distribute; this is what agents pin).

func (*CA) IssueServerCert

func (c *CA) IssueServerCert(dnsNames []string, ipAddrs []net.IP, ttl time.Duration, now time.Time) (certPEM, keyPEM []byte, err error)

IssueServerCert issues a serverAuth certificate for the plane's own TLS listeners (gRPC enrollment endpoint, embedded NATS), signed by the CA and valid for the supplied DNS names and IPs.

func (*CA) KeyPEM

func (c *CA) KeyPEM() ([]byte, error)

KeyPEM returns the CA private key in PKCS#8 PEM form. This is asset A2 — callers must encrypt it at rest and never log it (threat-model §5.1).

func (*CA) SignAgentCSR

func (c *CA) SignAgentCSR(csrPEM []byte, serverID string, ttl time.Duration, now time.Time) ([]byte, error)

SignAgentCSR verifies an agent's CSR and issues a client certificate whose CommonName is serverID, valid for ttl. The CSR's own subject is ignored: the plane is authoritative for identity. Proof-of-possession is enforced by checking the CSR signature, so only the holder of the matching private key can obtain a cert for that key.