Ziti

@objc
public class Ziti : NSObject, ZitiUnretained

This is the main entry point for interacting with Ziti, and provides a Swift-friendly way to access the Ziti C SDK

Configure Ziti with a ZitiIdentity. A ZitiIdentity can be created by enrolling with using a one-time JWT. See Ziti.enroll(_:_:). The ZitiIdentity can also be configured as part of Ziti.init(fromFile:)and other Zitiinitializers.

Ziti uses a loop to process events, similar toFoudation‘s Runloop (though implemented using libuv). Start Ziti processing via the Ziti.run(_:) method, which enters an infinate loop processing Ziti events until Ziti.shutdown() is called. Tthe Ziti.perform(_:) method supports scheduling work to be run on this thread and can be called safely from other threads.

See

See also:
  • ztx

    Opaque reference to Ziti SDK C context

    Declaration

    Swift

    public var ztx: OpaquePointer?

  • received first event from C sdk.

    Declaration

    Swift

    public var eventReceived: Bool

  • Access to the ZitiTunnel managing this instance (if applicable)

    Declaration

    Swift

    public weak var zitiTunnel: ZitiTunnel?

  • Arbitrary data user can attach to a Ziti instance. This dictionary is not used internally and is completely under the control of the user.

    Declaration

    Swift

    @objc
public var userData: [String : Any]

  • Type used for escaping closure called follwing initialize of Ziti connectivity

    Declaration

    Swift

    public typealias InitCallback = (_ error: ZitiError?) -> Void

    Parameters

    error

    ZitiError containing error information on failed initialization attempt

  • Type used for escaping closure called when ZitiEvent is received

    Declaration

    Swift

    public typealias EventCallback = (_ event: ZitiEvent?) -> Void

    Parameters

    event

    ZitiEvent containing event information

  • Type used for closure called for an operation to be performed on the loop

    Declaration

    Swift

    public typealias PerformCallback = () -> Void

  • Type used for debug dump

    Declaration

    Swift

    public typealias ZitiDumpPrinter = (_ msg: String) -> Int32

    Parameters

    msg

    debug string

    Return Value

    number of characters printed

  • Ziti constant indicating OK status from Ziti C SDK call

    Declaration

    Swift

    public static let ZITI_OK: Int

  • Ziti controller is unavailable

    Declaration

    Swift

    public static let ZITI_CONTROLLER_UNAVAILABLE: Int

  • Ziti context is disabled

    Declaration

    Swift

    public static let ZITI_DISABLED: Int

  • Ziti constant indication service is unavailable from Ziti C SDK call

    Declaration

    Swift

    public static let ZITI_SERVICE_UNAVAILABLE: Int

  • Ziti constant indicating an indentity is allowed to dial a particular service

    Declaration

    Swift

    public static let ZITI_CAN_DIAL: Int

  • Ziti constant indicating an indentity is allowed to bind a particular service

    Declaration

    Swift

    public static let ZITI_CAN_BIND: Int

  • Convenience function to convert Ziti error status to String

    Declaration

    Swift

    public class func zitiErrorString(status: Int32) -> String
  • id

    Identity associated with this instance of Ziti

    Declaration

    Swift

    public var id: ZitiIdentity

Initializers

  • Initialize Ziti with a ZitiIdentity stored in a JSON file.

    A typical usage of Ziti is to enroll using Ziti.enroll(_:_:), store the resulting file on disk, and use that file for subsequent creations of objects of class Ziti. The ZitiIdentity contains the information needed to access the Keychain for stored identity information (keys and identity certificates).

    Declaration

    Swift

    @objc
public init?(fromFile initFile: String)

    Parameters

    fromFile

    file containing JSON representation of a ZitiIdentity

    Return Value

    A Ziti object or nilon failure to load from file

  • Initialize Ziti with information needed for a ZitiIdentity.

    The ZitiIdentity contains the information needed to access the Keychain for stored identity information (keys and identity certificates).

    Declaration

    Swift

    @objc
