ThingWorx C SDK
Classes | Macros | Typedefs | Functions
twTls.h File Reference

ThingWorx TLS client abstraction layer. More...

#include "twOSPort.h"
#include "twErrors.h"
#include "tomcrypt.h"

Go to the source code of this file.

Classes

struct  twTlsClient
 TLS client structure definition. More...
 

Macros

#define TW_SUBJECT_CN   0
 
#define TW_SUBJECT_O   1
 
#define TW_SUBJECT_OU   2
 
#define TW_ISSUER_CN   3
 
#define TW_ISSUER_O   4
 
#define TW_ISSUER_OU   5
 
#define TW_READ_TIMEOUT   -333
 
#define TW_SHA1_CTX   hash_state
 
#define TW_SHA1_INIT(a)   sha1_init(a)
 
#define TW_SHA1_UPDATE(a, b, c)   sha1_process(a,b,c)
 
#define TW_SHA1_FINAL(a, b)   sha1_done(b,a)
 
#define TW_MD5_CTX   hash_state
 
#define TW_MD5_INIT(a)   md5_init(a)
 
#define TW_MD5_UPDATE(a, b, c)   md5_process(a,b,c)
 
#define TW_MD5_FINAL(a, b)   md5_done(b,a)
 

Typedefs

typedef struct twTlsClient twTlsClient
 TLS client structure definition.
 

Functions

int twTlsClient_Create (const char *host, int16_t port, uint32_t options, twTlsClient **client)
 Creates a new twTlsClient structure with the specified settings. More...
 
int twTlsClient_Connect (twTlsClient *t)
 Connects a twTlsClient::connection (see twSocket_Connect()). More...
 
int twTlsClient_ConnectSession (twTlsClient *t, void *sessionId, int sessionLength)
 Connects a twTlsClient::connection (see twSocket_Connect()) with some additional session options. More...
 
int twTlsClient_Reconnect (twTlsClient *t, const char *host, int16_t port)
 Reconnects a twTlsClient::connection (see twSocket_Reconnect()). More...
 
int twTlsClient_Close (twTlsClient *t)
 Closes a twTlsClient::connection (see twSocket_Close()). More...
 
int twTlsClient_Read (twTlsClient *t, char *buf, int len, int timeout)
 Reads len bytes of data from a twTlsClient::connection into buf (see twSocket_Read()). More...
 
int twTlsClient_Write (twTlsClient *t, char *buf, int len, int timeout)
 Writes len bytes of data from buf to a twTlsClient::connection (see twSocket_Write()). More...
 
int twTlsClient_Delete (twTlsClient *t)
 Frees all memory associated with a twTlsClient and all of its owned substructures. More...
 
int twTlsClient_IsEncrypted (twTlsClient *t)
 Checks to see if a twTlsClient is encrypted by getting the value of twTlsClient::isEncrypted. More...
 
void * twTlsClient_GetSessionId (twTlsClient *t)
 Gets the session ID of a twTlsClient. More...
 
void twTlsClient_SetSelfSignedOk (twTlsClient *t)
 Sets the twTlsClient to accept self signed certificates (see twSocket_SetSelfSignedOk()). More...
 
void twTlsClient_DisableCertValidation (twTlsClient *t)
 Sets the twTlsClient to disable certificate validation (see twSocket_DisableCertValidation()). More...
 
void twTlsClient_DisableEncryption (twTlsClient *t)
 Sets the twTlsClient to disable encryption (see twSocket_DisableEncryption()). More...
 
int twTlsClient_ValidateCert (twTlsClient *t)
 Tells the twTlsClient to validate its twTlsClient::ssl certificate (see TW_VALIDATE_CERT()). More...
 
int twTlsClient_UseCertificateFile (twTlsClient *t, const char *file, int type)
 Loads the first certificate stored in file into twTlsClient::ctx. More...
 
int twTlsClient_UsePrivateKeyFile (twTlsClient *t, const char *file, int type)
 Loads the first private key stored in file into twTlsClient::ctx. More...
 
int twTlsClient_UseCertificateChainFile (twTlsClient *t, const char *file, int type)
 Loads the certificate authority cert chain used to validate the server's certificate in file into twTlsClient::ctx (see TW_USE_KEY_FILE(). More...
 
