ziti

package
v0.23.35 Latest Latest
Warning

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

 Go to latest Published: May 9, 2024 License: Apache-2.0 Imports: 57 Imported by: 86

Documentation

Overview

Package ziti provides methods for loading Contexts which interact with an OpenZiti Controller via the Edge Client API to bind (host) services or dial (connect) to services.

Each context is required to authenticate with the Edge Client API via Credentials instance. Credentials come in the form of identity files, username/password, JWTs, and more.

Identity files specified in `ZITI_IDENTITIES` environment variable (semicolon separates) are loaded automatically at startup to populate the DefaultCollection. This behavior is deprecated, and explicit usage of an CtxCollection is suggested. This behavior can be replicated via NewSdkCollectionFromEnv().

Index

Constants

View Source 
const (
	// EventServiceAdded is emitted when a new service is detected by a Ziti SDK context.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) serviceDetail`*rest_model.ServiceDetail` - The full detail record of the service
	EventServiceAdded = events.EventName("service-new")

	// EventServiceChanged is emitted when an existing service undergoes a change in its definition.
	//
	//Arguments:
	// 1) Context - the context that triggered the listener
	// 2) serviceDetail`*rest_model.ServiceDetail` - The full detail record of the service
	EventServiceChanged = events.EventName("service-changed")

	// EventServiceRemoved is emitted when a service is no longer available.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) serviceDetail`*rest_model.ServiceDetail` - The full detail record of the service
	EventServiceRemoved = events.EventName("service-removed")

	// EventRouterConnected is emitted when a connection to an Edge Router is established.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) routerName `string` - The string name of the target router
	// 3) routerKey `string` - A string that uniquely identifies a router connection
	EventRouterConnected = events.EventName("router-connected")

	// EventRouterDisconnected is emitted when a connection to an Edge Router is disconnected.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) routerName `string` - The string name of the target router
	// 3) routerKey `string` - A string that uniquely identifies a router connection
	EventRouterDisconnected = events.EventName("router-disconnected")

	// EventMfaTotpCode is emitted when a Ziti context requires an MFA TOTP code to proceed with authentication.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) query *rest_model.AuthQueryDetail - details the authentication query causing the MFA Code request
	// 3) codeResponse MfaCodeResponse - a function that accepts a string to return to the authentication process. This codeResponse should be invoked with the user supplied TOTP code.
	EventMfaTotpCode = events.EventName("mfa-totp-code")

	// EventAuthQuery is emitted when a Ziti context requires an answer to an authentication query. MFA TOTP is
	// modeled as an authentication query as well and will also trigger the event EventMfaTotpCode.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) query `*rest_model.AuthQueryDetail` - the details of the authentication query
	//
	EventAuthQuery = events.EventName("auth-query")

	// EventAuthenticationStatePartial emitted if a context acquires an API Session that is in a partially authenticated state. Partial authentication
	// allows for interaction w/ MFA TOTP enrollment and answering authentication queries. It does not allow access to service.
	// This event may or may not be emitted depending on the authentication policy the identity is acting under.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) apiSession *rest_model.CurrentAPISessionDetail - details of the current API Session
	EventAuthenticationStatePartial = events.EventName("auth-state-partial")

	// EventAuthenticationStateFull is emitted when a context acquires an API Session that is fully authenticated. The
	// context will have access to services.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) apiSession *rest_model.CurrentApiSessionDetail - details of the current API Session
	EventAuthenticationStateFull = events.EventName("auth-state-full")

	// EventAuthenticationStateUnauthenticated is emitted when a context has reverted to an unauthenticated state after
	// being fully or partially authenticated.
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) apiSession *rest_model.CurrentApiSessionDetail - details of the invalid API Session
	EventAuthenticationStateUnauthenticated = events.EventName("auth-state-unauthenticated")

	// EventControllerUrlsUpdated is emitted when a new set of controllers is detected
	//
	// Arguments:
	// 1) Context - the context that triggered the listener
	// 2) apiUrls []*urls.URL - the URLs of the API for the available controllers
	EventControllerUrlsUpdated = events.EventName("controller-urls-updated")
)
View Source 
const (
	ServiceAdded   ServiceEventType = "Added"
	ServiceRemoved ServiceEventType = "Removed"
	ServiceChanged ServiceEventType = "Changed"

	DefaultServiceRefreshInterval = 5 * time.Minute
	DefaultSessionRefreshInterval = time.Hour
	MinRefreshInterval            = time.Second
)
View Source 
const (
	PrecedenceDefault  Precedence = 0
	PrecedenceRequired Precedence = 1
	PrecedenceFailed   Precedence = 2

	PrecedenceDefaultLabel  = string(rest_model.TerminatorPrecedenceDefault)
	PrecedenceRequiredLabel = string(rest_model.TerminatorPrecedenceRequired)
	PrecedenceFailedLabel   = string(rest_model.TerminatorPrecedenceFailed)
)
View Source 
const (
	LatencyCheckInterval = 30 * time.Second
	LatencyCheckTimeout  = 10 * time.Second

	ClientConfigV1 = "ziti-tunneler-client.v1"
	InterceptV1    = "intercept.v1"

	SessionDial = rest_model.DialBindDial
	SessionBind = rest_model.DialBindBind
)
View Source 
const EnrollmentMethodCa = "ca"
View Source 
const IdentitiesEnv = "ZITI_IDENTITIES"

IdentitiesEnv is the string environment variable that is used to load identity files to populate DefaultCollection

Variables

