This is the main header file containing all essential API functions. More...

Macros
#define	TRUE ( (BOOL)1 )

#define	FALSE ( (BOOL)0 )

Typedefs
typedef unsigned long	UINT32

typedef unsigned short	UINT16

typedef unsigned char	UINT8

typedef UINT8	BOOL

typedef UINT8	SOCKET
	Specifies a socket that has already been opened by either TCPClientOpen() or TCPServerOpen(). More...

typedef int(*	PointerToSend) (SOCKET pSocket, const UINT8 *pBuffer, UINT32 len_buffer)
	Pointer to function which sends TCP packets. As TLS operates on a higher ISO/OSI level, we need interface functions at this point that take care of processing incoming and outgoing data on a lower network layer, i.e. TCP. Hence, PointerToSend is expected to hold reference to TCPSend(). More...

typedef int(*	PointerToReceive) (SOCKET pSocket, UINT8 *const pBuffer, UINT32 len_buffer)
	Pointer to `TCPRecv()`. More...

typedef void(*	PointerToCloseSocket) (SOCKET pSocket)
	Pointer to `TCPClose()`. More...

typedef void (	PointerToMalloc) (UINT32 size)
	Pointer to `malloc()`. As dicussed during the introduction of TLSLib, TLS implementations have to work with dynamic memory unless of course there is enough stack available to allocate a static buffer of the maximum size, which in this case has to be 16 kilobytes per direction (i.e. incoming and outgoing buffer). Since on W7200 this requirement is impossible to satisfy, we have to make use of dynamic memory allocation. More...

typedef void(*	PointerToFree) (void *pMemory)
	Pointer to `free()`. More...

typedef void (	PointerToRealloc) (void *pMemory, UINT32 new_size)
	Pointer to `realloc()`. More...

typedef int(*	PointerToTRNG) (UINT8 rng[32])

Functions
int	TLSShutdown (const void **ppSession)
	Closes an existing TLS session and realeases dynamically allocated resources. More...

int	TLSEngine (SOCKET pSocket, const void **ppSession, const char fqdn[], const UINT8 len_fqdn, PointerToSend Send, PointerToReceive Receive, PointerToCloseSocket CloseSocket, PointerToMalloc Malloc, PointerToFree Free, PointerToRealloc Realloc, PointerToTRNG pbTRNG, UINT8 mode_of_operation, BOOL bClientMode_Tolerate_FQDN_Mismatch, BOOL bClientMode_Skip_Authorised_Root_CA_Check, BOOL client_certificate_request, const UINT8 server_cert[], const UINT32 len_server_cert, const UINT8 ca_cert[], const UINT32 len_ca_cert, const UINT8 client_cert[], const UINT32 len_client_cert, const UINT8 server_rsa_private_key[], const UINT32 len_server_rsa_private_key, const UINT8 client_rsa_private_key[], const UINT32 len_client_rsa_private_key)
	Creates a TLS server or client session. More...

int	TLSReadAppData (const void const ppCurrentSession, UINT8 output_buffer[], UINT32 *len_output_buffer)
	Reads incoming encrypted application data according to the established (after engine success) session parameters. More...

int	TLSWriteAppData (const void const ppCurrentSession, const UINT8 data[], UINT32 len_data)
	Writes outgoing encrypted app data according to the established TLS session parameters. More...

Detailed Description

This is the main header file containing all essential API functions.

Author: Witali Urovski

Copyright: Steen Harbach AG, Leverkusen, Germany

Version

Macro Definition Documentation

#define FALSE ( (BOOL)0 )

BOOL value false.

#define TRUE ( (BOOL)1 )

BOOL value true.

Typedef Documentation

typedef UINT8 BOOL

Type can only be TRUE (Non-zero) or FALSE (Zero). Boolean operations deliver the expected results.

typedef void(* PointerToCloseSocket) (SOCKET pSocket)

Pointer to TCPClose().

typedef void(* PointerToFree) (void *pMemory)

Pointer to free().

typedef void*(* PointerToMalloc) (UINT32 size)

Pointer to malloc(). As dicussed during the introduction of TLSLib, TLS implementations have to work with dynamic memory unless of course there is enough stack available to allocate a static buffer of the maximum size, which in this case has to be 16 kilobytes per direction (i.e. incoming and outgoing buffer). Since on W7200 this requirement is impossible to satisfy, we have to make use of dynamic memory allocation.

Note: In order to minimise memory allocation, a single TLS record buffer is used for both incoming and outgoing data. Technically, we start a TLS session with a minimum size of 512 bytes assigned to that buffer. With the help of a sophisticated look-ahead technique, every incoming or outgoing TLS record is parsed for its actual capacity dynamically increasing the size of the working buffer to hold the record. Once the record in question has been successfully processed, i.e. read or written, additional memory will be released decreasing the size to the originial minimum of 512 bytes.