int twTlsClient_SetClientCaList (twTlsClient *t, char *caFile)
 Loads a client certificate authority cert chain in file into twTlsClient::ctx. More...
 
void twTlsClient_SetDefaultPasswdCbUserdata (twTlsClient *t, void *u)
 Sets the twTlsClient::keypasswd of a twTlsClient to u. More...
 
int twTlsClient_EnableFipsMode (twTlsClient *t)
 Enables FIPS mode for a twTlsClient. Wrapper function for TW_ENABLE_FIPS_MODE(). More...
 
int twTlsClient_SetX509Fields (twTlsClient *t, char *subject_cn, char *subject_o, char *subject_ou, char *issuer_cn, char *issuer_o, char *issuer_ou)
 Sets the X509 fields of a twTlsClient. More...
 
int twTlsServer_Create (twTlsClient *t)
 Creates a new #TW_TLS server and associates it with a twTlsClient::ssl. More...
 
int twTlsServer_Accept (twTlsClient *t)
 Waits for a twTlsClient::ssl to initiate a handshake with the server (see TW_SSL_ACCEPT()). More...
 
void twSHA1_Init (TW_SHA1_CTX *ctx)
 Initializes an SHA1 context. More...
 
void twSHA1_Update (TW_SHA1_CTX *ctx, const uint8_t *msg, int len)
 Add a new entry to an SHA1 hash. More...
 
void twSHA1_Final (uint8_t *digest, TW_SHA1_CTX *ctx)
 Finalize and get the calculated SHA1 digest. More...
 
void twMD5_Init (TW_MD5_CTX *)
 Initializes an MD5 context. More...
 
void twMD5_Update (TW_MD5_CTX *, const uint8_t *msg, int len)
 Add a new entry to an MD5 hash. More...
 
void twMD5_Final (uint8_t *digest, TW_MD5_CTX *)
 Finalize and get the calculated MD5 digest. More...
 

Detailed Description

ThingWorx TLS client abstraction layer.

Macro Definition Documentation

#define TW_MD5_CTX   hash_state
Note
SHA1 for the websocket accept header. If not defined by the TLS library, use built in libTomcrypt
#define TW_SHA1_CTX   hash_state
Note
SHA1 for the websocket accept header. If not defined by the TLS library, use built in libTomcrypt

Function Documentation

void twMD5_Final ( uint8_t *  digest,
TW_MD5_CTX  
)

Finalize and get the calculated MD5 digest.

Parameters
[in,out]digestA pointer to the buffer to receive the digest.
[in]ctxA pointer to the ctx structure.
Returns
nothing
void twMD5_Init ( TW_MD5_CTX )

Initializes an MD5 context.

Parameters
[in]ctxA pointer to the ctx structure to initialize.
Returns
nothing
void twMD5_Update ( TW_MD5_CTX ,
const uint8_t *  msg,
int  len 
)

Add a new entry to an MD5 hash.

Parameters
[in]ctxA pointer to the ctx structure.
[in]msgA pointer to the message to add.
[in]lenThe length of the message.
Returns
nothing
void twSHA1_Final ( uint8_t *  digest,
TW_SHA1_CTX ctx 
)

Finalize and get the calculated SHA1 digest.

Parameters
[in,out]digestA pointer to the buffer to receive the digest.
[in]ctxA pointer to the ctx structure.
Returns
nothing
void twSHA1_Init ( TW_SHA1_CTX ctx)

Initializes an SHA1 context.

Parameters
[in]ctxA pointer to the ctx structure to initialize.
Returns
nothing
void twSHA1_Update ( TW_SHA1_CTX ctx,
const uint8_t *  msg,
int  len 
)

Add a new entry to an SHA1 hash.

Parameters
[in]ctxA pointer to the ctx structure.
[in]msgA pointer to the message to add.
[in]lenThe length of the message.
Returns
nothing
int twTlsClient_Close ( twTlsClient t)

Closes a twTlsClient::connection (see twSocket_Close()).

Parameters
[in]tA pointer to the twTlsClient to close.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsClient_Connect ( twTlsClient t)

