certificate

package
v0.0.0-...-4b75dde Latest Latest
Warning

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

 Go to latest Published: Sep 15, 2023 License: Apache-2.0 Imports: 25 Imported by: 0

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

View Source 
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"
)
View Source 
const (
	// MinRotateBeforeExpireMinutes specifies the minimum number of minutes of how much earlier we can do a certificate renewal.
	// This prevents us from rotating too frequently.
	MinRotateBeforeExpireMinutes = 5
)

Variables

View Source 
var ErrExpectedActiveMRC = errors.New("found no active MRCs")

ErrExpectedActiveMRC is the error that should be returned when no active MRCs are present in the mesh.

View Source 
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

View Source 
var ErrInvalidMRCRoleCombination = errors.New("invalid mrc role combination")

ErrInvalidMRCRoleCombination is the error that should be returned if the combination of MRC roles is invalid.

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

ErrNoCertificateInPEM is the error for no certificate in PEM

View Source 
var ErrNoMRCsFound = errors.New("found no MRCs")

ErrNoMRCsFound is the the error that should be returned if no MRCs were found in the control plane.

View Source 
var ErrNumMRCExceedsMaxSupported = errors.New("found more than the max number of MRCs supported in the control plane namespace")

ErrNumMRCExceedsMaxSupported is the error that should be returned if there are more than 2 MRCs with active and/or passive role in the mesh.

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

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

View Source 
var ErrUnexpectedMRCRole = errors.New("found unexpected MRC role. Expected passive or active")

ErrUnexpectedMRCRole is the error that should be returned if the role value is not passive or active. The MRC reconciler should only consider MRCs with passive or active roles for the validating and signing issuers.

View Source 
var ErrUnexpectedNilMRC = errors.New("received nil MRC")

ErrUnexpectedNilMRC is the the error that should be returned if the MRC is nil.

Functions

func CreateValidCertAndKey 

func CreateValidCertAndKey(cn CommonName, notBefore, notAfter time.Time) (pem.Certificate, pem.PrivateKey, error)

CreateValidCertAndKey creates a non-expiring PEM certificate and private key

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

func ValidateMRCCombination 

func ValidateMRCCombination(mrcList []*v1alpha2.MeshRootCertificate) error

ValidateMRCCombination expects a list of Active and Passive MRCs and ensures that the MRC combination is valid

Types

type Certificate 

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

	// 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 NewCertificateFromPEM 

func NewCertificateFromPEM(pemCert, pemKey, caCert []byte,
	signingIssuerID, validatingIssuerID string) (*Certificate, error)

NewCertificateFromPEM is a helper returning a *certificate.Certificate from the PEM components, signingIssuerID, and validatingIssuerID 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) GetSigningIssuerID 

func (c *Certificate) GetSigningIssuerID() string

GetSigningIssuerID returns the signing Issuer ID for this certificates holder

func (*Certificate) GetTrustedCAs 

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

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

func (*Certificate) GetValidatingIssuerID 

func (c *Certificate) GetValidatingIssuerID() string

GetValidatingIssuerID returns the validating Issuer ID for this certificates holder

func (*Certificate) String 

func (c *Certificate) String() string

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 on the CertificateManager

func ForCommonName 

func ForCommonName(fullCommonName string) IssueOption

ForCommonName creates an internal certificate with a given full common name

func ForCommonNamePrefix 

func ForCommonNamePrefix(prefix string) IssueOption

ForCommonNamePrefix creates an internal certificate with a prefix for the common name. The trust domain will be appended to the Common Name

func ForIngressGateway 

func ForIngressGateway(fullCommonName string) IssueOption

ForIngressGateway creates a certificate which is given a full common name

func ForServiceIdentity 

func ForServiceIdentity(identity identity.ServiceIdentity) IssueOption

ForServiceIdentity creates a service certificate with the given prefix for the common name The trust domain will be appended to the Common Name

type IssueOptions 

type IssueOptions struct {
	ValidityDuration time.Duration
	// contains filtered or unexported fields
}

IssueOptions is passed to the Certificate Providers when creating certificates

func NewCertOptions 

func NewCertOptions(options ...IssueOption) IssueOptions

NewCertOptions creates the IssueOptions for issuing a certificate

func NewCertOptionsWithFullName 