typedef void*(* PointerToRealloc) (void *pMemory, UINT32 new_size)

Pointer to realloc().

typedef int(* PointerToReceive) (SOCKET pSocket, UINT8 *const pBuffer, UINT32 len_buffer)

Pointer to TCPRecv().

typedef int(* PointerToSend) (SOCKET pSocket, const UINT8 *pBuffer, UINT32 len_buffer)

Pointer to function which sends TCP packets. As TLS operates on a higher ISO/OSI level, we need interface functions at this point that take care of processing incoming and outgoing data on a lower network layer, i.e. TCP. Hence, PointerToSend is expected to hold reference to TCPSend().

typedef int(* PointerToTRNG) (UINT8 rng[32])

Pointer to TRNG(). Generate 32 byte random number.

Parameters

[in]	rng[32]	Binary array to store 32 byte Random Nummber
[out]	rng[32]	Binary array to store 32 byte Random Nummber

typedef UINT8 SOCKET

Specifies a socket that has already been opened by either TCPClientOpen() or TCPServerOpen().

typedef unsigned short UINT16

16 bit unsigned integer.

typedef unsigned long UINT32

32 bit unsigned integer.

typedef unsigned char UINT8

8 bit unsigned integer.

Function Documentation

int TLSEngine	(	SOCKET	pSocket,
		const void **	ppSession,
		const char	fqdn[],
		const UINT8	len_fqdn,
		PointerToSend	Send,
		PointerToReceive	Receive,
		PointerToCloseSocket	CloseSocket,
		PointerToMalloc	Malloc,
		PointerToFree	Free,
		PointerToRealloc	Realloc,
		PointerToTRNG	pbTRNG,
		UINT8	mode_of_operation,
		BOOL	bClientMode_Tolerate_FQDN_Mismatch,
		BOOL	bClientMode_Skip_Authorised_Root_CA_Check,
		BOOL	client_certificate_request,
		const UINT8	server_cert[],
		const UINT32	len_server_cert,
		const UINT8	ca_cert[],
		const UINT32	len_ca_cert,
		const UINT8	client_cert[],
		const UINT32	len_client_cert,
		const UINT8	server_rsa_private_key[],
		const UINT32	len_server_rsa_private_key,
		const UINT8	client_rsa_private_key[],
		const UINT32	len_client_rsa_private_key
	)

Creates a TLS server or client session.

Parameters