View Source 
var DefaultOptions = &Options{
	RefreshInterval:        DefaultServiceRefreshInterval,
	SessionRefreshInterval: DefaultSessionRefreshInterval,
	OnServiceUpdate:        nil,
}
View Source 
var EnrollUrl, _ = url.Parse("/edge/client/v1/enroll")

Functions

func ForAllContexts deprecated added in v0.17.0 

func ForAllContexts(f func(ctx Context) bool)

Deprecated: ForAllContexts iterates over all Context instances in the DefaultCollection and call the provided function `f`. Usage of the DefaultCollection is advised against, and if this functionality is needed, implementations should instantiate their own CtxCollection via NewSdkCollection() or NewSdkCollectionFromEnv()

func GetControllerWellKnownCaPool added in v0.20.0 

func GetControllerWellKnownCaPool(controllerAddr string) (*x509.CertPool, error)

GetControllerWellKnownCaPool will return a x509.CertPool. The target controller will not be verified via TLS and must be verified by some other means (i.e. enrollment JWT token).

WARNING: This call is unauthenticated and should only be used for example purposes or expliciltly when an unauthenticated request is required.

func NewId added in v0.20.7 

func NewId() string

NewId will return a unique string id suitable for ziti.Context Id functionality.

Types

type Config added in v0.20.0 

type Config struct {
	//ZtAPI should be in the form of https://<domain>[:<port>]/edge/client/v1. For backwards compatability with single controller identities
	ZtAPI string `json:"ztAPI"`

	//ZtAPIs is an array of ZtAPI values, supersedes `ZtAPI`. ZtAPIs is used to make an initial connection to a controller.
	ZtAPIs []string `json:"ztAPIs"`

	//ConfigTypes is an array of string configuration types that will be requested from the controller
	//for services.
	ConfigTypes []string `json:"configTypes"`

	//The ID field allows configurations is maintained for backwards compatability with previous SDK versions.
	//If set, it will be used to set the Credentials field.
	ID identity.Config `json:"id"`

	//The Credentials field is used to authenticate with the Edge Client API. If the ID field is set, it will be used
	//to populate this field with credentials.
	Credentials apis.Credentials `json:"-"`

	//EnableHa will signal to the SDK to query and use OIDC authentication which is required for HA controller setups.
	//This is a temporary feature flag that will be removed and "default to true" at a later date.
	EnableHa bool `json:"enableHa"`
}

func NewConfig added in v0.20.0 

func NewConfig(ztApi string, idConfig identity.Config) *Config

NewConfig will create a new Config object from a provided Ziti Edge Client API URL and identity configuration. The Ziti Edge Client API is usually in the format of `https://host:port/edge/client/v1`.

func NewConfigFromFile added in v0.20.0 

func NewConfigFromFile(confFile string) (*Config, error)

NewConfigFromFile attempts to load a Config object from the provided path.

The file that is indicated should be in the following format: ``` 

{
  "ztAPI": "https://ziti.controller.example.com/edge/client/v1",
  "configTypes": ["config1", "config2"],
  "id": { "cert": "...", "key": "..." },
}

```

type Context 

type Context interface {
	// Authenticate attempts to use credentials configured on the Context to perform authentication. The authentication
	// implementation used is configured via the Credentials field on an Option struct provided during Context
	// creation.
	Authenticate() error

	// SetCredentials sets the credentials used to authenticate against the Edge Client API.
	SetCredentials(authenticator apis.Credentials)

	// GetCredentials returns the currently set credentials used to authenticate against the Edge Client API.
	GetCredentials() apis.Credentials

	// GetCurrentIdentity returns the Edge API details of the currently authenticated identity.
	GetCurrentIdentity() (*rest_model.IdentityDetail, error)

	// GetCurrentIdentityWithBackoff returns the Edge API details of the currently authenticated identity. with retry if necessary
	GetCurrentIdentityWithBackoff() (*rest_model.IdentityDetail, error)

	// Dial attempts to connect to a service using a given service name; authenticating as necessary in order to obtain
	// a service session, attach to Edge Routers, and connect to a service.
	Dial(serviceName string) (edge.Conn, error)

	// DialWithOptions performs the same logic as Dial but allows specification of DialOptions.
	DialWithOptions(serviceName string, options *DialOptions) (edge.Conn, error)

	// DialAddr finds the service for given address and performs a Dial for it.
	DialAddr(network string, addr string) (edge.Conn, error)

	// Listen attempts to host a service by the given service name;  authenticating as necessary in order to obtain
	// a service session, attach to Edge Routers, and bind (host) the service.
	Listen(serviceName string) (edge.Listener, error)

	// ListenWithOptions performs the same logic as Listen, but allows the specification of ListenOptions.
	ListenWithOptions(serviceName string, options *ListenOptions) (edge.Listener, error)

	// GetServiceId will return the id of a specific service by service name. If not found, false, will be returned
	// with an empty string.
	GetServiceId(serviceName string) (string, bool, error)

	// GetServices will return a slice of service details that the current authenticating identity can access for
	// dial (connect) or bind (host/listen).
	GetServices() ([]rest_model.ServiceDetail, error)

	// GetService will return the service details of a specific service by service name.
	GetService(serviceName string) (*rest_model.ServiceDetail, bool)

	// GetServiceForAddr finds the service with intercept that matches best to given address
	GetServiceForAddr(network, hostname string, port uint16) (*rest_model.ServiceDetail, int, error)

	// RefreshServices forces the context to refresh the list of services the current authenticating identity has access
	// to.
	RefreshServices() error

	// RefreshService forces the context to refresh just the service with the given name. If the given service isn't
	// found, a nil will be returned
	RefreshService(serviceName string) (*rest_model.ServiceDetail, error)

	// GetServiceTerminators will return a slice of rest_model.TerminatorClientDetail for a specific service name.
	// The offset and limit options can be used to page through excessive lists of items. A max of 500 is imposed on
	// limit.
	GetServiceTerminators(serviceName string, offset, limit int) ([]*rest_model.TerminatorClientDetail, int, error)

	// GetSession will return the session detail associated with a specific session id.
	GetSession(id string) (*rest_model.SessionDetail, error)

	// Metrics will return the current context's metrics Registry.
	Metrics() metrics.Registry

	// Close closes any connections open to edge routers
	Close()

	// Deprecated: AddZitiMfaHandler adds a Ziti MFA handler, invoked during authentication.
	// Replaced with event functionality. Use `zitiContext.AddListener(MfaTotpCode, handler)` instead.
	AddZitiMfaHandler(handler func(query *rest_model.AuthQueryDetail, resp MfaCodeResponse) error)

	// EnrollZitiMfa will attempt to enable TOTP 2FA on the currently authenticating identity if not already enrolled.
	EnrollZitiMfa() (*rest_model.DetailMfa, error)

	// VerifyZitiMfa will attempt to complete enrollment of TOTP 2FA with the given code.
	VerifyZitiMfa(code string) error

	// RemoveZitiMfa will attempt to remove TOTP 2FA for the current identity
	RemoveZitiMfa(code string) error

	// GetId returns a unique context id
	GetId() string

	// SetId allows the setting of a context's id
	SetId(id string)

	Events() Eventer
}

