pki

package
v0.0.0-...-8d377ce Latest Latest
Warning

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

Go to latest
Published: Mar 29, 2024 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Overview

package pki implements an x509 PKI (Public Key Infrastructure) system backed on etcd.

Index

Constants

This section is empty.

Variables

View Source
var (
	// SelfSigned is an Issuer that generates self-signed certificates.
	SelfSigned = &selfSigned{}
)
View Source
var (
	// From RFC 5280 Section 4.1.2.5
	UnknownNotAfter = time.Unix(253402300799, 0)
)

Functions

func CA

func CA(cn string) x509.Certificate

CA makes a Certificate that can sign other certificates.

func Client

func Client(identity string, groups []string) x509.Certificate

Client makes a Kubernetes PKI-compatible client certificate template. Directly derived from Kubernetes PKI requirements documented at

https://kubernetes.io/docs/setup/best-practices/certificates/#configure-certificates-manually

func Server

func Server(dnsNames []string, ips []net.IP) x509.Certificate

Server makes a Kubernetes PKI-compatible server certificate template.

Types

type CRL

type CRL struct {
	Raw  []byte
	List *pkix.CertificateList
}

type Certificate

type Certificate struct {
	Namespace *Namespace

	// Issuer is the Issuer that will generate this certificate if one doesn't
	// yet exist or etcd, or the requested certificate is ephemeral (not to be
	// stored on etcd).
	Issuer Issuer
	// Name is a unique key for storing the certificate in etcd (if the requested
	// certificate is not ephemeral).
	Name string
	// Template is an x509 certificate definition that will be used to generate
	// the certificate when issuing it.
	Template x509.Certificate

	// Mode in which this Certificate will operate. This influences the behaviour of
	// the Ensure call.
	Mode CertificateMode

	// PrivateKey is the private key for this Certificate. It should never be set by
	// the user, and instead will be populated by the Ensure call for Managed
	// Certificates.
	PrivateKey ed25519.PrivateKey

	// PublicKey is the public key for this Certificate. It should only be set by
	// the user for External or Ephemeral certificates, and will be populated by the
	// next Ensure call if missing.
	PublicKey ed25519.PublicKey
}

Certificate is the promise of a Certificate being available to the caller. In this case, Certificate refers to a pair of x509 certificate and corresponding private key. Certificates can be stored in etcd, and their issuers might also be store on etcd. As such, this type's methods contain references to an etcd KV client.

func (*Certificate) CACertificate

func (c *Certificate) CACertificate(ctx context.Context, kv clientv3.KV) ([]byte, error)

CACertificate returns the DER encoded x509 form of this Certificate that will be the used to issue child certificates.

func (*Certificate) Ensure

func (c *Certificate) Ensure(ctx context.Context, kv clientv3.KV) (cert []byte, err error)

Ensure returns an x509 DER-encoded (but not PEM-encoded) certificate for a given Certificate.

If the Certificate is ephemeral, each call to Ensure will cause a new certificate to be generated. Otherwise, it will be retrieved from etcd, or generated and stored there if needed.

func (*Certificate) Issue

func (c *Certificate) Issue(ctx context.Context, req *Certificate, kv clientv3.KV) (cert []byte, err error)

Issue will generate a key and certificate that is signed by this Certificate, if the Certificate is a CA.

func (*Certificate) Mount

Mount returns a locally mounted FilesystemCertificate for this Certificate, which allows services to access this Certificate via local filesystem access. The embeded fileargs.FileArgs can also be used to add additional file-backed data under the same mount by calling ArgPath. The returned FilesystemCertificate must be Closed in order to prevent a system mount leak.

func (*Certificate) PrivateKeyX509

func (c *Certificate) PrivateKeyX509() ([]byte, error)

func (Certificate) Revoke

func (c Certificate) Revoke(ctx context.Context, kv clientv3.KV, hostname string) error

Revoke performs a CRL-based revocation of a given certificate by this CA, looking it up by DNS name. The revocation is immediately written to the backing etcd store and will be available to consumers through the WatchCRL API.

An error is returned if the CRL could not be emitted (eg. due to an etcd communication error, a conflicting CRL write) or if the given hostname matches no emitted certificate.

Only Managed and External certificates can be revoked.

func (*Certificate) WatchCRL

func (c *Certificate) WatchCRL(cl client.Namespaced) event.Watcher[*CRL]

WatchCRL returns and Event Value compatible CRLWatcher which can be used to retrieve and watch for the newest CRL available from this CA certificate.

type CertificateMode

type CertificateMode int
const (
	// CertificateManaged is a certificate whose key material is fully managed by
	// the Certificate code. When set, PublicKey and PrivateKey must not be set by
	// the user, and instead will be populated by the Ensure call. Name must be set,
	// and will be used to store this Certificate and its keys within etcd. After
	// the initial generation during Ensure, other Certificates with the same Name
	// will be retrieved (including key material) from etcd.
	CertificateManaged CertificateMode = iota

	// CertificateExternal is a certificate whose key material is not managed by
	// Certificate or stored in etcd, but the X509 certificate itself is. PublicKey
	// must be set while PrivateKey must not be set. Name must be set, and will be
	// used to store the emitted X509 certificate in etcd on Ensure. After the
	// initial generation during Ensure, other Certificates with the same Name will
	// be retrieved (without key material) from etcd.
	CertificateExternal

	// CertificateEphemeral is a certificate whose data (X509 certificate and
	// possibly key material) is generated on demand each time Ensure is called.
	// Nothing is stored in etcd or loaded from etcd. PrivateKey or PublicKey can be
	// set, if both are nil then a new keypair will be generated. Name is ignored.
	CertificateEphemeral
)

type FilesystemCertificate

type FilesystemCertificate struct {
	*fileargs.FileArgs
	// CACertPath is the full path at which the CA certificate is available.
	// Read only.
	CACertPath string
	// CertPath is the full path at which the certificate is available. Read
	// only.
	CertPath string
	// KeyPath is the full path at which the private key is available, or an empty
	// string if the Certificate was created without a private key. Read only.
	KeyPath string
}

FilesystemCertificate is a fileargs.FileArgs wrapper which will contain PEM encoded certificate material when Mounted. This construct is useful when dealing with services that want to access etcd-backed certificates as files available locally. Paths to the available files are considered opaque and should not be leaked outside of the struct. Further restrictions on access to these files might be imposed in the future.

type Issuer

type Issuer interface {
	// CACertificate returns the DER-encoded x509 certificate of the CA that
	// will sign certificates when Issue is called, or nil if this is
	// self-signing issuer.
	CACertificate(ctx context.Context, kv clientv3.KV) ([]byte, error)
	// Issue will generate a certificate signed by the Issuer. The returned
	// certificate is x509 DER-encoded.
	Issue(ctx context.Context, req *Certificate, kv clientv3.KV) (cert []byte, err error)
}

Issuer is an entity that can issue certificates. This interface is implemented by SelfSigned, which is an issuer that emits self-signed certificates, and any other Certificate that has been created with CA(), which makes this Certificate act as a CA and issue (sign) ceritficates.

type Namespace

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

Namespace represents some path in etcd where certificate/CA data will be stored. Creating a namespace via Namespaced then permits the consumer of this library to start creating certificates within this namespace.

func Namespaced

func Namespaced(prefix string) Namespace

Namespaced creates a namespace for storing certificate data in etcd at a given 'path' prefix.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL