certificate

README

Package: Certificate

This package contains tools for issuing and renewing certificates for the service mesh.

For design and details on mTLS and certificate issuance please see docs/patterns/certificates.md.

Interfaces

In types.go we define a single interface, certificate.Manager, the interface exposing a particular certificate provider. The certificate manager is responsible for issuing and renewing certificates. It abstracts away the particular methods of signing, renewing, and storing certificates away from the rest of the service mesh components.

Providers

The directory providers contains implementations of certificate issuers (certificate.Managers):

1. tresor is a minimal internal implementation of a certificate issuer, which leverages Go's crypto library and uses Kubernetes' etcd for storage.
2. keyvault is a certificate issuer leveraging Azure Key Vault for secrets storage.
3. vault is another implementation of the certificate.Manager interface, which provides a way for all service mesh certificates to be stored on and signed by Hashicorp Vault.
4. cert-manager is a certificate issuer leveraging cert-manager to sign certificates from Issuers.

Certificate Rotation

In the rotor directory we implement a certificate rotation mechanism, which may or may not be leveraged by the certificate issuers (providers).

Documentation

Overview

Package certificate implements utility routines to endcode and decode certificates, and provides the interface definitions for Certificate and Certificate Manager.

Index

• Constants
• Variables
• func DecodePEMCertificate(certPEM []byte) (*x509.Certificate, error)
• func DecodePEMPrivateKey(keyPEM []byte) (*rsa.PrivateKey, error)
• func EncodeCertDERtoPEM(derBytes []byte) (pem.Certificate, error)
• func EncodeCertReqDERtoPEM(derBytes []byte) (pem.CertificateRequest, error)
• func EncodeKeyDERtoPEM(priv *rsa.PrivateKey) (pem.PrivateKey, error)
• type CertType
• type Certificate
  • func NewFromPEM(pemCert pem.Certificate, pemKey pem.PrivateKey) (*Certificate, error)
  • func (c *Certificate) GetCertificateChain() pem.Certificate
  • func (c *Certificate) GetCommonName() CommonName
  • func (c *Certificate) GetExpiration() time.Time
  • func (c *Certificate) GetIssuingCA() pem.RootCertificate
  • func (c *Certificate) GetPrivateKey() pem.PrivateKey
  • func (c *Certificate) GetSerialNumber() SerialNumber
  • func (c *Certificate) GetTrustedCAs() pem.RootCertificate
• type CommonName
  • func (cn CommonName) String() string
• type IssueOption
  • func FullCNProvided() IssueOption
  • func SubjectAlternativeNames(saNames ...string) IssueOption
  • func ValidityDurationProvided(validityDuration *time.Duration) IssueOption
• type Issuer
• type MRCClient
• type MRCEvent
• type MRCEventBroker
• type MRCEventType
• type Manager
  • func FakeCertManager() (*Manager, error)
  • func NewManager(ctx context.Context, mrcClient MRCClient, ...) (*Manager, error)
  • func (m *Manager) GetCertificate(prefix string) *Certificate
  • func (m *Manager) GetTrustDomain() string
  • func (m *Manager) IssueCertificate(prefix string, ct CertType, opts ...IssueOption) (*Certificate, error)
  • func (m *Manager) ListIssuedCertificates() []*Certificate
  • func (m *Manager) ReleaseCertificate(key string)
  • func (m *Manager) ShouldRotate(c *Certificate) bool
• type SerialNumber
  • func (sn SerialNumber) String() string

Constants

const (
	// TypeCertificate is a string constant to be used in the generation of a certificate.
	TypeCertificate = "CERTIFICATE"

	// TypePrivateKey is a string constant to be used in the generation of a private key for a certificate.
	TypePrivateKey = "PRIVATE KEY"

	// TypeCertificateRequest is a string constant to be used in the generation
	// of a certificate requests.
	TypeCertificateRequest = "CERTIFICATE REQUEST"
)

const (
	// RenewBeforeCertExpires signifies how much earlier (before expiration) should a certificate be renewed
	RenewBeforeCertExpires = 30 * time.Second
)

Variables

var ErrInvalidCertSecret = errors.New("invalid secret for certificate")

ErrInvalidCertSecret is the error that should be returned if the secret is stored incorrectly in the underlying infra

var ErrNoCertificateInPEM = errors.New("no certificate in PEM")

ErrNoCertificateInPEM is the errror for no certificate in PEM

var ErrSecretNotFound = errors.New("secret not found")

ErrSecretNotFound should be returned if the secret isn't present in the underlying infra, on a Get

Functions

func DecodePEMCertificate

func DecodePEMCertificate(certPEM []byte) (*x509.Certificate, error)

DecodePEMCertificate converts a certificate from PEM to x509 encoding

func DecodePEMPrivateKey

func DecodePEMPrivateKey(keyPEM []byte) (*rsa.PrivateKey, error)

DecodePEMPrivateKey converts a certificate from PEM to x509 encoding

func EncodeCertDERtoPEM

func EncodeCertDERtoPEM(derBytes []byte) (pem.Certificate, error)

EncodeCertDERtoPEM encodes the certificate provided in DER format into PEM format More information on the 2 formats is available in the following article: https://support.ssl.com/Knowledgebase/Article/View/19/0/der-vs-crt-vs-cer-vs-pem-certificates-and-how-to-convert-them

func EncodeCertReqDERtoPEM

func EncodeCertReqDERtoPEM(derBytes []byte) (pem.CertificateRequest, error)

EncodeCertReqDERtoPEM encodes the certificate request provided in DER format into PEM format.

func EncodeKeyDERtoPEM

func EncodeKeyDERtoPEM(priv *rsa.PrivateKey) (pem.PrivateKey, error)

EncodeKeyDERtoPEM converts a DER encoded private key into a PEM encoded key

Types

type CertType

type CertType string

CertType is the type of certificate. This is only used by FSM.

const (
	// Internal is the CertType representing all certs issued for use by the FSM
	// control plane.
	Internal CertType = "internal"

	// IngressGateway is the CertType for certs issued for use by ingress gateways.
	IngressGateway CertType = "ingressGateway"

	// Service is the CertType for certs issued for use by the data plane.
	Service CertType = "service"
)

type Certificate

type Certificate struct {
	// The CommonName of the certificate
	CommonName CommonName

	// The SubjectAlternateNames of the certificate
	SANames []string

	// The serial number of the certificate
	SerialNumber SerialNumber

	// When the cert expires
	// If this is a composite certificate, the expiration time is the earliest of them.
	Expiration time.Time

	// PEM encoded Certificate and Key (byte arrays)
	CertChain  pem.Certificate
	PrivateKey pem.PrivateKey

	// Certificate Authority signing this certificate
	IssuingCA pem.RootCertificate

	// The trust context of this certificate's recipient
	// Includes both issuing CA and validating CA (if applicable)
	TrustedCAs pem.RootCertificate
	// contains filtered or unexported fields
}

Certificate represents an x509 certificate.

func NewFromPEM

func NewFromPEM(pemCert pem.Certificate, pemKey pem.PrivateKey) (*Certificate, error)

NewFromPEM is a helper returning a *certificate.Certificate from the PEM components given.

func (*Certificate) GetCertificateChain

func (c *Certificate) GetCertificateChain() pem.Certificate

GetCertificateChain returns the certificate chain of the certificate

func (*Certificate) GetCommonName

func (c *Certificate) GetCommonName() CommonName

GetCommonName returns the Common Name of the certificate

func (*Certificate) GetExpiration

func (c *Certificate) GetExpiration() time.Time

GetExpiration returns the expiration time of the certificate

func (*Certificate) GetIssuingCA

func (c *Certificate) GetIssuingCA() pem.RootCertificate

GetIssuingCA returns the issuing CA of the certificate

func (*Certificate) GetPrivateKey

func (c *Certificate) GetPrivateKey() pem.PrivateKey

GetPrivateKey returns the private key of the certificate

func (*Certificate) GetSerialNumber

func (c *Certificate) GetSerialNumber() SerialNumber

GetSerialNumber returns the serial number of the certificate

func (*Certificate) GetTrustedCAs

func (c *Certificate) GetTrustedCAs() pem.RootCertificate

GetTrustedCAs returns the PEM-encoded trust context for this certificates holder

type CommonName

type CommonName string

CommonName is the Subject Common Name from a given SSL certificate.

func (CommonName) String

func (cn CommonName) String() string

type IssueOption

type IssueOption func(*issueOptions)

IssueOption is an option that can be passed to IssueCertificate.

func FullCNProvided

func FullCNProvided() IssueOption

FullCNProvided tells IssueCertificate that the provided prefix is actually the full trust domain, and not to append the issuer's trust domain.

func SubjectAlternativeNames

func SubjectAlternativeNames(saNames ...string) IssueOption

SubjectAlternativeNames tells IssueCertificate that the certificate's subject alternative names.

func ValidityDurationProvided

func ValidityDurationProvided(validityDuration *time.Duration) IssueOption

ValidityDurationProvided tells IssueCertificate that the certificate's validity duration.

type Issuer

type Issuer interface {
	// IssueCertificate issues a new certificate.
	IssueCertificate(CommonName, []string, time.Duration) (*Certificate, error)
}

Issuer is the interface for a certificate authority that can issue certificates from a given root certificate.

type MRCClient

type MRCClient interface {
	List() ([]*v1alpha3.MeshRootCertificate, error)
	MRCEventBroker

	// GetCertIssuerForMRC returns an Issuer based on the provided MRC.
	GetCertIssuerForMRC(mrc *v1alpha3.MeshRootCertificate) (Issuer, pem.RootCertificate, error)
}

MRCClient is an interface that can watch for changes to the MRC. It is typically backed by a k8s informer.

type MRCEvent

type MRCEvent struct {
	Type MRCEventType
	// The last observed version of the MRC as of the time of this event
	MRC *v1alpha3.MeshRootCertificate
}

MRCEvent describes a change event on a given MRC

type MRCEventBroker

type MRCEventBroker interface {
	// Watch allows the caller to subscribe to events surrounding
	// MRCs. Watch returns a channel that emits events, and
	// an error if the subscription goes awry.
	Watch(context.Context) (<-chan MRCEvent, error)
}

MRCEventBroker describes any type that allows the caller to Watch() MRCEvents

type MRCEventType

type MRCEventType string

MRCEventType is a type alias for a string describing the type of MRC event

var (
	// MRCEventAdded is the type of announcement emitted when we observe an addition of a Kubernetes MeshRootCertificate
	MRCEventAdded MRCEventType = "meshrootcertificate-added"

	// MRCEventUpdated is the type of announcement emitted when we observe an update to a Kubernetes MeshRootCertificate
	MRCEventUpdated MRCEventType = "meshrootcertificate-updated"
)

type Manager

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

Manager represents all necessary information for the certificate managers.

func FakeCertManager

func FakeCertManager() (*Manager, error)

FakeCertManager is a testing helper that returns a *certificate.Manager

func NewManager

func NewManager(ctx context.Context, mrcClient MRCClient, getServiceCertValidityPeriod func() time.Duration, getIngressCertValidityDuration func() time.Duration, msgBroker *messaging.Broker, checkInterval time.Duration) (*Manager, error)

NewManager creates a new CertificateManager with the passed MRCClient and options

func (*Manager) GetCertificate

func (m *Manager) GetCertificate(prefix string) *Certificate

GetCertificate returns the certificate with the specified cn from cache if it exists.

func (*Manager) GetTrustDomain

func (m *Manager) GetTrustDomain() string

GetTrustDomain returns the trust domain from the configured signingkey issuer. Note that the CRD uses a default, so this value will always be set.

func (*Manager) IssueCertificate

func (m *Manager) IssueCertificate(prefix string, ct CertType, opts ...IssueOption) (*Certificate, error)

IssueCertificate returns a newly issued certificate from the given client or an existing valid certificate from the local cache.

func (*Manager) ListIssuedCertificates

func (m *Manager) ListIssuedCertificates() []*Certificate

ListIssuedCertificates implements CertificateDebugger interface and returns the list of issued certificates.

func (*Manager) ReleaseCertificate

func (m *Manager) ReleaseCertificate(key string)

ReleaseCertificate is called when a cert will no longer be needed and should be removed from the system.

func (*Manager) ShouldRotate

func (m *Manager) ShouldRotate(c *Certificate) bool

ShouldRotate determines whether a certificate should be rotated.

type SerialNumber

type SerialNumber string

SerialNumber is the Serial Number of the given certificate.

func (SerialNumber) String

func (sn SerialNumber) String() string