Connects a twTlsClient::connection (see twSocket_Connect()).

Parameters
[in]tA pointer to the twTlsClient to connect.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsClient_ConnectSession ( twTlsClient t,
void *  sessionId,
int  sessionLength 
)

Connects a twTlsClient::connection (see twSocket_Connect()) with some additional session options.

Parameters
[in]tA pointer to the twTlsClient to connect.
[in]sessionIdThe session ID to assign to the connection.
[in]sessionLengthThe length of the session.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
Session ID objects keep internal link information about the session cache list, when being inserted into one #TW_SSL_CTX object's session cache. One SSL_SESSION object, regardless of its reference count, must therefore only be used with one #TW_SSL_CTX object (and the SSL objects created from this #TW_SSL_CTX object).
int twTlsClient_Create ( const char *  host,
int16_t  port,
uint32_t  options,
twTlsClient **  client 
)

Creates a new twTlsClient structure with the specified settings.

Parameters
[in]hostThe host name of the server (twSocket::host).
[in]portThe port the server is listening on (twSocket::port).
[in]optionsThe TLS options of the twTlsClient.
[out]clientA pointer to a pointer to store the newly allocated twTlsClient at.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will gain ownership of client and is responsible for freeing it via twTlsClient_Delete().

int cert_index = 0, ca_cert_index = 0; int cert_size, ca_cert_size; char **ca_cert, **cert; const char *password = NULL;

int twTlsClient_Delete ( twTlsClient t)

Frees all memory associated with a twTlsClient and all of its owned substructures.

Parameters
[in]tA pointer to the twTlsClient to delete.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void twTlsClient_DisableCertValidation ( twTlsClient t)

Sets the twTlsClient to disable certificate validation (see twSocket_DisableCertValidation()).

Parameters
[in]tA pointer to the twTlsClient to modify.
Returns
Nothing.
Warning
This option may induce a serious security risk.
void twTlsClient_DisableEncryption ( twTlsClient t)

Sets the twTlsClient to disable encryption (see twSocket_DisableEncryption()).

Parameters
[in]tA pointer to the twTlsClient to modify.
Returns
Nothing.
Warning
This option may induce a serious security risk.
int twTlsClient_EnableFipsMode ( twTlsClient t)

Enables FIPS mode for a twTlsClient. Wrapper function for TW_ENABLE_FIPS_MODE().

Parameters
[in]tA pointer to the twTlsClient to modify.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
void* twTlsClient_GetSessionId ( twTlsClient t)

Gets the session ID of a twTlsClient.

Parameters
[in]tA pointer to the twTlsClient to get the session ID of.
Returns
Nothing.
Note
Session ID objects keep internal link information about the session cache list, when being inserted into one #TW_SSL_CTX object's session cache. One #TW_SSL_SESSION object, regardless of its reference count, must therefore only be used with one #TW_SSL_CTX object (and the SSL objects created from this #TW_SSL_CTX object).
int twTlsClient_IsEncrypted ( twTlsClient t)

Checks to see if a twTlsClient is encrypted by getting the value of twTlsClient::isEncrypted.

Parameters
[in]tA pointer to the twTlsClient to inspect.
Returns
#TRUE if t is encrypted, #FALSE otherwise.
int twTlsClient_Read ( twTlsClient t,
char *  buf,
int  len,
int  timeout 
)

Reads len bytes of data from a twTlsClient::connection into buf (see twSocket_Read()).

Parameters
[in]tA pointer to the twTlsClient to read from.
[out]bufA buffer to store the read data.
[in]lenThe length of data to read.
[in]timeoutThe amount of time (in milliseconds) to wait for I/O before timing out.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of buf and is responsible for freeing it.
int twTlsClient_Reconnect ( twTlsClient t,
const char *  host,
int16_t  port 
)

Reconnects a twTlsClient::connection (see twSocket_Reconnect()).

Parameters
[in,out]tA pointer to the twTlsClient to reconnect.
[in]hostThe host name of the server (twSocket::host).
[in]portThe port the server is listening on (twSocket::port).
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsClient_SetClientCaList ( twTlsClient t,
char *  caFile 
)