Context is the main interface for SDK instances that may be used to authenticate, connect to services, or host services.

func LoadContext deprecated added in v0.17.0 

func LoadContext(configPath string) (Context, error)

Deprecated: LoadContext loads a configuration from the supplied path into the DefaultCollection as a convenience. Usage of the DefaultCollection is advised against, and if this functionality is needed, implementations should instantiate their own CtxCollection via NewSdkCollection() or NewSdkCollectionFromEnv().

This function's behavior can be replicated with: ```

collection = NewSdkCollection() collection.ConfigTypes = []string{InterceptV1, ClientConfigV1} collection.NewContextFromFile(configPath)

```

LoadContext will attempt to load a Config from the provided path, see NewConfigFromFile() for details. Additionally, LoadContext will attempt to authenticate the Context. If it does not authenticate, it will not be added to the DefaultCollection and an error will be returned. ```

func NewContext 

func NewContext(cfg *Config) (Context, error)

NewContext creates a Context from the supplied Config with the default options. See NewContextWithOpts().

func NewContextFromFile added in v0.20.7 

func NewContextFromFile(path string) (Context, error)

NewContextFromFile attempts to load a new Config from the provided path and then uses that config to instantiate a new Context. See NewConfigFromFile() for configuration file details.

func NewContextFromFileWithOpts added in v0.20.7 

func NewContextFromFileWithOpts(path string, options *Options) (Context, error)

NewContextFromFileWithOpts does the same as NewContextFromFile but allow Options to be supplied.

func NewContextWithOpts added in v0.13.0 

func NewContextWithOpts(cfg *Config, options *Options) (Context, error)

NewContextWithOpts creates a Context from the supplied Config and Options. The configuration requires either the `ID` field or the `Credentials` field to be populated. If both are supplied, the `ID` field is used.

type ContextDialer added in v0.17.0 

type ContextDialer interface {
	DialContext(ctx context.Context, network, address string) (net.Conn, error)
}

type ContextImpl added in v0.19.0 

type ContextImpl struct {
	Id string

	CtrlClt *CtrlClient

	events.EventEmmiter
	// contains filtered or unexported fields
}

func (*ContextImpl) AddAuthQueryListener added in v0.20.50 

func (context *ContextImpl) AddAuthQueryListener(handler func(Context, *rest_model.AuthQueryDetail)) func()

func (*ContextImpl) AddAuthenticationStateFullListener added in v0.20.50 

func (context *ContextImpl) AddAuthenticationStateFullListener(handler func(Context, apis.ApiSession)) func()

func (*ContextImpl) AddAuthenticationStatePartialListener added in v0.20.50 

func (context *ContextImpl) AddAuthenticationStatePartialListener(handler func(Context, apis.ApiSession)) func()

func (*ContextImpl) AddAuthenticationStateUnauthenticatedListener added in v0.20.50 

func (context *ContextImpl) AddAuthenticationStateUnauthenticatedListener(handler func(Context, apis.ApiSession)) func()

func (*ContextImpl) AddControllerUrlsUpdateListener added in v0.23.23 

func (context *ContextImpl) AddControllerUrlsUpdateListener(handler func(Context, []*url.URL)) func()

func (*ContextImpl) AddMfaTotpCodeListener added in v0.20.50 

func (context *ContextImpl) AddMfaTotpCodeListener(handler func(Context, *rest_model.AuthQueryDetail, MfaCodeResponse)) func()

func (*ContextImpl) AddRouterConnectedListener added in v0.20.50 

func (context *ContextImpl) AddRouterConnectedListener(handler func(Context, string, string)) func()

func (*ContextImpl) AddRouterDisconnectedListener added in v0.20.50 

func (context *ContextImpl) AddRouterDisconnectedListener(handler func(Context, string, string)) func()

func (*ContextImpl) AddServiceAddedListener added in v0.20.50 

func (context *ContextImpl) AddServiceAddedListener(handler func(Context, *rest_model.ServiceDetail)) func()

