Documentation
¶
Overview ¶
Package pki is the server's built-in certificate authority for workers.
The CA key is derived from the server's master key, so every replica of a server has the same CA without storing or sharing anything, and the CA certificate is byte-identical everywhere (Ed25519 signatures are deterministic and every field is fixed).
A worker enrolls by proving it knows the join token without sending it: both sides compute an HMAC keyed by the token over keying material exported from their TLS session, so a proof made for one connection is useless on another and a machine in the middle, holding two different sessions, can neither pass nor relay it. The server answers with a certificate for the worker's own public key and the CA certificate, both covered by the server's HMAC, which is how the worker learns to trust the CA. From then on each side verifies the other's certificate: the server presents a certificate valid only for server authentication, workers present certificates valid only for client authentication, so a worker's certificate can never impersonate the server.
Index ¶
- Constants
- func Binding(cs tls.ConnectionState) ([]byte, error)
- func EnrollTLS(pin string) *tls.Config
- func Equal(a, b []byte) bool
- func Fingerprint(der []byte) string
- func PeerWorker(cs tls.ConnectionState) (*x509.Certificate, error)
- func ServerProof(token string, binding, cert, caDER []byte) []byte
- func VerifyServer(caDER []byte) func(rawCerts [][]byte, _ [][]*x509.Certificate) error
- func WorkerCert(key ed25519.PrivateKey, certDER, caDER []byte) (tls.Certificate, *x509.Certificate, error)
- func WorkerProof(token string, binding []byte, name string, pub ed25519.PublicKey) []byte
- func WorkerTLS(caDER []byte, cert tls.Certificate) *tls.Config
- type CA
Constants ¶
const ExporterLabel = "EXPORTER-stampede-enroll"
ExporterLabel is the TLS exporter label enrollment proofs are bound to.
const Purpose = "stampede worker CA v1"
Purpose is the keyring derivation label for the CA key. Changing it changes the CA, invalidating every issued certificate.
const WorkerURIPrefix = "stampede://worker/"
WorkerURIPrefix starts the URI SAN that names a worker in its certificate.
Variables ¶
This section is empty.
Functions ¶
func Binding ¶
func Binding(cs tls.ConnectionState) ([]byte, error)
Binding returns the keying material exported from a TLS session for enrollment proofs.
func EnrollTLS ¶
EnrollTLS is the TLS configuration for enrolling: the worker does not know the CA yet, so it accepts any certificate here and checks the chain against the CA from the authenticated reply afterwards. When pin is set (a CA fingerprint), the chain must also lead to that CA.
func Fingerprint ¶
Fingerprint is "sha256:" and the hex SHA-256 of a DER certificate.
func PeerWorker ¶
func PeerWorker(cs tls.ConnectionState) (*x509.Certificate, error)
PeerWorker returns the verified worker certificate of a connection, or an error when the peer presented none or one not for client use.
func ServerProof ¶
ServerProof is the server's proof that it knows the join token and that cert and caDER come from it.
func VerifyServer ¶
func VerifyServer(caDER []byte) func(rawCerts [][]byte, _ [][]*x509.Certificate) error
VerifyServer checks a server's certificate chain against caDER and requires server-authentication usage. It does not check a host name: the CA is private to one server and issues no other server certificates.
func WorkerCert ¶
func WorkerCert(key ed25519.PrivateKey, certDER, caDER []byte) (tls.Certificate, *x509.Certificate, error)
WorkerCert assembles a worker's tls.Certificate from its key and the issued certificate, after checking that the certificate is for that key and chains to caDER for client authentication.
func WorkerProof ¶
WorkerProof is the worker's proof that it knows the join token.
Types ¶
type CA ¶
type CA struct {
Cert *x509.Certificate
DER []byte
// contains filtered or unexported fields
}
CA is a certificate authority with an Ed25519 key.
func (*CA) IssueWorker ¶
func (ca *CA) IssueWorker(name, id string, pub ed25519.PublicKey, validity time.Duration) ([]byte, error)
IssueWorker issues a client certificate for a worker's Ed25519 public key.
func (*CA) ServerCert ¶
ServerCert issues a certificate for the worker port, valid for server authentication only. Workers check it against the CA and the usage, not against a host name, so hosts are informational.
func (*CA) ServerTLS ¶
func (ca *CA) ServerTLS(cert tls.Certificate) *tls.Config
ServerTLS is the worker port's TLS configuration: TLS 1.3 (enrollment proofs need exported keying material), the CA-issued server certificate, and client certificates verified when given. The coordinator decides whether a connection needs one (the Connect stream does, Enroll does not).
Source Files