identity

package module
v1.0.109 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2025 License: Apache-2.0 Imports: 21 Imported by: 96

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

View Source 
var (
	// ErrInvalidAddressForIdentity is returned during ip/hostname SANs validation. It represents that the ip/hostname
	// is not present as a SAN in any available server certificates.
	ErrInvalidAddressForIdentity = errors.New("identity is not valid for provided host")
)

Define base errors

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 IsRootCa added in v1.0.83 

func IsRootCa(cert *x509.Certificate) bool

IsRootCa returns true if a certificate is a root certificate (is a ca, distinguishing name match on subject/issuer, and is self-signed)

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>`

func ValidFor added in v1.0.95 

func ValidFor(id Identity, hostnameOrIp string) error

ValidFor checks if the identity is valid for the given address

Types

type AddressError added in v1.0.95 

type AddressError struct {
	BaseErr  error
	Host     string
	ValidFor []string
}

AddressError is returned during ip/hostname SANs validation. It represents that the ip/hostname is not present as a SAN in any available server certificates.

func (*AddressError) Error added in v1.0.95 

func (e *AddressError) Error() string

func (*AddressError) Unwrap added in v1.0.95 

func (e *AddressError) Unwrap() error

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) AddCa added in v1.0.83 

func (self *CaPool) AddCa(cert *x509.Certificate) error

AddCa adds a CA (root or intermediate) certificate to the current pool. It returns an error if the certificate is not CA.

func (*CaPool) Clone added in v1.0.96 

func (self *CaPool) Clone() *CaPool

func (*CaPool) GetChain added in v1.0.81 

func (self *CaPool) GetChain(cert *x509.Certificate, additionalCerts ...*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, additionalCerts ...*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.

func (*CaPool) Intermediates added in v1.0.83 

func (self *CaPool) Intermediates() []*x509.Certificate

Intermediates returns a copy of the slice of currently added intermediates

func (*CaPool) IntermediatesAsStdPool added in v1.0.83 

func (self *CaPool) IntermediatesAsStdPool() *x509.CertPool

IntermediatesAsStdPool returns all intermediates in an *x509.CertPool. Useful for calling standard x509 package functions.

func (*CaPool) Roots added in v1.0.83 

func (self *CaPool) Roots() []*x509.Certificate

Roots returns a copy of the slice of currently added roots

func (*CaPool) RootsAsStdPool added in v1.0.83 

func (self *CaPool) RootsAsStdPool() *x509.CertPool

RootsAsStdPool returns all intermediates in an *x509.CertPool. Useful for calling standard x509 package functions.

func (*CaPool) VerifyToRoot added in v1.0.83 

func (self *CaPool) VerifyToRoot(cert *x509.Certificate) ([][]*x509.Certificate, error)

VerifyToRoot will obtain a chain and verify it to a root CA. This is similar to the requirements that OpenSSL has for TLS.

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) CheckServerCertSansForConflicts added in v1.0.96 

func (id *ID) CheckServerCertSansForConflicts() []SanHostConflictError

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) GetCaPool added in v1.0.96 

func (id *ID) GetCaPool() *CaPool

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) GetX509ActiveClientCertChain added in v1.0.96 

func (id *ID) GetX509ActiveClientCertChain() []*x509.Certificate

func (*ID) GetX509ActiveServerCertChains added in v1.0.96 

func (id *ID) GetX509ActiveServerCertChains() [][]*x509.Certificate

func (*ID) GetX509CaPool added in v1.0.96 

func (id *ID) GetX509CaPool() *CaPool

func (*ID) GetX509IdentityAltCertCertChains added in v1.0.96 

func (id *ID) GetX509IdentityAltCertCertChains() [][]*x509.Certificate

func (*ID) GetX509IdentityServerCertChain added in v1.0.96 

func (id *ID) GetX509IdentityServerCertChain() []*x509.Certificate

func (*ID) IsCertSettable added in v1.0.101 

func (id *ID) IsCertSettable() error

func (*ID) IsServerCertSettable added in v1.0.101 

func (id *ID) IsServerCertSettable() error

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(pemStr 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) ValidFor added in v1.0.95 

func (id *ID) ValidFor(hostnameOrIp string) error

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 returns the current tls.Certificate linked to this identity's loaded certificates that is used for
	// client connections. The first certificate is always the cert` value loaded.
	Cert() *tls.Certificate

	// ServerCert returns the current tls.Certificate linked to this identity's loaded certificates that is used
	// to initiate server listeners. The first certificate is always the root `cert` or `serverCert` value loaded.
	// Alternative server certs follow.
	ServerCert() []*tls.Certificate

	// CA returns the identities currently loaded x509.CertPool
	CA() *x509.CertPool

	// CaPool returns a more friendly version of x509.CertPool, useful for inspection
	CaPool() *CaPool

	// ServerTLSConfig returns a TSL config linked to this identity and its configuration and certificates. Mutations
	// to the identity (i.e. reloads, updates) propagate to the returned tls.Config.
	ServerTLSConfig() *tls.Config

	// ClientTLSConfig returns a tls.Config linked to this identity and its configuration and certificates. Mutations
	// to the identity (i.e. reloads, updates) propagate to the returned tls.Config.
	ClientTLSConfig() *tls.Config

	// Reload reloads the identity. All changes are propagated to tls.Configs returned by ClientTLSConfig and ServerTLSConfig.
	Reload() error

	// WatchFiles causes this identity to automatically watch its identity file and all referenced files for updates.
	// File updates will call Reload.
	WatchFiles() error

	// StopWatchingFiles reversed WatchFiles.
	StopWatchingFiles()

	// IsCertSettable returns nil if the "cert" certificate storage supports writing, used before calling SetCert()
	IsCertSettable() error

	// SetCert updates the current client cert in use and saves it to the identity file.
	SetCert(pem string) error

	// IsServerCertSettable returns nil if the server certificate storage supports writing, used before calling SetServerCert()
	IsServerCertSettable() error

	// SetServerCert update the current server cert in use and saves it to the identity file.
	SetServerCert(pem string) error

	// GetConfig returns the config used to generate this identity.
	GetConfig() *Config

	// GetX509ActiveClientCertChain returns the client certificate in use as a slice in order of [Leaf->Supporting Certs]
	GetX509ActiveClientCertChain() []*x509.Certificate

	// GetX509ActiveServerCertChains returns an array of arrays of x509.Certificates. Each sub-array is a
	// chain ordered in [Leaf->Supporting Certs]. Each chain is either from the `server_cert` field if defined,
	// otherwise `cert`, and all alternative server certs.
	GetX509ActiveServerCertChains() [][]*x509.Certificate

	// GetX509IdentityServerCertChain returns only the chain from the `server_cert` (if defined) else the chain
	// from the `cert` field.
	GetX509IdentityServerCertChain() []*x509.Certificate

	// GetX509IdentityAltCertCertChains returns all of the chains from the `alt_server_cert` array
	GetX509IdentityAltCertCertChains() [][]*x509.Certificate

	// GetCaPool returns a clone of the current  CA pool
	GetCaPool() *CaPool

	// CheckServerCertSansForConflicts checks the current leaf server certificate for duplicate IP/DNS SANs, which
	// cause ambiguous SNI lookups. Returns nil if no errors.
	CheckServerCertSansForConflicts() []SanHostConflictError

	// ValidFor checks a hostname or IP against all available server certificates and their SANs.
	ValidFor(hostnameOrIp string) error
}

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 SanHostConflictError added in v1.0.96 

type SanHostConflictError struct {
	HostOrIp     string
	Certificates []*x509.Certificate
}

func (SanHostConflictError) Error added in v1.0.96 

func (s SanHostConflictError) Error() string

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

func (*TokenId) ValidFor added in v1.0.95 

func (id *TokenId) ValidFor(hostnameOrIp string) error

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.