identity

package module
v1.0.81 Latest Latest
Warning

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

 Go to latest Published: Jul 1, 2024 License: Apache-2.0 Imports: 17 Imported by: 89

README

Ziti Identity library

This library is an attempt to normalize identity configuration for various ziti components.

Configuration

It is expected that identity configuration is stored in JSON format and mapped to identity.IdentityConfig type

{
    "id": {
        "key": "file://{path}",
        "cert": "file://{path}",
        "server_cert": "file://{path}" // optional
        "ca": "file://{path}" // optional
    }
}

It allows different ways of specifying private keys and certificates

Keys

  • from file "key": "file://{path to key PEM file}", or "key": "{path to key PEM file}". Note, latter version supports relative paths
  • inline "key": "pem:------BEGIN EC PRIVATE KEY-----...."
  • engine for HW token support "key": "engine:{engine_id}?{engine options}"

Certificates

Applied to both ID/client and server certificates, as well as CA bundle config

  • from file "cert": "file://{path to cert PEM file}", or "server_cert": "{path to key PEM file}". Note, latter version supports relative paths
  • inline "cert": "pem:------BEGIN CERTIFICATE-----...."

Usage

Once IdentityConfig is loaded, it could be used to acquire actual TLS credentials

idCfg := cfg.ID // load config from somewhere
id, err := identity.LoadIdentity(idCfg)

cltCert = id.Cert() // tls.Certificate

Documentation

Index

Constants

View Source 
const (
	ConfigFieldCert           = "cert"
	ConfigFieldKey            = "key"
	ConfigFieldServerCert     = "server_cert"
	ConfigFieldServerKey      = "server_key"
	ConfigFieldAltServerCerts = "alt_server_certs"
	ConfigFieldCa             = "ca"
)
View Source 
const (
	StorageFile = "file"
	StoragePem  = "pem"
)

Variables

This section is empty.

Functions

func AssembleServerChains added in v1.0.3 

func AssembleServerChains(certs []*x509.Certificate, cas []*x509.Certificate) ([][]*x509.Certificate, error)

AssembleServerChains takes in an array of certificates, finds all certificates with x509.ExtKeyUsageAny or x509.ExtKeyUsageServerAuth and builds an array of leaf-first chains. Chains are built starting from server authentication certificates found in `certs` and the signer chains are built from `certs` and `cas`. Both slices are de-duped and the `cas` slice is filtered for certificates with the CA flag set.

func ChainsToTlsCerts added in v1.0.3 

func ChainsToTlsCerts(chains [][]*x509.Certificate, key crypto.PrivateKey) []*tls.Certificate

ChainsToTlsCerts converts and array of x509 certificate chains to an array of tls.Certificates (which have their own internal arrays of raw certificates). It is assumed the same private key is used for all chains.

func IsFile added in v1.0.12 

func IsFile(configValue string) (string, bool)

IsFile returns a file path from a given configuration value and true if the configuration value is a file. Otherwise, returns empty string and false.

func LoadCert added in v1.0.46 

func LoadCert(certAddr string) ([]*x509.Certificate, error)

LoadCert will inspect the string property from an identity configuration and attempt to load an array of *x509.Certificate from there. The type of location is determined by a format with a type prefix followed by a colon. If no known type prefix is present, it is assumed the entire value is a file path.

Support Formats: - `pem:<PEM>` - `file:<PATH>`

func LoadKey 

func LoadKey(keyAddr string) (crypto.PrivateKey, error)

LoadKey will inspect the string property from an identity configuration and attempt to load a private key from there. The type of location is determined by a format with a type prefix followed by a colon. If no known type prefix is present, it is assumed the entire value is a file path.

Support Formats: - `pem:<PEM>` - `file:<PATH>`

Types

type CaPool added in v1.0.21 

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

func NewCaPool added in v1.0.21 

func NewCaPool(certs []*x509.Certificate) *CaPool

func (*CaPool) GetChain added in v1.0.81 