func (*ContextImpl) AddServiceChangedListener added in v0.20.50 

func (context *ContextImpl) AddServiceChangedListener(handler func(Context, *rest_model.ServiceDetail)) func()

func (*ContextImpl) AddServiceRemovedListener added in v0.20.50 

func (context *ContextImpl) AddServiceRemovedListener(handler func(Context, *rest_model.ServiceDetail)) func()

func (*ContextImpl) AddZitiMfaHandler added in v0.19.0 

func (context *ContextImpl) AddZitiMfaHandler(handler func(query *rest_model.AuthQueryDetail, response MfaCodeResponse) error)

func (*ContextImpl) Authenticate added in v0.19.0 

func (context *ContextImpl) Authenticate() error

func (*ContextImpl) Close added in v0.19.0 

func (context *ContextImpl) Close()

func (*ContextImpl) CloseAllEdgeRouterConns added in v0.20.50 

func (context *ContextImpl) CloseAllEdgeRouterConns()

func (*ContextImpl) Dial added in v0.19.0 

func (context *ContextImpl) Dial(serviceName string) (edge.Conn, error)

func (*ContextImpl) DialAddr added in v0.19.0 

func (context *ContextImpl) DialAddr(network string, addr string) (edge.Conn, error)

func (*ContextImpl) DialWithOptions added in v0.19.0 

func (context *ContextImpl) DialWithOptions(serviceName string, options *DialOptions) (edge.Conn, error)

func (*ContextImpl) EnrollZitiMfa added in v0.19.0 

func (context *ContextImpl) EnrollZitiMfa() (*rest_model.DetailMfa, error)

func (*ContextImpl) EnsureAuthenticated added in v0.19.0 

func (context *ContextImpl) EnsureAuthenticated(options edge.ConnOptions) error

func (*ContextImpl) Events added in v0.20.50 

func (context *ContextImpl) Events() Eventer

func (*ContextImpl) GetCredentials added in v0.20.0 

func (context *ContextImpl) GetCredentials() apis.Credentials

func (*ContextImpl) GetCurrentIdentity added in v0.19.0 

func (context *ContextImpl) GetCurrentIdentity() (*rest_model.IdentityDetail, error)

func (*ContextImpl) GetCurrentIdentityWithBackoff added in v0.23.4 

func (context *ContextImpl) GetCurrentIdentityWithBackoff() (*rest_model.IdentityDetail, error)

func (*ContextImpl) GetId added in v0.20.7 

func (context *ContextImpl) GetId() string

func (*ContextImpl) GetService added in v0.19.0 

func (context *ContextImpl) GetService(name string) (*rest_model.ServiceDetail, bool)

func (*ContextImpl) GetServiceForAddr added in v0.19.0 

func (context *ContextImpl) GetServiceForAddr(network, hostname string, port uint16) (*rest_model.ServiceDetail, int, error)

GetServiceForAddr finds the service with intercept that matches best to given address

func (*ContextImpl) GetServiceId added in v0.19.0 

func (context *ContextImpl) GetServiceId(name string) (string, bool, error)

func (*ContextImpl) GetServiceTerminators added in v0.19.0 

func (context *ContextImpl) GetServiceTerminators(serviceName string, offset, limit int) ([]*rest_model.TerminatorClientDetail, int, error)

func (*ContextImpl) GetServices added in v0.19.0 

func (context *ContextImpl) GetServices() ([]rest_model.ServiceDetail, error)

func (*ContextImpl) GetSession added in v0.19.0 

func (context *ContextImpl) GetSession(serviceId string) (*rest_model.SessionDetail, error)

func (*ContextImpl) Listen added in v0.19.0 

func (context *ContextImpl) Listen(serviceName string) (edge.Listener, error)

func (*ContextImpl) ListenWithOptions added in v0.19.0 

func (context *ContextImpl) ListenWithOptions(serviceName string, options *ListenOptions) (edge.Listener, error)

func (*ContextImpl) Metrics added in v0.19.0 

func (context *ContextImpl) Metrics() metrics.Registry

func (*ContextImpl) OnClose added in v0.19.0 

func (context *ContextImpl) OnClose(routerConn edge.RouterConn)

func (*ContextImpl) Reauthenticate added in v0.20.50 

func (context *ContextImpl) Reauthenticate() error

func (*ContextImpl) RefreshApiSessionWithBackoff added in v0.22.30 

func (context *ContextImpl) RefreshApiSessionWithBackoff() error

func (*ContextImpl) RefreshService added in v0.20.145 

func (context *ContextImpl) RefreshService(serviceName string) (*rest_model.ServiceDetail, error)

func (*ContextImpl) RefreshServices added in v0.19.0 

func (context *ContextImpl) RefreshServices() error

func (*ContextImpl) RemoveZitiMfa added in v0.19.0 

func (context *ContextImpl) RemoveZitiMfa(code string) error

func (*ContextImpl) Sessions added in v0.19.0 

func (context *ContextImpl) Sessions() ([]*rest_model.SessionDetail, error)

func (*ContextImpl) SetCredentials added in v0.20.0 

func (context *ContextImpl) SetCredentials(credentials apis.Credentials)

func (*ContextImpl) SetId added in v0.20.7 

func (context *ContextImpl) SetId(id string)

func (*ContextImpl) VerifyZitiMfa added in v0.19.0 

func (context *ContextImpl) VerifyZitiMfa(code string) error

type CtrlClient added in v0.19.0 