func NewCertOptionsWithFullName(fullCommonName string, validity time.Duration) IssueOptions

NewCertOptionsWithFullName creates the IssueOptions for the issuing a certificate with a given full common name

func NewCertOptionsWithTrustDomain 

func NewCertOptionsWithTrustDomain(prefix string, trustDomain string, validity time.Duration, spiffeEnabled bool) IssueOptions

NewCertOptionsWithTrustDomain creates the IssueOptions for the issuing a certificate with a given full common name

func (IssueOptions) CommonName 

func (o IssueOptions) CommonName() CommonName

CommonName constructs the CommonName for the certificate. If the FullCommonName option is set it will use configured name. Otherwise it uses the name configured and appends the trustdomain

func (IssueOptions) URISAN 

func (o IssueOptions) URISAN() *url.URL

URISAN generates a URL in the Spiffe format spiffe://trustdomain/sa/svc

type Issuer 

type Issuer interface {
	// IssueCertificate issues a new certificate.
	IssueCertificate(IssueOptions) (*Certificate, error)
}

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

type IssuerInfo 

type IssuerInfo struct {
	Signing    PrincipalInfo
	Validating PrincipalInfo
}

IssuerInfo is used to hold the current certificate information about the issuers

func (IssuerInfo) AreDifferent 

func (td IssuerInfo) AreDifferent() bool

AreDifferent returns true if the signing and validating trust domains are different

type MRCClient 

type MRCClient interface {
	UpdateMeshRootCertificate(mrc *v1alpha2.MeshRootCertificate) error
	ListMeshRootCertificates() ([]*v1alpha2.MeshRootCertificate, error)
	MRCEventBroker

	// GetCertIssuerForMRC returns an Issuer based on the provided MRC.
	GetCertIssuerForMRC(mrc *v1alpha2.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 {
	// The name of the MRC generating the event
	MRCName string
}

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

type Manager 

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

Manager represents all necessary information for the certificate managers.

func NewManager 

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

NewManager creates a new CertificateManager with the passed MRCClient and options TODO(5046): plumb ownedUseCases through.

func (*Manager) GetIssuersInfo 

func (m *Manager) GetIssuersInfo() IssuerInfo

GetIssuersInfo returns the trust domains and if SPIFFE is enabled from the configured issuers. Note that the CRD uses a default, so this value will always be set. It is up to the caller to determine if the signing and validating trust domains are different

func (*Manager) IssueCertificate 

func (m *Manager) IssueCertificate(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.

func (*Manager) SubscribeRotations 

func (m *Manager) SubscribeRotations(key string) (chan interface{}, func())

SubscribeRotations returns a channel that outputs every certificate that is rotated by the manager. The caller must call the returned method to close the channel. WARNING: you cannot call wait on the returned channel on the same go routine you are issuing a certificate on.

type PrincipalInfo 

type PrincipalInfo struct {
	TrustDomain   string
	SpiffeEnabled bool
}

PrincipalInfo holds TrustDomain and if SPIFFE is enabled which is used to create the Principal Identities for the proxy

type SerialNumber 

type SerialNumber string

SerialNumber is the Serial Number of the given certificate.

func (SerialNumber) String 

func (sn SerialNumber) String() string

Source Files

View all Source files

Directories

Path Synopsis
castorage
k8s
Package k8s implements helper functions to get certificates from Kubernetes secret
 Package k8s implements helper functions to get certificates from Kubernetes secret
Package pem defines the types for the attributes of a Certificate.
 Package pem defines the types for the attributes of a Certificate.
Package providers implements generic certificate provider related functionality
 Package providers implements generic certificate provider related functionality
certmanager
Package certmanager implements the certificate.Manager interface for cert-manager.io as the certificate provider.
 Package certmanager implements the certificate.Manager interface for cert-manager.io as the certificate provider.
tresor
Package tresor implements the certificate.Manager interface for Tresor, a custom certificate provider in OSM.
 Package tresor implements the certificate.Manager interface for Tresor, a custom certificate provider in OSM.
tresor/fake
Package fake moves fakes to their own sub-package
 Package fake moves fakes to their own sub-package
vault
Package vault implements the certificate.Manager interface for Hashicorp Vault as the certificate provider.
 Package vault implements the certificate.Manager interface for Hashicorp Vault as the certificate provider.

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.