public init(_ id: String, _ ztAPI: String, name: String?, caPool: String?)

    Parameters

    id

    Usually the sub field from the one-time enrollment JWT. Used by Ziti to store and retrieve identity-related items in the Keychain`
    ztAPI

    scheme, host, and port used to communicate with Ziti controller
    name

    name assocaited with this identity in Ziti.
    caPool

    CA pool verified as part of enrollment that can be used to establish trust with of the Ziti controller

  • Initialize Ziti with a ZitiIdentity.

    Declaration

    Swift

    @objc
public init(withId zid: ZitiIdentity)

    Parameters

    zid

    the ZitiIdentity containing the information needed to access the Keychain for stored identity information (keys and identity certificates).

  • Initilize Ziti with an externally supplied uv_loop.

    This can be useful when an application needs to manage multiple ZitiIdentitys and share a single uv_loop In this scenario, the loop is expected to execute outside of the run(:_) method.

    Declaration

    Swift

    public init(zid: ZitiIdentity, loopPtr: ZitiRunloop)

    Parameters

    zid

    the ZitiIdentity containing the information needed to access the Keychain for stored identity information (keys and identity certificates).
    loop

    the externanally supplied uv_loop

  • Initilize Ziti for use with a ZitiTunnel instance

    This can be useful when an application needs to manage multiple ZitiIdentitys and share a single ZitiTunnel, which manages running this instance

    Declaration

    Swift

    public init(zid: ZitiIdentity, zitiTunnel: ZitiTunnel)

    Parameters

    zid

    the ZitiIdentity containing the information needed to access the Keychain for stored identity information (keys and identity certificates).
    loop

    the externanally supplied uv_loop

  • Helper class to manage private loop constructs. An object of this class can be used when holding a shared instane of the loop to be used among multiple identities

    See more

    Declaration

    Swift

    @objc
public class ZitiRunloop : NSObject

  • wrapper to execute uv_run (blocking)

    Declaration

    Swift

    public class func executeRunloop(loopPtr: ZitiRunloop) -> Int32

  • Remove keys and certificates created during enroll() from the keychain

    Declaration

    Swift

    @objc
public func forget()

  • Provide app information to Ziti Controller

    Declaration

    Swift

    @objc
public static func setAppInfo(_ appId: String, _ appVersion: String)

    Parameters

    appId

    Name (e.g., BundleIdentifier) of application
    appVersion

    Version of application

Enrollment

  • Type used for escaping closure called following an enrollment attempt

    Declaration

    Swift

    public typealias EnrollmentCallback = (_ zid: ZitiIdentity?, _ error: ZitiError?) -> Void

    Parameters

    zid

    ZitiIdentity returned on successful enrollment. nil on failed attempt
    error

    ZitiError containing error information on failed enrollment attempt

  • Enroll a Ziti identity using a JWT file

    Enrollment consists of parsing the JWT to determine controller address, verifying the given JWT was signed with the controller’s public key, downloading the CA chain from the controller (to be used as part of establishing trust in future interactions with the controller), generating a private key (stored in the Keychain), creating a Certificate Signing Request (CSR), sending the CSR to the controller and receiving our signed certificate. This certificate is stored in the Keychain and required for future interactions with the controller.

    A ZitiIdentity is passed back in the EnrollmentCallback that can be stored and using to create an instance of Ziti

    Declaration

    Swift

    @objc
public static func enroll(_ jwtFile: String, _ enrollCallback: @escaping EnrollmentCallback)

    Parameters

    jwtFile

    file containing one-time JWT token for enrollment
    cb

    callback called indicating status of enrollment attempt

Ziti Operational Methods

  • Convienience method for calling run(_:_) with nil posture check support

    See

    See also:

    Declaration

    Swift

    @objc
public func run(_ initCallback: @escaping InitCallback)

    Parameters

    initCallback

    called when intialization with the Ziti controller is complete

  • Execute a permanant loop processing data from all attached sources (including Ziti)

    Start Ziti processing via this method. All Ziti processing occurs in the same thread as this call and all callbacks run on this thread. Use the perform(_:) to schedule work to be run on this thread. perform(_:) can be called safely from other threads.

    Note that if a uv_loop is specified during Ziti initialization, running the loop is expected to occur outside of this call. In this scenario, this method initializes Ziti for connections using the configured ZitiIdentity and blocks until the calling thread is cancelled.

    See

    See also:

    Declaration

    Swift

    @objc
public func run(_ postureChecks: ZitiPostureChecks?, _ initCallback: @escaping InitCallback)

    Parameters

    postureChecks

    provide (optional) support for posture checks
    initCallback

    called when intialization with the Ziti controller is complete

  • Create a new thread forrun(_:)` and return

    Declaration

    Swift

    @objc