func (self *CaPool) GetChain(cert *x509.Certificate, extraCerts ...*x509.Certificate) []*x509.Certificate

GetChain returns a chain from `cert` up and including the root CA if possible. If no cert is provided, nil is returned. If no chains is assembled the resulting chain will be the target cert only.

func (*CaPool) GetChainMinusRoot added in v1.0.21 

func (self *CaPool) GetChainMinusRoot(cert *x509.Certificate, extraCerts ...*x509.Certificate) []*x509.Certificate

GetChainMinusRoot returns a chain from `cert` up to, but not including, the root CA if possible. If no cert is provided, nil is returned, if no chains is assembled the resulting chain will be the target cert only.

type Config 

type Config struct {
	Key            string       `json:"key" yaml:"key" mapstructure:"key"`
	Cert           string       `json:"cert" yaml:"cert" mapstructure:"cert"`
	ServerCert     string       `json:"server_cert,omitempty" yaml:"server_cert,omitempty" mapstructure:"server_cert,omitempty"`
	ServerKey      string       `json:"server_key,omitempty" yaml:"server_key,omitempty" mapstructure:"server_key,omitempty"`
	AltServerCerts []ServerPair `json:"alt_server_certs,omitempty" yaml:"alt_server_certs,omitempty" mapstructure:"alt_server_certs,omitempty"`
	CA             string       `json:"ca,omitempty" yaml:"ca,omitempty" mapstructure:"ca"`
}

func NewConfigFromMap 

func NewConfigFromMap(identityMap map[interface{}]interface{}) (*Config, error)

NewConfigFromMap will parse a standard identity configuration section that has been loaded from JSON/YAML/etc. parse functions that return interface{} maps. It expects the following fields to be defined as strings if present. If any fields are missing they are left as empty string in the resulting Config.

func NewConfigFromMapWithPathContext 

func NewConfigFromMapWithPathContext(identityMap map[interface{}]interface{}, pathContext string) (*Config, error)

NewConfigFromMapWithPathContext performs the same checks as NewConfigFromMap but also allows a path context to be provided for error messages when parsing deep or complex configuration.

Example: 

`NewConfigFromMapWithPathContext(myMap, "my.path")` errors would be formatted as "value [my.path.cert] must be a string"`

func (*Config) Validate 

func (config *Config) Validate() error

Validate validates the current IdentityConfiguration to have non-empty values all fields except ServerKey which assumes that Key is a suitable default.

func (*Config) ValidateForClient 

func (config *Config) ValidateForClient() error

ValidateForClient validates the current IdentityConfiguration has enough values to initiate a client connection. For example: a tls.Config for a client in mTLS

func (*Config) ValidateForClientWithPathContext 

func (config *Config) ValidateForClientWithPathContext(pathContext string) error

ValidateForClientWithPathContext performs the same checks as ValidateForClient but also allows a path context to be provided for error messages when parsing deep or complex configuration.

Example: 

`ValidateForClientWithPathContext("my.path")`  errors would be formatted as "required configuration value [my.path.cert]..."`

func (*Config) ValidateForServer 

func (config *Config) ValidateForServer() error

ValidateForServer validates the current IdentityConfiguration has enough values to a client connection. For example: a tls.Config for a server in mTLS

func (*Config) ValidateForServerWithPathContext 

func (config *Config) ValidateForServerWithPathContext(pathContext string) error

ValidateForServerWithPathContext performs the same checks as ValidateForServer but also allows a path context to be provided for error messages when parsing deep or complex configuration.

Example: 

`ValidateWithPathContext("my.path")`  errors would be formatted as "required configuration value [my.path.cert]..."`

func (*Config) ValidateWithPathContext 

func (config *Config) ValidateWithPathContext(pathContext string) error

ValidateWithPathContext performs the same checks as Validate but also allows a path context to be provided for error messages when parsing deep or complex configuration.

Example: 

`ValidateWithPathContext("my.path")`  errors would be formatted as "required configuration value [my.path.cert]..."`