type CtrlClient struct {
	*apis.ClientApiClient
	Credentials apis.Credentials

	ApiSessionCertificateDetail rest_model.CurrentAPISessionCertificateDetail
	ApiSessionCsr               x509.CertificateRequest
	ApiSessionCertificate       *x509.Certificate
	ApiSessionPrivateKey        *ecdsa.PrivateKey
	ApiSessionCertInstance      string

	PostureCache *posture.Cache
	ConfigTypes  []string
	// contains filtered or unexported fields
}

CtrlClient is a stateful version of ZitiEdgeClient that simplifies operations

func (*CtrlClient) Authenticate added in v0.19.0 

func (self *CtrlClient) Authenticate() (apis.ApiSession, error)

Authenticate attempts to use authenticate, overwriting any existing ApiSession.

func (*CtrlClient) AuthenticateMFA added in v0.19.0 

func (self *CtrlClient) AuthenticateMFA(code string) error

AuthenticateMFA handles MFA authentication queries may be provided. AuthenticateMFA allows the current identity for their current api session to attempt to pass MFA authentication.

func (*CtrlClient) CreateSession added in v0.19.0 

func (self *CtrlClient) CreateSession(id string, sessionType SessionType) (*rest_model.SessionDetail, error)

CreateSession will attempt to obtain a session token for a specific service id and type.

func (*CtrlClient) EnrollMfa added in v0.19.0 

func (self *CtrlClient) EnrollMfa() (*rest_model.DetailMfa, error)

EnrollMfa will attempt to start TOTP MFA enrollment for the currently authenticated identity.

func (*CtrlClient) EnsureApiSessionCertificate added in v0.19.0 

func (self *CtrlClient) EnsureApiSessionCertificate() error

EnsureApiSessionCertificate will create an ApiSessionCertificate if one does not already exist.

func (*CtrlClient) GetCurrentApiSession added in v0.19.0 

func (self *CtrlClient) GetCurrentApiSession() apis.ApiSession

GetCurrentApiSession returns the current cached ApiSession or nil

func (*CtrlClient) GetCurrentIdentity added in v0.19.0 

func (self *CtrlClient) GetCurrentIdentity() (*rest_model.IdentityDetail, error)

GetCurrentIdentity returns the rest_model.IdentityDetail for the currently authenticated ApiSession.

func (*CtrlClient) GetIdentity added in v0.19.0 

func (self *CtrlClient) GetIdentity() (identity.Identity, error)

GetIdentity returns the identity.Identity used to facilitate authentication. Each identity.Identity instance may provide authentication material in the form of x509 certificates and private keys and/or trusted CA pools.

func (*CtrlClient) GetService added in v0.20.145 

func (self *CtrlClient) GetService(name string) (*rest_model.ServiceDetail, error)

GetService will fetch the specific service requested. If the service doesn't exist, nil will be returned

func (*CtrlClient) GetServiceTerminators added in v0.19.0 

func (self *CtrlClient) GetServiceTerminators(svc *rest_model.ServiceDetail, offset int, limit int) ([]*rest_model.TerminatorClientDetail, int, error)

GetServiceTerminators returns the client terminator details for a specific service.

func (*CtrlClient) GetServices added in v0.19.0 

func (self *CtrlClient) GetServices() ([]*rest_model.ServiceDetail, error)

GetServices will fetch the list of services that the identity of the current ApiSession has access to for dialing or binding.

func (*CtrlClient) GetSession added in v0.19.0 

func (self *CtrlClient) GetSession(id string) (*rest_model.SessionDetail, error)

GetSession returns the full rest_model.SessionDetail for a specific id. Does not function with JWT backed sessions.

func (*CtrlClient) GetSessionFromJwt added in v0.22.6 

func (self *CtrlClient) GetSessionFromJwt(sessionToken string) (*rest_model.SessionDetail, error)

func (*CtrlClient) IsServiceListUpdateAvailable added in v0.19.0 

func (self *CtrlClient) IsServiceListUpdateAvailable() (bool, *strfmt.DateTime, error)

IsServiceListUpdateAvailable will contact the controller to determine if a new set of services are available. Service updates could entail gaining/losing services access via policy or runtime authorization revocation due to posture checks.

func (*CtrlClient) NewApiSessionCertificate added in v0.19.0 

func (self *CtrlClient) NewApiSessionCertificate() error

NewApiSessionCertificate will create a new ephemeral private key used to generate an ephemeral certificate that may be used with the current ApiSession. The generated certificate and private key are scoped to the ApiSession used to create it.

func (*CtrlClient) Refresh added in v0.19.0 

func (self *CtrlClient) Refresh() (apis.ApiSession, error)

Refresh will contact the controller extending the current ApiSession for legacy API Sessions

func (*CtrlClient) RemoveMfa added in v0.19.0 

func (self *CtrlClient) RemoveMfa(code string) error

RemoveMfa will remove the currently enrolled TOTP MFA added by EnrollMfa() and verified by VerifyMfa()

func (*CtrlClient) SendPostureResponse added in v0.19.0 

func (self *CtrlClient) SendPostureResponse(response rest_model.PostureResponseCreate) error

SendPostureResponse creates a posture response (some state data the controller has requested) for services. This information is used to determine runtime authorization access to services via posture checks.

func (*CtrlClient) SendPostureResponseBulk added in v0.19.0 

func (self *CtrlClient) SendPostureResponseBulk(responses []rest_model.PostureResponseCreate) error

SendPostureResponseBulk provides the same functionality as SendPostureResponse but allows multiple responses to be sent in a single request.

func (*CtrlClient) VerifyMfa added in v0.19.0 