public func runAsync(_ initCallback: @escaping InitCallback)

    Parameters

    initCallback

    called when intialization with the Ziti controller is complete

  • Create a new thread forrun(_:)` and return

    Declaration

    Swift

    @objc
public func runAsync(_ postureChecks: ZitiPostureChecks?, _ initCallback: @escaping InitCallback)

    Parameters

    postureChecks

    provide (optional) support for posture checking
    initCallback

    called when intialization with the Ziti controller is complete

  • Shutdown the Ziti processing started via run(_:). This will cause the loop to exit once all scheduled activity on the loop completes

    Declaration

    Swift

    @objc
public func shutdown()

  • Create a ZitiConnection object

    This method will only be able to create connections after Ziti has started running (see run(_:))

    Declaration

    Swift

    @objc
public func createConnection() -> ZitiConnection?

    Return Value

    An intialized ZitiConnection or nil on error

  • Get the version of the wrapped Ziti C SDK

    Declaration

    Swift

    public func getCSDKVersion() -> (version: String, revision: String, buildDate: String)

    Return Value

    tuple of version, revision, buildDate

  • Get the version of the connected controller

    Declaration

    Swift

    public func getControllerVersion() -> (version: String, revision: String, buildDate: String)

    Return Value

    tuple of version, revision, buildDate or (“”, “”, “”) if Ziti is not currently running

  • Retrieve current transfer rates

    Rates are in bytes / second, calculated using 1 minute EWMA

    Declaration

    Swift

    public func getTransferRates() -> (up: Double, down: Double)

  • Notifies that the host has undergone a state change: either woke or unlocked.

    Declaration

    Swift

    public func endpointStateChange(_ woken: Bool, _ unlocked: Bool)

  • Check if this instance of Ziti is enabled. This method should only be called from the same thread as the run loop (e.g., as part of a perform(_:) operation), and not before InitCallback is triggered.

    Declaration

    Swift

    public func isEnabled() -> Bool

    Return Value

    Bool indicating if this Ziti instance is enabled, or false if called before InitCallback has been triggered

  • Enable or disable this Ziti instance. This method should only be called from the same thread as the run loop (e.g., as part of a perform(_:) operation), and not before InitCallback is triggered.

    Declaration

    Swift

    public func setEnabled(_ enabled: Bool)

    Parameters

    enabled

    Boolean indicating to enable or disable this Zit iinstance

  • Output debugging information to supplied callback. The output from this command may be useful when submitting issues.

    This method must be called in an interation of the loop

    Declaration

    Swift

    @objc
public func dump(_ printer: @escaping ZitiDumpPrinter)

  • Perform an operation in an upcoming iteration of the loop

    Ziti is not threadsafe. All operations must run on the same thread as run(_:). Use the perform(_:) method to execute the operation on the Ziti thread

    Declaration

    Swift

    @objc
public func perform(_ op: @escaping PerformCallback)

    Parameters

    op

    Escaping closure that executes on the same thread as run(_:)

  • User supplied callback for timer

    Declaration

    Swift

    public typealias TimerCallback = (OpaquePointer) -> Void

  • Schedule a timer

    Declaration

    Swift

    @objc
public func startTimer(_ timeout: UInt64, _ repeatTime: UInt64, _ op: @escaping TimerCallback)

  • Remove and destroy a timer

    Declaration

    Swift

    @objc
public func endTimer(_ h: OpaquePointer)

    Parameters

    h

    Opaque pointer to the timer handle available in TimerCallback

  • Register a closure to be called when events are received

    These callbacks should be registerd before run(_:) is executed or the intiali events will be missed

    Declaration

    Swift

    public func registerEventCallback(_ cb: @escaping EventCallback, _ mask: UInt32 = 0xffff)

    Parameters

    cb

    The closre to be executed

MFA

  • Type definition of MFA enrollment callback

    Declaration

    Swift

    public typealias MfaEnrollCallback = (_ ziti: Ziti, _ status: Int32, _ mfaEnrollment: ZitiMfaEnrollment?) -> Void

  • Enroll in MFA

    Declaration

    Swift

    public func mfaEnroll(_ cb: @escaping MfaEnrollCallback)

    Parameters

    cb

    Callback invoked on completion of enrollment attempt

  • Type definition of callback method for MFA operations

    Declaration

    Swift

    public typealias MfaCallback = (_ ziti: Ziti, _ status: Int32) -> Void

  • Remove MFA from this identity

    Declaration

    Swift

    public func mfaRemove(_ code: String, _ cb: @escaping MfaCallback)

    Parameters

    code

    TOTP code for MFA
    cb

    Callback invoked on completion of the attempt

  • Verify an MFA enrollment attempt

    Declaration

    Swift

    public func mfaVerify(_ code: String, _ cb: @escaping MfaCallback)

    Parameters

    code

    TOTP code for MFA
    cb

    Callback invoked on completion of the attempt

  • Type definition of callback method for attempted retrieval or MFA recovery codes

    Declaration

    Swift

    public typealias MfaRecoveryCodesCallback = (_ ziti: Ziti, _ status: Int32, _ codes: [String]) -> Void

  • Retrieve MFA recovery codes

    Declaration

    Swift

    public func mfaGetRecoveryCodes(_ code: String, _ cb: @escaping MfaRecoveryCodesCallback)

    Parameters

    code

    TOTP code for MFA
    cb

    Callback invoked on completion of the attempt

  • Generate new MFA recovery codes

    Declaration

    Swift

    public func mfaNewRecoveryCodes(_ code: String, _ cb: @escaping MfaRecoveryCodesCallback)

    Parameters

    code

    TOTP code for MFA
    cb

    Callback invoked on completion of the attempt

  • Authenticate via MFA

    Declaration

    Swift

    public func mfaAuth(_ code: String, _ cb: @escaping MfaCallback)

    Parameters

    code

    TOTP code for MFA
    cb

    Callback invoked on completion of the attempt