type ID 

type ID struct {
	Config
	// contains filtered or unexported fields
}

func (*ID) CA 

func (id *ID) CA() *x509.CertPool

CA returns the ID's current CA certificate pool that is used by all tls.Config's generated from it.

func (*ID) CaPool added in v1.0.21 

func (id *ID) CaPool() *CaPool

CaPool returns the ID's current CA certificate pool that can be used to build cert chains

func (*ID) Cert 

func (id *ID) Cert() *tls.Certificate

Cert returns the ID's current client certificate that is used by all tls.Config's generated from it.

func (*ID) ClientTLSConfig 

func (id *ID) ClientTLSConfig() *tls.Config

ClientTLSConfig returns a new tls.Config instance that will delegate client certificate lookup to the current ID. Calling Reload on the source ID can update which client certificate is used if the internal Config is altered by calling Config or if the values the Config points to are altered (i.e. file update).

Generating multiple tls.Config's by calling this method will return tls.Config's that are all tied to this ID's Config and client certificates.

func (*ID) GetClientCertificate 

func (id *ID) GetClientCertificate(config *tls.Config, _ *tls.CertificateRequestInfo) (*tls.Certificate, error)

GetClientCertificate is used to satisfy tls.Config's GetClientCertificate requirements. Allows client certificates to be updated after enrollment extensions without disconnecting the current client. New settings will be used on re-connect.

func (*ID) GetConfig 

func (id *ID) GetConfig() *Config

GetConfig returns the internally stored copy of the Config that was used to create the ID. The returned Config can be used to create additional IDs but those IDs will not share the same Config.

func (*ID) GetConfigForClient 

func (id *ID) GetConfigForClient(config *tls.Config, _ *tls.ClientHelloInfo) (*tls.Config, error)

GetConfigForClient is used to satisfy tls.Config's GetConfigForClient requirements. Allows servers to have up-to-date CA chains after enrollment extension.

func (*ID) GetServerCertificate 

func (id *ID) GetServerCertificate(hello *tls.ClientHelloInfo) (*tls.Certificate, error)

GetServerCertificate is used to satisfy tls.Config's GetCertificate requirements. Allows server certificates to be updated after enrollment extensions without stopping listeners and disconnecting clients. New settings are used for all new incoming connection.

func (*ID) Reload 

func (id *ID) Reload() error

Reload re-interprets the internal Config that was used to create this ID. This instance of the ID is updated with new client, server, and ca configuration. All tls.Config's generated from this ID will use the newly loaded values for new connections.

func (*ID) ServerCert 

func (id *ID) ServerCert() []*tls.Certificate

ServerCert returns the ID's current server certificate that is used by all tls.Config's generated from it.

func (*ID) ServerTLSConfig 

func (id *ID) ServerTLSConfig() *tls.Config

ServerTLSConfig returns a new tls.Config instance that will delegate server certificate lookup to the current ID. Calling Reload on the source ID will update which server certificate is used if the internal Config is altered by calling Config or if the values the Config points to are altered (i.e. file update).

Generating multiple tls.Config's by calling this method will return tls.Config's that are all tied to this ID's Config.

func (*ID) SetCert 

func (id *ID) SetCert(pem string) error

SetCert persists a new PEM as the ID's client certificate.

func (*ID) SetServerCert 

func (id *ID) SetServerCert(pem string) error

SetServerCert persists a new PEM as the ID's server certificate.

func (*ID) StopWatchingFiles added in v1.0.12 

func (id *ID) StopWatchingFiles()

StopWatchingFiles decrements the number of watchers. If zero is hit all watching is stopped. If too many stops are called a panic will occur.

func (*ID) WatchFiles added in v1.0.12 

func (id *ID) WatchFiles() error

WatchFiles will increment the number of watchers. The first watcher will start a file system watcher. WatchFiles should match with a StopWatchingFiles.

type Identity 