Loads a client certificate authority cert chain in file into twTlsClient::ctx.

Parameters
[in]tA pointer to the twTlsClient to modify.
[in]fileThe certificate chain file to use.
[in]typeThe container format of file.
Returns
1 on success, updates error stack on failure.
Note
The certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root).
void twTlsClient_SetDefaultPasswdCbUserdata ( twTlsClient t,
void *  u 
)

Sets the twTlsClient::keypasswd of a twTlsClient to u.

Parameters
[in]tA pointer to the twTlsClient to modify.
[in]uA pointer to the data to use as they password.
Returns
Nothing.
void twTlsClient_SetSelfSignedOk ( twTlsClient t)

Sets the twTlsClient to accept self signed certificates (see twSocket_SetSelfSignedOk()).

Parameters
[in]tA pointer to the twTlsClient to modify.
Returns
Nothing.
Warning
This option may induce a serious security risk.
int twTlsClient_SetX509Fields ( twTlsClient t,
char *  subject_cn,
char *  subject_o,
char *  subject_ou,
char *  issuer_cn,
char *  issuer_o,
char *  issuer_ou 
)

Sets the X509 fields of a twTlsClient.

Parameters
[in,out]tA pointer to the twTlsClient to modify.
[in]subject_cnThe common name of the subject.
[in]subject_oThe organization of the subject.
[in]subject_ouThe organizational unit of the subject.
[in]issuer_cnThe common name of the issuer.
[in]issuer_oThe organization of the issuer.
[in]issuer_ouThe organizational unit of the issuer.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsClient_UseCertificateChainFile ( twTlsClient t,
const char *  file,
int  type 
)

Loads the certificate authority cert chain used to validate the server's certificate in file into twTlsClient::ctx (see TW_USE_KEY_FILE().

Parameters
[in]tA pointer to the twTlsClient to modify.
[in]fileThe certificate chain file to use.
[in]typeThe container format of file.
Returns
1 on success, updates error stack on failure.
Note
The certificates must be in PEM format and must be sorted starting with the subject's certificate (actual client or server certificate), followed by intermediate CA certificates if applicable, and ending at the highest level (root).
int twTlsClient_UseCertificateFile ( twTlsClient t,
const char *  file,
int  type 
)

Loads the first certificate stored in file into twTlsClient::ctx.

Parameters
[in]tA pointer to the twTlsClient to modify.
[in]fileThe certificate file to use.
[in]typeThe container format of file.
Returns
1 on success, updates error stack on failure.
int twTlsClient_UsePrivateKeyFile ( twTlsClient t,
const char *  file,
int  type 
)

Loads the first private key stored in file into twTlsClient::ctx.

Parameters
[in]tA pointer to the twTlsClient to modify.
[in]fileThe private key file to use.
[in]typeThe container format of file.
Returns
1 on success, updates error stack on failure.
int twTlsClient_ValidateCert ( twTlsClient t)

Tells the twTlsClient to validate its twTlsClient::ssl certificate (see TW_VALIDATE_CERT()).

Parameters
[in]tA pointer to the twTlsClient to validate the certificate of.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsClient_Write ( twTlsClient t,
char *  buf,
int  len,
int  timeout 
)

Writes len bytes of data from buf to a twTlsClient::connection (see twSocket_Write()).

Parameters
[in]tA pointer to the twTlsClient to write to.
[out]bufA buffer containing the data to be written.
[in]lenThe length of data to write.
[in]timeoutThe amount of time (in milliseconds) to wait for I/O before timing out.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
Note
The calling function will retain ownership of buf and is responsible for freeing it.
int twTlsServer_Accept ( twTlsClient t)

Waits for a twTlsClient::ssl to initiate a handshake with the server (see TW_SSL_ACCEPT()).

Parameters
[in]tA pointer to the twTlsClient to utilize.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.
int twTlsServer_Create ( twTlsClient t)

Creates a new #TW_TLS server and associates it with a twTlsClient::ssl.

Parameters
[in,out]tA pointer to the twTlsClient to modify.
Returns
#TW_OK if successful, positive integral on error code (see twErrors.h) if an error was encountered.