func (self *CtrlClient) VerifyMfa(code string) error

VerifyMfa will complete a TOTP MFA enrollment created via EnrollMfa.

type CtxCollection added in v0.20.7 

type CtxCollection struct {
	ConfigTypes []string
	// contains filtered or unexported fields
}

An CtxCollection allows Context instances to be instantiated and maintained as a group. Useful in scenarios where multiple Context instances are managed together. Instead of using ziti.NewContext() like functions, use the function provided on this type to automatically have contexts added as they are created. If ConfigTypes is set, they will be automatically added to any instantiated Context through `New*` functions.

Context instances can be created directly from CtxCollection instances. Doing so automatically adds new Context instances to the CtxCollection:

``` collection := ziti.NewCtxCollection() cfg, err := ziti.NewConfigFromFile(str) ctx, err := collection.NewContext(cfg) //return the ctx and adds it to the collection ```

If more control over Config and Context instantiation is desired before the Context is added to the collection the Add() function can be used:

``` collection := ziti.NewCtxCollection() cfg, err := ziti.NewConfigFromFile(str) ctx, err := ziti.NewContext(cfg) collection.Add(ctx) //manual collection add ``` 

var DefaultCollection *CtxCollection

Deprecated: DefaultCollection is deprecated and is included for legacy support. It powers two other deprecated functions: `ForAllContext() and and `LoadContext()` which rely on it. The intended replacement is for implementations that wish to have this functionality to use NewSdkCollection() or NewSdkCollectionFromEnv() on their own.

func NewSdkCollection added in v0.20.7 

func NewSdkCollection() *CtxCollection

NewSdkCollection creates a new empty collection.

func NewSdkCollectionFromEnv added in v0.20.7 

func NewSdkCollectionFromEnv(envVariable string) *CtxCollection

NewSdkCollectionFromEnv will create an empty CtxCollection and then attempt to populate it from configuration files provided in a semicolon separate list of file paths retrieved from an environment variable.

func (*CtxCollection) Add added in v0.20.7 

func (set *CtxCollection) Add(ctx Context)

Add allows the arbitrary idempotent inclusion of a Context in the current collection. If a Context with the same id as an existing Context is added and is a different instance, the original is closed and removed.

func (*CtxCollection) ForAll added in v0.20.7 

func (set *CtxCollection) ForAll(f func(ctx Context))

ForAll call the provided function `f` on each Context.

func (*CtxCollection) NewContext added in v0.20.7 

func (set *CtxCollection) NewContext(cfg *Config) (Context, error)

NewContext is the same as ziti.NewContext but will also add the resulting context to the current collection.

func (*CtxCollection) NewContextFromFile added in v0.20.7 

func (set *CtxCollection) NewContextFromFile(file string) (Context, error)

NewContextFromFile is the same as ziti.NewContextFromFile but will also add the resulting context to the current collection.

func (*CtxCollection) NewContextFromFileWithOpts added in v0.20.7 

func (set *CtxCollection) NewContextFromFileWithOpts(file string, options *Options) (Context, error)

NewContextFromFileWithOpts is the same as ziti.NewContextFromFileWithOpts but will also add the resulting context to the current collection.

func (*CtxCollection) NewContextWithOpts added in v0.20.7 

func (set *CtxCollection) NewContextWithOpts(cfg *Config, options *Options) (Context, error)

NewContextWithOpts is the same as ziti.NewContextWithOpts but will also add the resulting context to the current collection.

func (*CtxCollection) NewDialer added in v0.20.7 

func (set *CtxCollection) NewDialer() Dialer

NewDialer will return a dialer that will iterate over the Context instances inside the collection, searching for the context that best matches the service.

If a matching service is not found, an error is returned. Matching is based on Match() logic in edge.InterceptV1Config.

func (*CtxCollection) NewDialerWithFallback added in v0.20.7 

func (set *CtxCollection) NewDialerWithFallback(ctx context.Context, fallback Dialer) Dialer

NewDialerWithFallback will return a dialer that will iterate over the Context instances inside the collection, searching for the context that best matches the service.

If a matching service is not found, a dial is attempted using the fallback dialer. Matching is based on Match() logic in edge.InterceptV1Config.

func (*CtxCollection) Remove added in v0.20.7 

func (set *CtxCollection) Remove(ctx Context)

Remove removes the supplied Context from the collection. It is not closed or altered in any way.

func (*CtxCollection) RemoveById added in v0.20.7 

func (set *CtxCollection) RemoveById(id string)

RemoveById removes a context by its string id. It is not closed or altered in any way.

type DialOptions added in v0.13.47 

type DialOptions struct {
	ConnectTimeout time.Duration
	Identity       string
	AppData        []byte
}

func (DialOptions) GetConnectTimeout added in v0.13.47 

func (d DialOptions) GetConnectTimeout() time.Duration

type Dialer added in v0.17.0 

type Dialer interface {
	Dial(network, address string) (net.Conn, error)
}

func NewDialer deprecated added in v0.17.0 

func NewDialer() Dialer

Deprecated: NewDialer will return a dialer from the DefaultCollection that will iterate over the Context instances inside the collection searching for the context that best matches the service.

It is suggested that implementations construct their own CtxCollection and use the NewDialer/NewDialerWithFallback present there.

If a matching service is not found, an error is returned. Matching is based on Match() logic in edge.InterceptV1Config.

func NewDialerWithFallback deprecated added in v0.17.0 

func NewDialerWithFallback(ctx context.Context, fallback Dialer) Dialer

Deprecated: NewDialerWithFallback will return a dialer from the DefaultCollection that will iterate over the Context instances inside the collection searching for the context that best matches the service.

It is suggested that implementations construct their own CtxCollection and use the NewDialer/NewDialerWithFallback present there.

If a matching service is not found, a dial is attempted with the fallback dialer. Matching is based on Match() logic in edge.InterceptV1Config.

type EnrollmentClaims added in v0.20.0 

type EnrollmentClaims struct {
	jwt.RegisteredClaims
	EnrollmentMethod string            `json:"em"`
	Controllers      []string          `json:"ctrls"`
	SignatureCert    *x509.Certificate `json:"-"`
}

func (*EnrollmentClaims) EnrolmentUrl added in v0.20.0 

func (t *EnrollmentClaims) EnrolmentUrl() string

type Eventer added in v0.20.50 

type Eventer interface {
	// AddServiceAddedListener adds an event listener for the EventServiceAdded event and returns a function to remove
	// the listener. It is emitted any time a new service definition is received. The service detail provided is the
	// service that was added.
	AddServiceAddedListener(func(Context, *rest_model.ServiceDetail)) func()

	// AddServiceChangedListener adds an event listener for the EventServiceChanged event and returns a function to remove
	// the listener. It is emitted any time a known service definition is updated with new values. The service detail
	// provided is the service that was changed.
	AddServiceChangedListener(func(Context, *rest_model.ServiceDetail)) func()

	// AddServiceRemovedListener adds an event listener for the EventServiceRemoved event and returns a function to remove
	// the listener. It is emitted any time known service definition is no longer accessible. The service detail
	// provided is the service that was removed.
	AddServiceRemovedListener(func(Context, *rest_model.ServiceDetail)) func()

	// AddRouterConnectedListener adds an event listener for the EventRouterConnected event and returns a function to remove
	// the listener. It is emitted any time a router connection is established. The strings provided are router name and connection address.
	AddRouterConnectedListener(func(ztx Context, name string, addr string)) func()

	// AddRouterDisconnectedListener adds an event listener for the EventRouterDisconnected event and returns a function to remove
	// the listener. It is emitted any time a router connection is closed. The strings provided are router name and connection address.
	AddRouterDisconnectedListener(func(ztx Context, name string, addr string)) func()

	// AddMfaTotpCodeListener adds an event listener for the EventMfaTotpCode event and returns a function to remove
	// the listener. It is emitted any time the currently authenticated API Session requires an MFA TOTP Code for
	// authentication. The authentication query detail and an MfaCodeResponse function are provided. The MfaCodeResponse
	// should be invoked to answer the MFA TOTP challenge.
	//
	// Authentication challenges for MFA are modeled as authentication queries, and is provided to listeners for
	// informational purposes. This event handler is a specific authentication query that responds to the internal Ziti
	// MFA TOTP challenge only. All authentication queries, including MFA TOTP ones, are also available through
	// AddAuthQueryListener, but does not provide typed response callbacks.
	AddMfaTotpCodeListener(func(Context, *rest_model.AuthQueryDetail, MfaCodeResponse)) func()

	// AddAuthQueryListener adds an event listener for the EventAuthQuery event and returns a function to remove
	// the listener. The event is emitted any time the current API Session is required to pass additional authentication
	// challenges - which enabled MFA functionality.
	AddAuthQueryListener(func(Context, *rest_model.AuthQueryDetail)) func()

	// AddAuthenticationStatePartialListener adds an event listener for the EventAuthenticationStatePartial event and
	// returns a function to remove the listener. Partial authentication occurs when there are unmet authentication
	// queries - which are defined by the authentication policy associated with the identity. The
	// EventAuthQuery or EventMfaTotpCode events will also coincide with this event. Additionally, the authentication
	// queries that triggered this event are available on the API Session detail in the `AuthQueries` field.
	//
	// In the partially authenticated state, a context will have reduced capabilities. It will not be able to
	// update/list services, create service sessions, etc. It will be able to enroll in TOTP MFA and answer
	// authentication queries.
	//
	// One all authentication queries are answered, the EventAuthenticationStateFull event will be emitted. For
	// identities that do not have secondary authentication challenges associated with them, this even will never
	// be emitted.
	AddAuthenticationStatePartialListener(func(Context, edge_apis.ApiSession)) func()

	// AddAuthenticationStateFullListener adds an event listener for the EventAuthenticationStateFull event and
	// returns a function to remove the listener. Full authentication occurs when there are no unmet authentication
	// queries - which are defined by the authentication policy associated with the identity. In a fully authenticated
	// state, the context will be able to perform all client actions.
	AddAuthenticationStateFullListener(func(Context, edge_apis.ApiSession)) func()

	// AddAuthenticationStateUnauthenticatedListener adds an event listener for the EventAuthenticationStateUnauthenticated
	// event and returns a function to remove the listener. The unauthenticated state occurs when the API session
	// currently being used is no longer valid. API Sessions may become invalid due to prolonged inactivity due to
	// network disconnection, the host machine entering a power saving/sleep mode, etc. It may also occur due to
	// administrative action such as removing specific API Sessions or removing entire identities.
	//
	// The API Session detail provided to the listener may be nil. If it is not nil, the API Session detail is the
	// now expired API Session.
	AddAuthenticationStateUnauthenticatedListener(func(Context, edge_apis.ApiSession)) func()

	// AddListener is an alias for .On(eventName, listener).
	AddListener(events.EventName, ...events.Listener)

	// EventNames returns an array listing the events for which the emitter has registered listeners.
	// The values in the array will be strings.
	EventNames() []events.EventName

	// GetMaxListeners returns the max listeners for this emmiter
	// see SetMaxListeners
	GetMaxListeners() int

	// ListenerCount returns the length of all registered listeners to a particular event
	ListenerCount(events.EventName) int

	// Listeners returns a copy of the array of listeners for the event named eventName.
	Listeners(events.EventName) []events.Listener

	// On registers a particular listener for an event, func receiver parameter(s) is/are optional
	On(events.EventName, ...events.Listener)

	// Once adds a one-time listener function for the event named eventName.
	// The next time eventName is triggered, this listener is removed and then invoked.
	Once(events.EventName, ...events.Listener)

	// RemoveAllListeners removes all listeners, or those of the specified eventName.
	// Note that it will remove the event itself.
	// Returns an indicator if event and listeners were found before the remove.
	RemoveAllListeners(events.EventName) bool

	// RemoveListener removes given listener from the event named eventName.
	// Returns an indicator whether listener was removed
	RemoveListener(events.EventName, events.Listener) bool
}

Eventer provides types methods for adding event listeners to a context and exposes some weakly typed functions that are useful for debugging/testing.

type KeyAlgVar added in v0.20.0 

type KeyAlgVar string

func (*KeyAlgVar) EC added in v0.20.0 

func (f *KeyAlgVar) EC() bool

func (*KeyAlgVar) Get added in v0.20.0 

func (f *KeyAlgVar) Get() string

func (*KeyAlgVar) RSA added in v0.20.0 

func (f *KeyAlgVar) RSA() bool

func (*KeyAlgVar) Set added in v0.20.0 

func (f *KeyAlgVar) Set(value string) error

func (*KeyAlgVar) String added in v0.20.0 

func (f *KeyAlgVar) String() string

func (*KeyAlgVar) Type added in v0.20.0 

func (f *KeyAlgVar) Type() string

type ListenEventObserver added in v0.21.2 

type ListenEventObserver interface {
	Notify(eventType ListenEventType)
}

type ListenEventType added in v0.21.2 

type ListenEventType int
const (
	ListenerAdded       ListenEventType = 1
	ListenerEstablished ListenEventType = 2
	ListenerRemoved     ListenEventType = 3
)

type ListenOptions added in v0.13.47 

type ListenOptions struct {
	// Initial static cost assigned to terminators for this service
	Cost uint16

	// Initial precedence assigned to terminators for this service
	Precedence Precedence

	// When using WaitForNEstablishedListeners, how long to wait before giving
	// if N listeners can't be established
	ConnectTimeout time.Duration

	// Maximum number of terminators to establish. If a value less than 1 is provided,
	// will default to 1. At most one terminator will be established per available
	// edge router. If both MaxConnections and MaxTerminators have non-zer values,
	// the value from MaxTerminators will be used
	//
	// Deprecated: used MaxTerminators instead.
	MaxConnections int

	// Maximum number of terminators to establish. If a value less than 1 is provided,
	// will default to 1. At most one terminator will be established per available
	// edge router. If both MaxConnections and MaxTerminators have non-zer values,
	// the value from MaxTerminators will be used
	MaxTerminators int

	// Instance name to assign to terminators for this service
	Identity string

	// Assign the name of the edge identity hosting the service to the terminator's instance name
	// Overrides any name specified using the Identity field in ListenOptions
	BindUsingEdgeIdentity bool

	// If set to true, requires that AcceptEdge is called on the edge.Listener
	ManualStart bool

	// Wait for N listeners before returning from the Listen call. By default it will return
	// before any listeners have been established.
	WaitForNEstablishedListeners uint
}

func DefaultListenOptions added in v0.13.47 

func DefaultListenOptions() *ListenOptions

type MfaCodeResponse added in v0.20.50 

type MfaCodeResponse func(code string) error

MfaCodeResponse is a handler used to return a string (TOTP) code

type Options added in v0.15.17 

type Options struct {
	// Service refresh interval. May not be less than 1 second
	RefreshInterval time.Duration

	// Edge session refresh interval. Edge session only need to be refreshed if the list of available
	// edge routers has changed. This should be a relatively rare occurrence. If a dial fails, the
	// edge session will be refreshed regardless.
	// May not be less than 1 second
	SessionRefreshInterval time.Duration

	// Deprecated: OnContextReady is a callback that is invoked after the first successful authentication request. It
	// does not delineate between fully and partially authenticated API Sessions. Use context.AddListener() with the events
	// EventAuthenticationStateFull, EventAuthenticationStatePartial, EventAuthenticationStateUnAuthenticated instead.
	OnContextReady func(ctx Context)

	// Deprecated: OnServiceUpdate is a callback that is invoked when a service changes its definition.
	// Use `zitiContext.AddListener(<eventName>, handler)` where `eventName` may be EventServiceAdded, EventServiceChanged, EventServiceRemoved.
	OnServiceUpdate     serviceCB
	EdgeRouterUrlFilter func(string) bool
}

type Precedence added in v0.13.47 

type Precedence byte

func GetPrecedenceForLabel added in v0.15.3 

func GetPrecedenceForLabel(p string) Precedence

func (Precedence) String added in v0.15.3 

func (p Precedence) String() string

type ServiceEventType added in v0.15.17 

type ServiceEventType string

type SessionType added in v0.19.0 

type SessionType rest_model.DialBind

type Versions added in v0.20.0 

type Versions struct {
	Api           string `json:"api"`
	EnrollmentApi string `json:"enrollmentApi"`
}

Source Files

View all Source files

Directories

Path Synopsis
network
posture

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.