TLS Abstraction Layer. More...

Typedefs
typedef void *	TLS_Handle

Functions
TLS_Handle	TLS_create (TLS_Method method)
	Allocate and initialize a new TLS context and return its handle. More...

void	TLS_delete (TLS_Handle *tls)
	Destroy the TLS context instance and free the previously allocated instance object. More...

int	TLS_setCertFile (TLS_Handle tls, TLS_Cert_Type type, TLS_Cert_Format format, const char *filePath)
	Set the certificate files required for TLS handshake. More...

int	TLS_setCertBuf (TLS_Handle tls, TLS_Cert_Type type, TLS_Cert_Format format, uint8_t *buf, uint32_t buflen)
	Set the certificate buffers required for TLS handshake. More...

int	TLS_writeDerFile (uint8_t buf, uint32_t buflen, TLS_Cert_Format format, const char filePath)
	Convert and write DER encoded certificate buffers to file system. More...

int	TLS_writePemFile (uint8_t buf, uint32_t buflen, TLS_Cert_Type type, TLS_Cert_Format format, const char filePath)
	write PEM encoded certificate buffers to file system More...

TLS Error Codes
#define	TLS_EINVALIDPARAMS (-11)
	Input parameters are invalid. More...

#define	TLS_ENOTSUPPORTED (-12)
	This feature is not supported on the network stack. More...

#define	TLS_EALLOCFAIL (-13)
	Not enough heap to allocate required memory. More...

#define	TLS_ECERTLOADFAIL (-14)
	Loading the certificate on SSL stack failed. More...

#define	TLS_ECERTWRITEFAIL (-15)
	Writing the certificate to filesystem failed. More...

TLS Method
enum	TLS_Method { TLS_METHOD_CLIENT_TLSV1 = 1, TLS_METHOD_CLIENT_TLSV1_1, TLS_METHOD_CLIENT_TLSV1_2, TLS_METHOD_SERVER_TLSV1, TLS_METHOD_SERVER_TLSV1_1, TLS_METHOD_SERVER_TLSV1_2 }

typedef enum TLS_Method	TLS_Method

TLS Certificate Type
enum	TLS_Cert_Type { TLS_CERT_TYPE_CA = 1, TLS_CERT_TYPE_CERT, TLS_CERT_TYPE_KEY, TLS_CERT_TYPE_DH_KEY }

typedef enum TLS_Cert_Type	TLS_Cert_Type

TLS Certificate Format
enum	TLS_Cert_Format { TLS_CERT_FORMAT_DER = 1, TLS_CERT_FORMAT_PEM }

typedef enum TLS_Cert_Format	TLS_Cert_Format

Detailed Description

TLS Abstraction Layer.

This module provides a simple portable interface to create and delete TLS contexts for various TLS layers like SimpleLink WiFi TLS and WolfSSL. These contexts can be shared with supported networking protocols like HTTP, MQTT and other protocols which require TLS and are connecting to the same host server.

The certificates can be provided either as a buffer input or as a string containing the certificate paths on the file system.

The file system based approach is supported only for TI-RTOS/SimpleLink WiFi and Linux/Sitara devices. The certificates can be set by providing the certificate file path using TLS_setCertFile().

The buffer based approach is supported only for TI-RTOS/NDK and Linux/Sitara devices. The certificates can be set by providing the certificate buffers using TLS_setCertBuf().

Additionally, for TI-RTOS/SimpleLink WiFi and Linux/Sitara devices certificate buffers can be written to file system using TLS_writeDerFile() and set using TLS_setCertFile().

A brief usage of TLS APIs is shown below as pseudo codes for different supported platforms

TI-RTOS/SimpleLink WiFi and Linux/Sitara (make sure file path is accessible):

#include <ti/net/tls.h>
tls = TLS_create(TLS_METHOD_CLIENT_TLSV1_2);
//Create and flash the root CA PEM data (stored in a buffer) to a .der file.
//If the *.der files are already flashed, you don't need to do this step.
TLS_writeDerFile(caBuf, caBufLen, TLS_CERT_FORMAT_PEM, "/certs/ca.der");
TLS_setCertFile(tls, TLS_CERT_TYPE_CA, TLS_CERT_FORMAT_DER,
        "/certs/ca.der");
TLS_delete(&tls);

TI-RTOS/NDK and Linux/Sitara:

#include <ti/net/tls.h>
tls = TLS_create(TLS_METHOD_CLIENT_TLSV1_2);
TLS_setCertBuf(tls, TLS_CERT_TYPE_CA, TLS_CERT_FORMAT_PEM, caBuf, caBufLen);
TLS_delete(&tls);

Macro Definition Documentation

§ TLS_EINVALIDPARAMS

#define TLS_EINVALIDPARAMS (-11)

Input parameters are invalid.

§ TLS_ENOTSUPPORTED

#define TLS_ENOTSUPPORTED (-12)

This feature is not supported on the network stack.

§ TLS_EALLOCFAIL

#define TLS_EALLOCFAIL (-13)

Not enough heap to allocate required memory.

§ TLS_ECERTLOADFAIL

#define TLS_ECERTLOADFAIL (-14)

Loading the certificate on SSL stack failed.

§ TLS_ECERTWRITEFAIL

#define TLS_ECERTWRITEFAIL (-15)

Writing the certificate to filesystem failed.

Typedef Documentation

§ TLS_Method

typedef enum TLS_Method TLS_Method

§ TLS_Cert_Type

typedef enum TLS_Cert_Type TLS_Cert_Type

§ TLS_Cert_Format

typedef enum TLS_Cert_Format TLS_Cert_Format

§ TLS_Handle

typedef void* TLS_Handle

Enumeration Type Documentation

§ TLS_Method

enum TLS_Method

Enumerator
TLS_METHOD_CLIENT_TLSV1	TLS v1 Client
TLS_METHOD_CLIENT_TLSV1_1	TLS v1.1 Client
TLS_METHOD_CLIENT_TLSV1_2	TLS v1.2 Client
TLS_METHOD_SERVER_TLSV1	TLS v1 Server
TLS_METHOD_SERVER_TLSV1_1	TLS v1.1 Server
TLS_METHOD_SERVER_TLSV1_2	TLS v1.2 Server

§ TLS_Cert_Type

enum TLS_Cert_Type

Enumerator
TLS_CERT_TYPE_CA	Root CA certificate
TLS_CERT_TYPE_CERT	Client/Server certificate
TLS_CERT_TYPE_KEY	Client/Server private key
TLS_CERT_TYPE_DH_KEY	Diffie-Hellman key (SimpleLink WiFi only)

§ TLS_Cert_Format

enum TLS_Cert_Format

Enumerator
TLS_CERT_FORMAT_DER	DER encoded certificates
TLS_CERT_FORMAT_PEM	PEM encoded certificates

Function Documentation

§ TLS_create()

TLS_Handle TLS_create ( TLS_Method method )

Allocate and initialize a new TLS context and return its handle.

Parameters

[in] method TLS version (see TLS_Method)

Returns: a TLS_Handle on success or NULL on failure

§ TLS_delete()

void TLS_delete ( TLS_Handle * tls )

Destroy the TLS context instance and free the previously allocated instance object.

Parameters

[in] tls Pointer to the TLS context instance

§ TLS_setCertFile()

int TLS_setCertFile	(	TLS_Handle	tls,
		TLS_Cert_Type	type,
		TLS_Cert_Format	format,
		const char *	filePath
	)

Set the certificate files required for TLS handshake.

It takes the path to a valid certificate on the file system as input.

Remarks: This function is not supported for NDK/WolfSSL.

Parameters

[in]	tls	TLS context instance
[in]	type	Certificate type as defined in TLS_Cert_Type
[in]	format	Certificate format as defined in TLS_Cert_Format
[in]	filePath	Path to the certificate on the file system. Note, the string has to be persistent throughout the life-cycle of the TLS context.

Returns: 0 on success or an error code on failure TLS_EINVALIDPARAMS, TLS_ECERTLOADFAIL, TLS_ENOTSUPPORTED.