[in]	pSocket	Socket pointer to an established connection.
[out]	ppSession	Simple reference to a void pointer that will hold reference to a session. Once a TLS session has been successfully established this reference will be used as a session ticket to pass on to TLSReadAppData() and TLSWriteAppData() to actually send and receive TLS secured data over the network.
[in]	fqdn	Character array to hold the FQDN of the server a TLS connection will be established with. Note: This is important for client mode only! Much like all browsers, in client mode the TLS engine will not only establish a connection to the target server, but also verify its parameters. This verification comprises several steps: Check, if the FQDN specified here is equal to the CN attribute from the server certificate. Check, if the server's certificate has been published by a root CA whose certificate must in turn correspond with the pre-coded one. Check the digital signature of the server certificate. Check the digital signature of the root CA certificate.
[in]	len_fqdn	Length of the specified server FQDN without the trailing zero character, which is often used with zero-terminated strings.
[in]	Send	Pointer to TCPSend() or a similar function.
[in]	Receive	Pointer to TCPRecv() or a similar function.
[in]	CloseSocket	Pointer to TCPClose() or a similar function.
[in]	Malloc	Pointer to malloc().
[in]	Free	Pointer to free().
[in]	Realloc	Pointer to realloc().
[in]	TRNG	(True Random Number Generator) Pointer to Hardware engine for entropy. NULL to disable this and the pbTLS engine will use a hard coded = fix random number ! only good for test purpose
[in]	mode_of_operation	Determines mode of operation for the session to be established. 0: Client Mode. 1: Server Mode.
[in]	bClientMode_Tolerate_FQDN_Mismatch	For testing purposes it might be necessary to relax strict server FQDN (fully qualified domain name) check. This is similar to when a browser warns his user that the common name (CN) from the server's certificate does not correspond with the URL specified (or IP address) by the user in the address field. The user may still want to proceed with the secure connection to that server. That is exactly what is going to happen here, too. FALSE: in the certificate provided by the client (we are server) the CN must be equal to the URL or FQDN. in case of mismatch: TLS msg. return is: "access denied"; TLS alert is "fatal". and then TLSShutdown() + Socket close() + return Error code: TLS_ERR_WRONG_CN_OR_FQDN = 67 to the application TRUE: URL or FQDN missmatch to CN inside the client certificate is ignored.
[in]	bClientMode_Skip_Authorised_Root_CA_Check	we have to make sure that the original CA certificate and the one reported by the server are absolutely identical. We could compare the two certificates in terms of their distinguished names, their signature as well as their public key, but then again they have to be absolutely equal to the last byte! For security reasons, in client mode, the TLS engine not only checks the server's FQDN against the CN presented in its certificate, but also compares the corresponding root CA certificate, which the server is supposed to send along together with the actual server certificate, with the pre-defined one. The idea behind that logic is to make sure that, as client, no connection will be made with a potentially unknown and hence unsafe server. Using this flag (= TRUE) however this restriction can be ignored, if need be. FALSE: a certificate signed by CA is needed. possible ERROR return can be: INTERNAL_BAD_PARAMETER = 750 UNEXPECTED_CA_CERTIFICATE = 71 CERTIFICATE_PARSE = 70 CERTIFICATE_VERIFY = 69 TLS msg. return is: "access denied"; TLS alert is "fatal". TRUE: a self certified certificate is used without CA
[in]	client_certificate_request	New added feature in 1.1. This request is optional in TLS 1.2 and only needed in Server Mode if you want to force the bilateral authentication. 0: no request is send. 1: the Server will send request for the client certificate.
[in]	server_cert[]	pointer to the certificate used in server mode. The certificate need to be in an array of byte in HEX format. See Introduction/Certificate for details about BASE64 to HEX conversion. NULL in client mode.
[in]	len_server_cert	length of the server certificate array, 0 in client mode.
[in]	ca_cert[]	pointer to the CA certificate for verification if parameter bClientMode_Skip_Authorised_Root_CA_Check is FALSE. The certificate need to be in an array of byte in HEX format. See Introduction/Certificate for details about BASE64 to HEX conversion. NULL if bClientMode_Skip_Authorised_Root_CA_Check is TRUE = ignored.
[in]	len_ca_cert	length of the CA certificate array, 0 if bClientMode_Skip_Authorised_Root_CA_Check is TRUE = ignored.
[in]	client_cert[]	pointer to the certificate used in client mode, NULL in server mode. The certificate need to be in an array of byte in HEX format. See Introduction/Certificate for details about BASE64 to HEX conversion.
[in]	len_client_cert	length of the client certificate array, 0 in server mode.
[in]	server_rsa_private_key[]	a: for software crypto it's the concatenated prime1 + prime2 + exponent1 + exponent2 + coefficient (without the leading 0x00) as an HEX coded array of byte = one string. b: for hardware crypto it's only the privateExponent without leading 0x00 NULL in client mode.
[in]	len_server_rsa_private_key	length of the string (e.g. length of RSA 2048 = 640 or 256), 0 in client mode.
[in]	client_rsa_private_key[]	a: for software crypto it's the concatenated prime1 + prime2 + exponent1 + exponent2 + coefficient (without the leading 0x00) as an HEX coded array of byte = one string. b: for hardware crypto it's only the privateExponent without leading 0x00 NULL in server mode
[in]	len_client_rsa_private_key	length of the string (e.g. length of RSA 2048 = 640 or 256) 0 in server mode.

Returns: 0 on success or one of the error codes specified in error.h

int TLSReadAppData	(	const void const	ppCurrentSession,
		UINT8	output_buffer[],
		UINT32 *	len_output_buffer
	)

Reads incoming encrypted application data according to the established (after engine success) session parameters.

Parameters

[in]	ppCurrentSession	Valid session pointer to a session established by TLSEngine().
[in]	output_buffer	Binary array to hold the output data read from the incoming TLS record. Make sure that the buffer is properly sized!
[out]	len_output_buffer	If the read operation has been successful, TLSReadAppData() returns the number of bytes written into output_buffer.

Returns: 0 on success or one of the error codes specified in error.h

int TLSShutdown ( const void ** ppSession )

Closes an existing TLS session and realeases dynamically allocated resources.

Parameters

[in] ppSession Reference to the session pointer as created by TLSEngine().

Returns: 0 on success or one of the error codes specified in error.h

int TLSWriteAppData	(	const void const	ppCurrentSession,
		const UINT8	data[],
		UINT32	len_data
	)

Writes outgoing encrypted app data according to the established TLS session parameters.

Parameters

[in]	ppCurrentSession	Valid session pointer to a session established by TLSEngine().
[in]	data	Buffer that holds application data to be secured and sent to peer.
[in]	len_data	Number of bytes to be processed from data.

Returns: 0 on success or one of the error codes specified in error.h

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Function Documentation