.NET SDK: TunnelManager Class
The .NET SDK has full support for application tunneling. Application tunnels allow for secure, firewall-transparent tunneling of TCP client/server applications such as VNC and SSH. To use the tunneling capabilities of this SDK, you must initialize the tunnel manager singleton.
TunnelManager Singleton
The TunnelManager singleton may be retrieved by using the getTunnelManager() method on the ConnectedThingClient class, and initialized by calling the Initialize() method using a ClientConfigurator object.
When new tunnels are requested by the ThingWorx Platform, the tunnel manager creates a new tunnel. These tunnels establish an independent WebSocket back to the platform. By default, these websockets connect back to the same host/port that the API uses, as well as the same TLS certificate validation criteria. You can override these defaults by setting the appropriate values in the ClientConfigurator object passed to the Initialize() method.
Methods of the TunnelManager Class
The following methods are available on the TunnelManager class:
• Initialize — Initializes the TunnelManager.
• Shutdown — Shuts down the TunnelManager.
• StopTunnel — Shuts down a specified tunnel. This method takes the following properties:
◦ id — The Id of the tunnel to shutdown.
◦ msg — Message to be logged.
• StopAllTunnels — Shuts down all tunnels.
• TunnelStateChanged — Event triggered when the state of a tunnel changes
• UpdateTunnelServerInfo — Updates the host, port and application key that the tunnels use to connect to the ThingWorx Platform that is requesting a tunnel. This method takes the following properties:
◦ host — The new host name to use.
◦ port — The new port to use.
◦ appkey — A new application key to authenticate against the platform requesting the tunnel. The only authentication you can use for tunneling is an application key. Refer to the next section for information on using callbacks to obtain the application key.
Additional Settings for Tunneling
The following TunnelManagerInfo properties can be set in the ClientConfigurator to override the default settings of the TunnelManager:
• TunnelManagerInfo.Host — The IP address or domain name of the ThingWorx platform that requests the tunnel.
• TunnelManagerInfo.Port — The number of the port to use for the tunnel on the server.
• TunnelManagerInfo.Claims — The application key to use to authenticate against the platform that requests the tunnel. For example:
TwPasswordDelegate appkeyCallback = myApplicationKeyCallback;
config.TunnelManagerInfo.Claims = SecurityClaims.fromAppKeyCallback(appKeyCallback)
 |
In production, the callback should obtain an application key or other required PASSWORD from a secure source.
|
Refer to .NET SDK: SecurityClaims Class for more information.
• TunnelManagerInfo.EnableFipsMode — If you must use FIPS mode, set this property to true. The .NET SDK supports OpenSSL v.1.1.1j, as of v.5.8.3. This version of OpenSSL does not support FIPS mode. If you require FIPS mode, you need to obtain a version of OpenSSL that supports FIPS mode. For security reasons, using older versions of OpenSSL is not recommended.
• TunnelManagerInfo.AllowSelfSignedCertificates — Set this property to true if, for development purposes only, you need to use self-signed certificates. Set this property to false for production use.
• TunnelManagerInfo.DisableCertValidation — Set this property to true to tell the SSL/TLS library that it should not validate certificates.
 |
In a production environment, it is strongly recommended that, for security reasons, you set both AllowSelfSignedCertificates and DisableCertValidation to false.
|
• TunnelManagerInfo.X509Fields — Supply the fields of an X.509 certificate to be validated. Note that null values are not checked against the received certificate, while non-null values are checked. The following fields are typically validated:
◦ Subject.cn — The common name of the subject in the certificate.
◦ Subject.o — The organization of the subject in the certificate.
◦ Subject.ou — The organizational unit of the subject in the certificate.
◦ Issuer.cn — The common name of the issuer in the certificate.
◦ Issuer.o — The organization of the issuer in the certificate.
◦ Issuer.ou — The organizational unit of the issuer in the certificate.