modulepki

package
v4.2.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 12, 2026 License: MIT Imports: 36 Imported by: 0

Documentation

Overview

Package modulepki is the kernel's built-in certificate authority for network modules. It issues short-lived certificates whose only identity is a SPIFFE URI SAN (see pkg/moduletls), enrolls modules with hashed one-time or revocable credentials, renews certificates over mTLS, and rotates the CA with an overlap during which both CAs are trusted.

The CA private key is stored sealed with AES-256-GCM under a key-encryption key from configuration; it is unsealed only to sign.

Index

Constants

View Source 
const (
	MinLeafLifetime = 10 * time.Minute
	MaxLeafLifetime = 30 * 24 * time.Hour
)

Leaf lifetimes SignLeaf accepts.

View Source 
const (
	MaxOneTimeEnrollmentTTL  = 7 * 24 * time.Hour
	MaxReusableEnrollmentTTL = 366 * 24 * time.Hour
)

Enrollment limits.

View Source 
const (

	// DefaultCertificateLifetime is the lifetime of module and kernel
	// certificates.
	DefaultCertificateLifetime = 24 * time.Hour
)

Variables

View Source 
var (
	// ErrNoAuthority means the cluster has no current CA yet.
	ErrNoAuthority = errors.New("module PKI has no current CA")
	// ErrInvalidRequest reports a malformed or unacceptable CSR.
	ErrInvalidRequest = errors.New("invalid certificate request")
)
View Source 
var (
	// ErrEnrollmentRejected is the single answer to any unusable enrollment
	// credential, so it cannot be probed.
	ErrEnrollmentRejected = errors.New("module enrollment rejected")
	// ErrCertificateRevoked means the certificate or its enrollment was
	// revoked.
	ErrCertificateRevoked = errors.New("module certificate revoked")
)
View Source 
var ErrBuiltinPKIDisabled = errors.New("the built-in module PKI is not enabled")

ErrBuiltinPKIDisabled means the kernel does not run its own CA: no module_runtime.ca_kek is configured, or the PKI is external.

Functions

func ParseKEK 

func ParseKEK(raw string) ([]byte, error)

ParseKEK decodes a 32-byte key-encryption key given as standard base64 or hex.

func PeerCertificate 

func PeerCertificate(ctx context.Context) (*x509.Certificate, error)

PeerCertificate returns the verified client certificate of a gRPC call, or Unauthenticated when the client presented none.

func RenewAfter added in v4.2.0 

func RenewAfter(issuedAt, notAfter time.Time) time.Time

RenewAfter is when the holder of a leaf issued at issuedAt that expires at notAfter renews it: two thirds of its lifetime. It is the one definition of the Agent contract's renew_after_unix, so a reader that only has the recorded issue and expiry times (the transport inventory) derives the same instant the Agent was told.

func RevocationEpoch 

func RevocationEpoch() uint64

RevocationEpoch returns the process-wide revocation epoch.

func SerialString 

func SerialString(serial *big.Int) string

SerialString is the recorded form of a certificate serial.

Types

type Authority 

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

Authority is the built-in module CA of one cluster.

func FromConfig 

func FromConfig(cfg config.ModuleRuntimeConfig, db *gorm.DB) (*Authority, error)

FromConfig returns the built-in Authority configured by cfg. The CA is independent of the module listener: with pki builtin, module_runtime.ca_kek configures it whether or not module_runtime.enabled starts the listener, so agent enrollment can use it alone (config.ModuleRuntimeConfig.BuiltinCA).

func New 

func New(opts Options) (*Authority, error)

New returns the Authority of opts.Cluster.

func (*Authority) Cluster 

func (a *Authority) Cluster() string

Cluster returns the cluster the authority serves.

func (*Authority) CreateEnrollment 

func (a *Authority) CreateEnrollment(ctx context.Context, request EnrollmentRequest) (string, model.ModuleEnrollment, error)

CreateEnrollment stores a new credential and returns it. The credential is shown only here; the kernel keeps its SHA-256.

func (*Authority) Enroll 

func (a *Authority) Enroll(ctx context.Context, credential, packageID, cluster string, csrDER []byte) (Issued, error)

Enroll exchanges a credential and a CSR for the package's first certificate. A one-time credential is consumed atomically; a failed issuance leaves it unused.

func (*Authority) Ensure 

func (a *Authority) Ensure(ctx context.Context) error

Ensure creates the cluster's first CA when it has none.

func (*Authority) IsRevoked 

func (a *Authority) IsRevoked(ctx context.Context, serial string) (bool, error)

