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.Manager
s):
tresor
is a minimal internal implementation of a certificate issuer, which leverages Go'scrypto
library and uses Kubernetes' etcd for storage.keyvault
is a certificate issuer leveraging Azure Key Vault for secrets storage.vault
is another implementation of thecertificate.Manager
interface, which provides a way for all service mesh certificates to be stored on and signed by Hashicorp Vault.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 (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
- type IssueOption
- type Issuer
- type MRCClient
- type MRCEvent
- type MRCEventBroker
- type MRCEventType
- type Manager
- 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
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 ¶ added in v1.0.0
func DecodePEMCertificate(certPEM []byte) (*x509.Certificate, error)
DecodePEMCertificate converts a certificate from PEM to x509 encoding
func DecodePEMPrivateKey ¶ added in v1.0.0
func DecodePEMPrivateKey(keyPEM []byte) (*rsa.PrivateKey, error)
DecodePEMPrivateKey converts a certificate from PEM to x509 encoding
func EncodeCertDERtoPEM ¶ added in v1.0.0
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 ¶ added in v1.0.0
func EncodeCertReqDERtoPEM(derBytes []byte) (pem.CertificateRequest, error)
EncodeCertReqDERtoPEM encodes the certificate request provided in DER format into PEM format.
func EncodeKeyDERtoPEM ¶ added in v1.0.0
func EncodeKeyDERtoPEM(priv *rsa.PrivateKey) (pem.PrivateKey, error)
EncodeKeyDERtoPEM converts a DER encoded private key into a PEM encoded key
Types ¶
type CertType ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
func (c *Certificate) GetCertificateChain() pem.Certificate
GetCertificateChain returns the certificate chain of the certificate
func (*Certificate) GetCommonName ¶ added in v1.0.0
func (c *Certificate) GetCommonName() CommonName
GetCommonName returns the Common Name of the certificate
func (*Certificate) GetExpiration ¶ added in v1.0.0
func (c *Certificate) GetExpiration() time.Time
GetExpiration returns the expiration time of the certificate
func (*Certificate) GetIssuingCA ¶ added in v1.0.0
func (c *Certificate) GetIssuingCA() pem.RootCertificate
GetIssuingCA returns the issuing CA of the certificate
func (*Certificate) GetPrivateKey ¶ added in v1.0.0
func (c *Certificate) GetPrivateKey() pem.PrivateKey
GetPrivateKey returns the private key of the certificate
func (*Certificate) GetSerialNumber ¶ added in v1.0.0
func (c *Certificate) GetSerialNumber() SerialNumber
GetSerialNumber returns the serial number of the certificate
func (*Certificate) GetTrustedCAs ¶ added in v1.0.0
func (c *Certificate) GetTrustedCAs() pem.RootCertificate
GetTrustedCAs returns the PEM-encoded trust context for this certificates holder
type CommonName ¶ added in v1.0.0
type CommonName string
CommonName is the Subject Common Name from a given SSL certificate.
func (CommonName) String ¶ added in v1.0.0
func (cn CommonName) String() string
type IssueOption ¶ added in v1.0.0
type IssueOption func(*issueOptions)
IssueOption is an option that can be passed to IssueCertificate.
func FullCNProvided ¶ added in v1.0.0
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 ¶ added in v1.0.0
func SubjectAlternativeNames(saNames ...string) IssueOption
SubjectAlternativeNames tells IssueCertificate that the certificate's subject alternative names.
func ValidityDurationProvided ¶ added in v1.0.0
func ValidityDurationProvided(validityDuration *time.Duration) IssueOption
ValidityDurationProvided tells IssueCertificate that the certificate's validity duration.
type Issuer ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
FakeCertManager is a testing helper that returns a *certificate.Manager
func NewManager ¶ added in v1.0.0
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 ¶ added in v1.0.0
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 ¶ added in v1.0.0
func (m *Manager) ListIssuedCertificates() []*Certificate
ListIssuedCertificates implements CertificateDebugger interface and returns the list of issued certificates.
func (*Manager) ReleaseCertificate ¶ added in v1.0.0
ReleaseCertificate is called when a cert will no longer be needed and should be removed from the system.
func (*Manager) ShouldRotate ¶ added in v1.0.0
func (m *Manager) ShouldRotate(c *Certificate) bool
ShouldRotate determines whether a certificate should be rotated.
type SerialNumber ¶ added in v1.0.0
type SerialNumber string
SerialNumber is the Serial Number of the given certificate.
func (SerialNumber) String ¶ added in v1.0.0
func (sn SerialNumber) String() string
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 FSM.
|
Package tresor implements the certificate.Manager interface for Tresor, a custom certificate provider in FSM. |
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. |