§ TLS_setCertBuf()

int TLS_setCertBuf	(	TLS_Handle	tls,
		TLS_Cert_Type	type,
		TLS_Cert_Format	format,
		uint8_t *	buf,
		uint32_t	buflen
	)

Set the certificate buffers required for TLS handshake.

It takes a valid certificate buffer as input and loads it on the TLS context.

Remarks: This function is not supported for SimpleLink WiFi. Instead, use TLS_writeDerFile() to write the certificate buffer to file and TLS_setCertFile() to load the file from file system.

Parameters

[in]	tls	TLS context instance
[in]	type	Certificate type as defined in TLS_Cert_Type
[in]	format	Certificate format as defined in TLS_Cert_Format
[in]	buf	Certificate buffer
[in]	buflen	Length of 'buf' buffer

Returns: 0 on success or an error code on failure TLS_EALLOCFAIL, TLS_ECERTLOAFAIL, TLS_ENOTSUPPORTED.

§ TLS_writeDerFile()

int TLS_writeDerFile	(	uint8_t *	buf,
		uint32_t	buflen,
		TLS_Cert_Format	format,
		const char *	filePath
	)

Convert and write DER encoded certificate buffers to file system.

It takes a valid certificate buffer as input, converts it to DER encoding if the input buffer is in PEM encoding and writes to file system to the location provided as input.

Remarks: This function is not supported for NDK/WolfSSL.; The files written to the file system are not deleted by this TLS module. It is the user's responsibility to delete the files if needed.

Parameters

[in]	buf	Certificate buffer
[in]	buflen	Length of 'buf' buffer
[in]	format	Certificate format as defined in TLS_Cert_Format
[in]	filePath	Path to write the certificate on the file system with ".der" extension. Note, the string has to be persistent throughout the life-cycle of the TLS context.

Returns: 0 on success or an error code on failure TLS_EALLOCFAIL, TLS_ECERTWRITEFAIL, TLS_ENOTSUPPORTED.

§ TLS_writePemFile()

int TLS_writePemFile	(	uint8_t *	buf,
		uint32_t	buflen,
		TLS_Cert_Type	type,
		TLS_Cert_Format	format,
		const char *	filePath
	)

write PEM encoded certificate buffers to file system

It takes a valid certificate buffer in PEM format as input, and writes to file system to the location provided as input.

The PEM certificate buffer should include headers and footers. For example, the certificates should begin and end with:

-----BEGIN CERTIFICATE-----\n
-----END CERTIFICATE-----\n

Each of the header, certificate data and footer line in the buffer should be terminated by a newline character.

Remarks: This function is not supported for NDK/WolfSSL.; The files written to the file system are not deleted by this TLS module. It is the user's responsibility to delete the files if needed.

Parameters

[in]	buf	Certificate buffer
[in]	buflen	Length of 'buf' buffer
[in]	type	Certificate type as defined in TLS_Cert_Type
[in]	format	Certificate format as defined in TLS_Cert_Format
[in]	filePath	Path to write the certificate on the file system with ".pem" extension. Note, the string has to be persistent throughout the life-cycle of the TLS context.

Returns: 0 on success or an error code on failure TLS_ECERTWRITEFAIL, TLS_ENOTSUPPORTED.

Typedefs

Functions

TLS Error Codes

TLS Method

TLS Certificate Type

TLS Certificate Format

Detailed Description

Macro Definition Documentation

§ TLS_EINVALIDPARAMS

§ TLS_ENOTSUPPORTED

§ TLS_EALLOCFAIL

§ TLS_ECERTLOADFAIL

§ TLS_ECERTWRITEFAIL

Typedef Documentation

§ TLS_Method

§ TLS_Cert_Type

§ TLS_Cert_Format

§ TLS_Handle

Enumeration Type Documentation

§ TLS_Method

§ TLS_Cert_Type

§ TLS_Cert_Format

Function Documentation

§ TLS_create()

§ TLS_delete()

§ TLS_setCertFile()

§ TLS_setCertBuf()

§ TLS_writeDerFile()

§ TLS_writePemFile()