ThingWorx Edge C SDK > Using SSL/TLS for Security > Setting Up Secure Connections
  
Setting Up Secure Connections
By default the C SDK is set up to ensure the most secure connection possible, using the OpenSSL 1.0.2q library as the default library in the non-FIPS distribution bundles of the SDK and OpenSSL 1.0.2l in the FIPS versions of the SDK.
* 
Starting with release 2.2.1 of the C SDK, the non-FIPS distribution bundles provide version 1.0.2q of the OpenSSL 32– and 64–bit libraries, which on Windows platforms are based on the Visual Studio 2015 runtime library. The FIPS distribution bundles of this SDK provide the 32–bit OpenSSL libraries, v.1.0.2l, which are based on the Visual Studio 2012 runtime library.
For the most secure connection, set the issuer and subject fields of your server certificates before starting the connection by using the twApi_SetX509Fields() function. These settings mean that it will attempt to validate certificates and reject self-signed certificates.
Several functions are available to modify the default behavior and may provide some level of convenience during development, such as allowing self-signed certificates. These functions can be found in the file, twApi.h, and are as follows:
int twApi_SetProxyInfo(char * proxyHost, uint16_t proxyPort,
char * proxyUser, twPasswdCallbackFunction proxyPassCallback);
void twApi_SetSelfSignedOk();
int twApi_EnableFipsMode();
void twApi_DisableCertValidation();
void twApi_DisableEncryption();
int twApi_SetX509Fields(char * subject_cn, char * subject_o, char * subject_ou,
char * issuer_cn, char * issuer_o, char * issuer_ou);
int twApi_LoadCACert(const char *file, int type);
int twApi_LoadClientCert(char *file);
int twApi_SetClientKey(const char *file, twPasswdCallbackFunction passphraseCallback, int type);
In the twApi_SetProxyInfo() function, note that this function no longer takes a variable for the proxy password. Instead, it uses the output of the twPasswdCallbackFunction(). For details, see Passwords (C SDK 2.2.0 and later).
In the twApi_SetClientKey() function, note that this function no longer takes a variable for the passphrase. Instead it uses the output of the twPasswdCallbackFunction(). For details, see Passwords (C SDK 2.2.0 and later).
* 
Although you may want to enable self-signed certificates for development purposes, make sure that you disable self-signed certificates and set up the proper certificates before putting your application into production. Modifying the most secure settings possible for production is NOT recommended.
The functions defined in twTLS.h can be used for any SSL/TLS connections that your application needs to make. These functions are the abstracted interface that sit on top of the underlying TLS implementation.
Consistent with the OpenSSL APIs, the C SDK uses a structure for an SSL/TLS context that manages all the SSL/TLS sessions, as well as a structure for an SSL/TLS session itself. In addition, the APIs expose several functions for operations. The definitions and functions are exposed with preprocessor definitions. For these details, refer to the Doxygen documentation provided with the SDK. The following table lists and briefly describes the structures and functions defined in twTLS.h.
Item
Description
TW_SSL_CTX
The SSL context structure as defined by the implementation.
TW_SSL
The SSL session structure as defined by the implementation.
TW_SSL_SESSION_ID_SIZE
The SSL session structure as defined by the implementation.
TW_SSL_SESSION_ID_SIZE
The size of an SSL session ID as defined by the implementation. This ID is used for session resumption.
TW_GET_CERT_SIZE
Returns the maximum number of certificates allowed by the implementation.
TW_GET_CA_CERT_SIZE
Returns the maximum number of CA certificates allowed by the implementation.
TW_NEW_SSL_CTX
Creates and initializes new instance of an SSL_CTX.
TW_NEW_SSL_CLIENT(a,b,c,d)
Creates and initializes a new instance of an SSL structure within the provided SSL_CTX.
Parameters:
a — pointer to a TW_SSL_CTX structure.
b — a TW_SOCKET_TYPE value that is the descriptor of the socket to be used. The underlying socket should not be opened before calling this function.
c — session id. The session ID if session resumption is being used. The SDK does not use session resumption and sets this to NULL.
d — size of the session ID that was passed in.
TW_HANDSHAKE_SUCCEEDED
Returns a Boolean (char) value, TRUE if the SSL handshake succeeded and data can be securely exchanged, FALSE if otherwise.
TW_SSL_FREE(a)
Close any socket and free up any memory associated with an SSL session.
Parameter:
a — pointer to the TW_SSL structure to free.
TW_SSL_CTX_FREE(a)
Free up any memory associated with an SSL context.
Parameter:
a — pointer to the TW_SSL_CTX structure to free.
TW_SSL_WRITE(a,b,c)
Writes data out the secure connection.
Parameters:
a — pointer to the TW_SSL structure to write to.
b — pointer to the buffer containing the data to write.
c — the amount of data to write.
This result of this macro should contain the number of bytes sent, or a negative number if an error occurred.
TW_SSL_READ(a, b, c, d)
Reads data from the secure connection.
Parameters:
a — pointer to the TW_SSL structure to read from.
b — pointer to the buffer that the data should be placed in.
c — the amount of data to read.
d — the number of milliseconds to wait while trying to read the desired amount of data.
This result of this macro should contain the number of bytes read, or a negative number if an error occurred.
TW_USE_CERT_FILE(a,b,c)
Loads an X509 certificate in PEM or DER format from the file specified.
Parameters:
a — pointer to the TW_SSL_CTX structure load the certificate into.
b — name of the file containing the certificate.
c — a password to access the certificate (if required).
TW_USE_KEY_FILE(a,b,c,d)
Loads an encrypted key in PEM or DER format from the file specified.
Parameters:
a — pointer to the TW_SSL_CTX structure to read from
b — name of the file containing the key
c — the type of key
d — a password to access the key.
TW_USE_CERT_CHAIN_FILE(a,b,c)
Loads a certificate chain in PEM or DER format from the file specified.
Parameters:
a — pointer to the TW_SSL_CTX structure load the certificate into.
b — name of the file containing the certificate chain.
c — a password to access the certificate (if required).
TW_SET_CLIENT_CA_LIST(a,b)
Sets the list of supported CAs from the file specified.
Parameters:
a — pointer to the TW_SSL_CTX structure load the certificate into.
b — pointer to the CA list.
TW_VALIDATE_CERT(TW_SSL * ssl, char selfSignedOk)
Inline function that validates the received certificate.
Parameters:
ssl — pointer to the TW_SSL structure that has received the certificate
selfSignedOk — boolean, set to TRUE if self-signed certificates are allowed, FALSE if not. Default is FALSE.
Returns zero if the certificate is valid, non-zero if not.
TW_ENABLE_FIPS_MODE(a)
Enables FIPS mode.
Parameters:
a – pointer to the TW_SSL_CTX structure
Returns zero if successful or an error code if FIPS is supported but enabling failed or TW_FIPS_MODE_NOT_SUPPORTED if the TLS layer does not support FIPS
TW_GET_X509_FIELD(TW_SSL * ssl, char field)
Inline function that gets the value of a field in the certificate.
Parameters:
ssl — pointer to the TW_SSL structure that has received the certificate
fieldchar, the field to retrieve. Fields supported must be SUBJECT_CN, SUBJECT_O, SUBJECT_OU, ISSUER CN, ISSUER_O, ISSUER_OU
Returns the value of the field, or NULL if the field is not found.