Proxy Server Authentication
The C SDK supports the following authentication options for communicating with ThingWorx Platform through a proxy server:
• No authentication
• Basic authentication
• Digest authentication
• NTLM
As of v.2.2.0, the C SDK uses a callback function to retrieve a basic password or a digest when it needs to authenticate with a proxy server. The twPasswords.h file provides the signatures for this callback function:
typedef void (*twPasswdCallbackFunction)(char * passwdBuffer, unsigned int maxPasswdSize);
where passwdBuffer allocates a buffer in which to copy the password or digest and maxPasswdSize is the size of the buffer. Do not copy a password or digest that is longer than maxPasswdSize into passwdBuffer.
 |
In production, this callback should obtain a password or digest from a secure source.
|
Initializing with Proxy Server Configuration
As of C SDK v.2.2.8, using the twApi_InitializeWithProxy() function is the preferred way to set up proxy information. Use the following function instead of twApi_Initialize() to set up communication through a proxy server:
twApi_InitializeWithProxy(char * host, uint16_t port, char * resource,
twPasswdCallbackFunction app_key_function, char * gatewayName,
uint32_t messageChunkSize, uint16_t frameSize, char autoreconnect,
char * proxyHost, uint16_t proxyPort, char * proxyUser,
twPasswdCallbackFunction proxyPassCallback)
 |
For publishing purposes, line breaks have been added to the lines above. To copy and paste into your application, first copy and paste into a plain text editor and remove the line breaks. Then copy and paste the function into your code.
|
The parameters for twApi_InitializeWithProxy() are the same as those for twApi_Initialize, with four additional parameters to specify the proxy information. The following table describes the parameters you can specify:
|
Parameter
|
Description
|
|---|---|
|
host
|
The host name of the ThingWorx Platform to connect to.
|
|
port
|
The TCP port number to used by the ThingWorx Platform for client connections.
|
|
resource
|
The ThingWorx Platform resource. This value should always be /ThingWorx/WS, unless it has been changed by the platform.
|
|
app_key_function
|
A pointer to a function that is called whenever the client must provide an application key for authentication. You must implement this function and pass a pointer to it to initialize the API. This function must be of type twPasswdCallbackFunction and should have a formate like the one shown here:
myPasswordCallback(char* passwdBuffer,unsigned int maxPasswordLength); The implementation of this function must fill passwdBuffer with the current application key. The application key is defined on the ThingWorx Platform. It represents a user and is used as an authentication token.
|
|
gatewayName
|
An optional name to register with if the application is acting as a gateway for multiple Things..
|
|
messageChunkSize
|
The maximum size of each chunk of a WebSocket message, in bytes. This value should match the value set on the ThingWorx Platform. The default value is 8192 bytes and should not be exceeded.
|
|
frameSize
|
The maximum size in bytes of a WebSocket frame. Typically matches the value of messageChunkSize.
|
|
autoreconnect
|
If set to TRUE, enables automatic reconnection to the ThingWorx Platform if a connection is lost.
|
|
proxyHost
|
The host name of the proxy server to use when connecting to the ThingWorx Platform.
|
|
proxyPort
|
The number of the port on the proxy server to use.
|
|
proxyUser
|
If the proxy server requires Basic or Digest authentication, provide a user name to present to the proxy server on connection. These credentials are only for the proxy server. They are not passed beyond the proxy server.
|
|
passwdCallback
|
This is a pointer to a function that is called when connecting to a password-protected server. This function must be of type twPasswdCallbackFunction and should have a format similar to the following:
myPasswordCallback(char* passwdBuffer, unsingned int maxPasswordLength); The implementation of this function must fill passwdBuffer with the proxy password.
For a password, you must use the twPasswordCallbackFunction to obtain an encrypted password from a source of your choosing and store the encrypted password in passwdCallback. For example, your application might request the credentials in a user interface or command line interface.
The C SDK retrieves and uses the password when it must access the proxy server. It then zeroes out the passwdCallback and discards it from memory. Refer to Initializing
the Tunnel Manager (Optional).
|
You can still call twApi_Initialize and twApi_SetProxyInfo separately. However, this is not recommended because it can cause a DNS failure and force a disconnect when using a domain name for the platform. These functions are defined in the source file, twApi.h. Here are the signatures for these functions:
twApi_Initialize
int twApi_Initialize(char * host, uint16_t port, char * resource,
twPasswdCallbackFunction app_key_function, char * gatewayName,
uint32_t messageChunkSize, uint16_t frameSize, char autoreconnect);
twApi_SetProxyInfo
int twApi_SetProxyInfo(char * proxyHost, uint16_t proxyPort,
char * proxyUser, twPasswdCallbackFunction proxyPassCallback);
Tunneling with Proxy Servers
When using a proxy server, you must set both the initial proxy as shown above using twApi_SetProxyInfo and the proxy for tunneling with twTunnelManager_SetProxyInfo. If you set only the initial proxy and not the tunneling proxy, the connection succeeds but the tunneling fails. Refer to Tunneling with Proxy Servers for more information about setting up the proxy server for tunneling.