type Identity interface {
	Cert() *tls.Certificate
	ServerCert() []*tls.Certificate
	CA() *x509.CertPool
	CaPool() *CaPool
	ServerTLSConfig() *tls.Config
	ClientTLSConfig() *tls.Config
	Reload() error

	WatchFiles() error
	StopWatchingFiles()

	SetCert(pem string) error
	SetServerCert(pem string) error

	GetConfig() *Config
}

func LoadIdentity 

func LoadIdentity(cfg Config) (Identity, error)

type LazyIdentity added in v1.0.47 

type LazyIdentity struct {
	Identity
	*Config
	// contains filtered or unexported fields
}

LazyIdentity will delay calling identity.LoadIdentity(config) till it is first accessed.

func (*LazyIdentity) CA added in v1.0.47 

func (self *LazyIdentity) CA() *x509.CertPool

func (*LazyIdentity) CaPool added in v1.0.47 

func (self *LazyIdentity) CaPool() *CaPool

func (*LazyIdentity) Cert added in v1.0.47 

func (self *LazyIdentity) Cert() *tls.Certificate

func (*LazyIdentity) ClientTLSConfig added in v1.0.47 

func (self *LazyIdentity) ClientTLSConfig() *tls.Config

func (*LazyIdentity) GetConfig added in v1.0.47 

func (self *LazyIdentity) GetConfig() *Config

func (*LazyIdentity) Reload added in v1.0.47 

func (self *LazyIdentity) Reload() error

func (*LazyIdentity) ServerCert added in v1.0.47 

func (self *LazyIdentity) ServerCert() []*tls.Certificate

func (*LazyIdentity) ServerTLSConfig added in v1.0.47 

func (self *LazyIdentity) ServerTLSConfig() *tls.Config

func (*LazyIdentity) SetCert added in v1.0.47 

func (self *LazyIdentity) SetCert(pem string) error

func (*LazyIdentity) SetServerCert added in v1.0.47 

func (self *LazyIdentity) SetServerCert(pem string) error

func (*LazyIdentity) StopWatchingFiles added in v1.0.47 

func (self *LazyIdentity) StopWatchingFiles()

func (*LazyIdentity) WatchFiles added in v1.0.47 

func (self *LazyIdentity) WatchFiles() error

type ServerPair added in v1.0.5 

type ServerPair struct {
	ServerCert string `json:"server_cert,omitempty" yaml:"server_cert,omitempty" mapstructure:"server_cert,omitempty"`
	ServerKey  string `json:"server_key,omitempty" yaml:"server_key,omitempty" mapstructure:"server_key,omitempty"`
}

type TokenId 

type TokenId struct {
	Identity
	Token string
	Data  map[uint32][]byte
}

func LoadClientIdentity 

func LoadClientIdentity(certPath, keyPath, caCertPath string) (*TokenId, error)

func LoadServerIdentity 

func LoadServerIdentity(clientCertPath, serverCertPath, keyPath, caCertPath string) (*TokenId, error)

func NewClientTokenIdentity 

func NewClientTokenIdentity(clientCerts []*x509.Certificate, privateKey crypto.PrivateKey, caCerts []*x509.Certificate) *TokenId

func NewClientTokenIdentityWithPool added in v1.0.42 

func NewClientTokenIdentityWithPool(clientCerts []*x509.Certificate, privateKey crypto.PrivateKey, caPool *x509.CertPool) *TokenId

func NewIdentity 

func NewIdentity(id Identity) *TokenId

func (*TokenId) ClientTLSConfig 

func (i *TokenId) ClientTLSConfig() *tls.Config

func (*TokenId) ServerTLSConfig 

func (i *TokenId) ServerTLSConfig() *tls.Config

func (*TokenId) ShallowCloneWithNewToken 

func (i *TokenId) ShallowCloneWithNewToken(token string) *TokenId

Source Files

View all Source files

Directories

Path Synopsis
parsec
pkcs11

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.