IsRevoked reports whether a certificate serial was revoked. Unknown serials (for example the kernel's own certificate) are not revoked.

func (*Authority) KernelTLS 

func (a *Authority) KernelTLS(ctx context.Context, refresh time.Duration) (moduletls.Source, error)

KernelTLS returns a moduletls.Source for the kernel: a certificate with the kernel's SPIFFE identity, issued in memory by the current CA (its key never leaves the process), and the trust bundle, refreshed every refresh.

func (*Authority) Lifetime 

func (a *Authority) Lifetime() time.Duration

Lifetime returns the lifetime of issued certificates.

func (*Authority) ListEnrollments 

func (a *Authority) ListEnrollments(ctx context.Context) ([]model.ModuleEnrollment, error)

ListEnrollments returns the cluster's enrollments, newest first.

func (*Authority) Maintain 

func (a *Authority) Maintain(ctx context.Context) error

Maintain promotes a next CA that has been trusted for one certificate lifetime and retires the previous one. Retired CAs stay in the trust bundle until the certificates they signed have expired.

func (*Authority) PruneCertificates 

func (a *Authority) PruneCertificates(ctx context.Context, cutoff time.Time) error

PruneCertificates deletes records of certificates that expired before cutoff.

func (*Authority) Renew 

func (a *Authority) Renew(ctx context.Context, peer *x509.Certificate, csrDER []byte) (Issued, error)

Renew issues a new certificate for the holder of a valid module certificate. peer must already be verified against the trust bundle, as the module listener does during the TLS handshake.

func (*Authority) RevokeEnrollment 

func (a *Authority) RevokeEnrollment(ctx context.Context, id string) error

RevokeEnrollment stops a credential and every certificate issued through it: they can no longer renew, and IsRevoked reports their serials.

func (*Authority) Roots 

func (a *Authority) Roots(ctx context.Context) (*x509.CertPool, error)

Roots returns TrustBundle as a certificate pool.

func (*Authority) Rotate 

func (a *Authority) Rotate(ctx context.Context) (*model.ServiceCA, error)

Rotate creates the next CA. It joins the trust bundle at once and starts signing only after one certificate lifetime (see Maintain), so every peer has fetched it by then. Rotating while a next CA exists returns it.

func (*Authority) SignLeaf 

func (a *Authority) SignLeaf(ctx context.Context, tx *gorm.DB, uri *url.URL, lifetime time.Duration, csrDER []byte) (SignedLeaf, error)

SignLeaf issues, inside tx, a certificate whose only identity is the URI SAN uri, for the public key of the PKCS#10 request csrDER, valid for lifetime, with the current CA. The subject and SANs of the request are ignored. The caller records the serial in the same transaction.

func (*Authority) TrustBundle 

func (a *Authority) TrustBundle(ctx context.Context) ([]*x509.Certificate, error)

TrustBundle returns every CA a peer must trust: the current and next CAs and retired CAs whose certificates may still be valid.

func (*Authority) TrustBundlePEM 

func (a *Authority) TrustBundlePEM(ctx context.Context) ([]byte, error)

TrustBundlePEM returns TrustBundle PEM-encoded, the file a module needs to verify the kernel when it enrolls (ANIX_MODULE_TRUST_BUNDLE_FILE).

func (*Authority) TrustBundleRetaining 

func (a *Authority) TrustBundleRetaining(ctx context.Context, retention time.Duration) ([]*x509.Certificate, error)

TrustBundleRetaining is TrustBundle for certificates that live up to retention, such as agent certificates: a retired CA stays until the last certificate it may have signed has expired.

type EnrollmentRequest 

type EnrollmentRequest struct {
	PackageID string
	TTL       time.Duration
	// Reusable credentials (for Kubernetes pods that may restart) can enroll
	// until they expire or are revoked; others enroll once.
	Reusable  bool
	CreatedBy uint
}

EnrollmentRequest describes a new enrollment credential.

type ExternalSource 

type ExternalSource struct {
	TrustBundleFile string
	CertFile        string
	KeyFile         string
	Cluster         string
	Refresh         time.Duration
	// contains filtered or unexported fields
}

ExternalSource serves certificates issued outside the kernel, for example by cert-manager: a trust bundle file and the kernel's certificate and key. Files are re-read when they change, at most every refresh, so rotated secrets apply without a restart.

func (*ExternalSource) Source 

func (s *ExternalSource) Source() (moduletls.Source, error)

Source returns the kernel's moduletls.Source after checking that the files load and that the certificate carries the cluster's kernel identity.

type Issued 

type Issued struct {
	CertificateDER []byte
	TrustBundleDER [][]byte
	Identity       moduletls.Identity
	Serial         string
	NotAfter       time.Time
	RenewAfter     time.Time
}

Issued is a signed leaf certificate.

type Options 

type Options struct {
	DB      *gorm.DB
	Cluster string
	// KEK seals the CA private key; see ParseKEK.
	KEK []byte
	// Lifetime of issued certificates; DefaultCertificateLifetime when zero.
	Lifetime time.Duration
	// Now defaults to time.Now.
	Now func() time.Time
}

Options configures an Authority.

type Server 

type Server struct {
	modulepkiv1.UnimplementedModulePKIServer
	Authority *Authority
}

Server serves ModulePKI on the kernel's module listener. The listener verifies client certificates during the handshake but accepts clients without one, because Enroll comes before the first certificate.

func (*Server) Enroll 

func (s *Server) Enroll(ctx context.Context, request *modulepkiv1.EnrollRequest) (*modulepkiv1.EnrollResponse, error)

func (*Server) GetTrustBundle 

func (s *Server) GetTrustBundle(ctx context.Context, _ *modulepkiv1.GetTrustBundleRequest) (*modulepkiv1.GetTrustBundleResponse, error)

func (*Server) Renew 

func (s *Server) Renew(ctx context.Context, request *modulepkiv1.RenewRequest) (*modulepkiv1.RenewResponse, error)

type SignedLeaf 

type SignedLeaf struct {
	CertificateDER []byte
	// TrustBundleDER is the trust bundle retaining retired CAs for the
	// lifetime the leaf was signed with.
	TrustBundleDER [][]byte
	Serial         string
	NotAfter       time.Time
	RenewAfter     time.Time
	// IssuerKeyID names the CA that signed the leaf.
	IssuerKeyID string
}

SignedLeaf is a certificate the CA signed for an identity outside the module identities, such as an agent's.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.