TLS configuration

Macros
#define	TLS_EVENT_CODE_ALM_ALGO_NOT_SUPPORTED   1
#define	TLS_EVENT_CODE_ALM_UNSECURE_COMMUNICATION   2
#define	TLS_EVENT_CODE_ALM_CERT_UNAVAILABLE   3
#define	TLS_EVENT_CODE_ALM_BAD_CERT   4
#define	TLS_EVENT_CODE_ALM_CERT_SIZE_EXCEEDED   5
#define	TLS_EVENT_CODE_ALM_CERT_VALIDATION_FAILED   6
#define	TLS_EVENT_CODE_ALM_CERT_REQUIRED   7
#define	TLS_EVENT_CODE_ALM_HANDSHAKE_FAILED_UNKNOWN_REASON   8
#define	TLS_EVENT_CODE_WRN_INSECURE_TLS_VERSION   9
#define	TLS_EVENT_CODE_INF_SESSION_RENEGOTIATION   10
#define	TLS_EVENT_CODE_ALM_CERT_EXPIRED   11
#define	TLS_EVENT_CODE_ALM_CERT_REVOKED   12
#define	TLS_EVENT_CODE_ALM_CERT_NOT_CONFIGURED   13
#define	TLS_EVENT_CODE_ALM_CERT_NOT_TRUSTED   14
#define	TLS_EVENT_CODE_ALM_NO_CIPHER   15
#define	TLS_EVENT_CODE_INF_SESSION_ESTABLISHED   16

Typedefs
typedef struct sTLSConfiguration *	TLSConfiguration
typedef struct sTLSConnection *	TLSConnection
typedef void(*	TLSConfiguration_EventHandler) (void *parameter, TLSEventLevel eventLevel, int eventCode, const char *message, TLSConnection con)

Enumerations
enum	TLSConfigVersion {   TLS_VERSION_NOT_SELECTED = 0 , TLS_VERSION_SSL_3_0 = 3 , TLS_VERSION_TLS_1_0 = 4 , TLS_VERSION_TLS_1_1 = 5 ,   TLS_VERSION_TLS_1_2 = 6 , TLS_VERSION_TLS_1_3 = 7 }
enum	TLSEventLevel { TLS_SEC_EVT_INFO = 0 , TLS_SEC_EVT_WARNING = 1 , TLS_SEC_EVT_INCIDENT = 2 }

Functions
PAL_API TLSConfiguration	TLSConfiguration_create (void)
	Create a new TLSConfiguration object to represent TLS configuration and certificates and set owner count to 1.
PAL_API TLSConfiguration	TLSConfiguration_claimOwnership (TLSConfiguration self)
	Increase the owner count.
PAL_API void	TLSConfiguration_setClientMode (TLSConfiguration self)
PAL_API const char *	TLSConfigVersion_toString (TLSConfigVersion version)
	Convert TLS version number to string.
PAL_API char *	TLSConnection_getPeerAddress (TLSConnection self, char *peerAddrBuf)
	Get the peer address of the TLS connection.
PAL_API uint8_t *	TLSConnection_getPeerCertificate (TLSConnection self, int *certSize)
	Get the TLS certificate used by the peer.
PAL_API TLSConfigVersion	TLSConnection_getTLSVersion (TLSConnection self)
	Get the TLS version used by the connection.
PAL_API void	TLSConfiguration_setEventHandler (TLSConfiguration self, TLSConfiguration_EventHandler handler, void *parameter)
	Set the security event handler.
PAL_API void	TLSConfiguration_enableSessionResumption (TLSConfiguration self, bool enable)
	enable or disable TLS session resumption (default: enabled)
PAL_API void	TLSConfiguration_setSessionResumptionInterval (TLSConfiguration self, int intervalInSeconds)
	Set the maximum life time of a cached TLS session for session resumption in seconds.
PAL_API void	TLSConfiguration_setChainValidation (TLSConfiguration self, bool value)
	Enables the validation of the certificate trust chain (enabled by default)
PAL_API void	TLSConfiguration_setAllowOnlyKnownCertificates (TLSConfiguration self, bool value)
	Set if only known certificates are accepted.
PAL_API bool	TLSConfiguration_setOwnCertificate (TLSConfiguration self, uint8_t *certificate, int certLen)
	Set own certificate (identity) from a byte buffer.
PAL_API bool	TLSConfiguration_setOwnCertificateFromFile (TLSConfiguration self, const char *filename)
	Set own certificate (identity) from a certificate file.
PAL_API bool	TLSConfiguration_setOwnKey (TLSConfiguration self, uint8_t *key, int keyLen, const char *keyPassword)
	Set the own private key from a byte buffer.
PAL_API bool	TLSConfiguration_setOwnKeyFromFile (TLSConfiguration self, const char *filename, const char *keyPassword)
	Set the own private key from a key file.
PAL_API bool	TLSConfiguration_addAllowedCertificate (TLSConfiguration self, uint8_t *certificate, int certLen)
PAL_API bool	TLSConfiguration_addAllowedCertificateFromFile (TLSConfiguration self, const char *filename)
	Add a certificate to the list of allowed peer certificates.
PAL_API bool	TLSConfiguration_addCACertificate (TLSConfiguration self, uint8_t *certificate, int certLen)
	Add a CA certificate used to validate peer certificates from a byte buffer.
PAL_API bool	TLSConfiguration_addCACertificateFromFile (TLSConfiguration self, const char *filename)
	Add a CA certificate used to validate peer certificates from a file.
PAL_API void	TLSConfiguration_setRenegotiationTime (TLSConfiguration self, int timeInMs)
	Set the renegotiation timeout.
PAL_API void	TLSConfiguration_setMinTlsVersion (TLSConfiguration self, TLSConfigVersion version)
	Set minimal allowed TLS version to use.
PAL_API void	TLSConfiguration_setMaxTlsVersion (TLSConfiguration self, TLSConfigVersion version)
	Set maximal allowed TLS version to use.
PAL_API bool	TLSConfiguration_addCRL (TLSConfiguration self, uint8_t *crl, int crlLen)
	Add a CRL (certificate revocation list) from buffer.
PAL_API bool	TLSConfiguration_addCRLFromFile (TLSConfiguration self, const char *filename)
	Add a CRL (certificate revocation list) from a file.
PAL_API void	TLSConfiguration_resetCRL (TLSConfiguration self)
	Removes any CRL (certificate revocation list) currently in use.
PAL_API void	TLSConfiguration_addCipherSuite (TLSConfiguration self, int ciphersuite)
	Add an allowed ciphersuite to the list of allowed ciphersuites.
PAL_API void	TLSConfiguration_clearCipherSuiteList (TLSConfiguration self)
	Clear the list of allowed ciphersuites.
PAL_API void	TLSConfiguration_destroy (TLSConfiguration self)
	Release all resource allocated by the TLSConfiguration instance or decrease owner count.

Detailed Description

Macro Definition Documentation

TLS_EVENT_CODE_ALM_ALGO_NOT_SUPPORTED

#define TLS_EVENT_CODE_ALM_ALGO_NOT_SUPPORTED   1

TLS_EVENT_CODE_ALM_BAD_CERT

#define TLS_EVENT_CODE_ALM_BAD_CERT   4

TLS_EVENT_CODE_ALM_CERT_EXPIRED

#define TLS_EVENT_CODE_ALM_CERT_EXPIRED   11

TLS_EVENT_CODE_ALM_CERT_NOT_CONFIGURED

#define TLS_EVENT_CODE_ALM_CERT_NOT_CONFIGURED   13

TLS_EVENT_CODE_ALM_CERT_NOT_TRUSTED

#define TLS_EVENT_CODE_ALM_CERT_NOT_TRUSTED   14

TLS_EVENT_CODE_ALM_CERT_REQUIRED

#define TLS_EVENT_CODE_ALM_CERT_REQUIRED   7

TLS_EVENT_CODE_ALM_CERT_REVOKED

#define TLS_EVENT_CODE_ALM_CERT_REVOKED   12

TLS_EVENT_CODE_ALM_CERT_SIZE_EXCEEDED

#define TLS_EVENT_CODE_ALM_CERT_SIZE_EXCEEDED   5

TLS_EVENT_CODE_ALM_CERT_UNAVAILABLE

#define TLS_EVENT_CODE_ALM_CERT_UNAVAILABLE   3

TLS_EVENT_CODE_ALM_CERT_VALIDATION_FAILED

#define TLS_EVENT_CODE_ALM_CERT_VALIDATION_FAILED   6

TLS_EVENT_CODE_ALM_HANDSHAKE_FAILED_UNKNOWN_REASON

#define TLS_EVENT_CODE_ALM_HANDSHAKE_FAILED_UNKNOWN_REASON   8

TLS_EVENT_CODE_ALM_NO_CIPHER

#define TLS_EVENT_CODE_ALM_NO_CIPHER   15

TLS_EVENT_CODE_ALM_UNSECURE_COMMUNICATION

#define TLS_EVENT_CODE_ALM_UNSECURE_COMMUNICATION   2

TLS_EVENT_CODE_INF_SESSION_ESTABLISHED

#define TLS_EVENT_CODE_INF_SESSION_ESTABLISHED   16

TLS_EVENT_CODE_INF_SESSION_RENEGOTIATION

#define TLS_EVENT_CODE_INF_SESSION_RENEGOTIATION   10

TLS_EVENT_CODE_WRN_INSECURE_TLS_VERSION

#define TLS_EVENT_CODE_WRN_INSECURE_TLS_VERSION   9

Typedef Documentation

TLSConfiguration

typedef struct sTLSConfiguration* TLSConfiguration

TLSConfiguration_EventHandler

typedef void(* TLSConfiguration_EventHandler) (void *parameter, TLSEventLevel eventLevel, int eventCode, const char *message, TLSConnection con)

TLSConnection

typedef struct sTLSConnection* TLSConnection

Enumeration Type Documentation

TLSConfigVersion

enum TLSConfigVersion

Enumerator
TLS_VERSION_NOT_SELECTED
TLS_VERSION_SSL_3_0
TLS_VERSION_TLS_1_0
TLS_VERSION_TLS_1_1
TLS_VERSION_TLS_1_2
TLS_VERSION_TLS_1_3

TLSEventLevel

enum TLSEventLevel

Enumerator
TLS_SEC_EVT_INFO
TLS_SEC_EVT_WARNING
TLS_SEC_EVT_INCIDENT

Function Documentation

TLSConfiguration_addAllowedCertificate()

PAL_API bool TLSConfiguration_addAllowedCertificate	(	TLSConfiguration	self,
		uint8_t *	certificate,
		int	certLen )

Add a certificate to the list of allowed peer certificates from a byte buffer

Parameters

certificate	the certificate buffer
certLen	the length of the certificate buffer

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_addAllowedCertificateFromFile()

PAL_API bool TLSConfiguration_addAllowedCertificateFromFile	(	TLSConfiguration	self,
		const char *	filename )

Add a certificate to the list of allowed peer certificates.

Parameters

filename

filename of the certificate file

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_addCACertificate()

PAL_API bool TLSConfiguration_addCACertificate	(	TLSConfiguration	self,
		uint8_t *	certificate,
		int	certLen )

Add a CA certificate used to validate peer certificates from a byte buffer.

Parameters

certificate	the certificate buffer
certLen	the length of the certificate buffer

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_addCACertificateFromFile()

PAL_API bool TLSConfiguration_addCACertificateFromFile	(	TLSConfiguration	self,
		const char *	filename )

Add a CA certificate used to validate peer certificates from a file.

Parameters

filename

filename of the certificate file

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_addCipherSuite()

PAL_API void TLSConfiguration_addCipherSuite	(	TLSConfiguration	self,
		int	ciphersuite )

Add an allowed ciphersuite to the list of allowed ciphersuites.

Parameters

self	the TLS configuration instance
ciphersuite	the ciphersuite to add (IANA cipher suite ID)

TLSConfiguration_addCRL()

PAL_API bool TLSConfiguration_addCRL	(	TLSConfiguration	self,
		uint8_t *	crl,
		int	crlLen )

Add a CRL (certificate revocation list) from buffer.

Parameters

crl	the buffer containing the CRL
crlLen	the length of the CRL buffer

Returns

true, when the CRL was imported, false otherwise (e.g. unknown format)

TLSConfiguration_addCRLFromFile()

PAL_API bool TLSConfiguration_addCRLFromFile	(	TLSConfiguration	self,
		const char *	filename )

Add a CRL (certificate revocation list) from a file.

Parameters

filename

filename of the CRL file

Returns

true, when the CRL was imported, false otherwise (e.g. unknown format)

TLSConfiguration_claimOwnership()

PAL_API TLSConfiguration TLSConfiguration_claimOwnership

(

TLSConfiguration

self

)

Increase the owner count.

Note

Every owner has to call TLSConfiguration_destroy separately.

Parameters

self	the TLSConfiguration instance

TLSConfiguration_clearCipherSuiteList()

PAL_API void TLSConfiguration_clearCipherSuiteList

(

TLSConfiguration

self

)

Clear the list of allowed ciphersuites.

Parameters

self	the TLS configuration instance

TLSConfiguration_create()

PAL_API TLSConfiguration TLSConfiguration_create

(

void

)

Create a new TLSConfiguration object to represent TLS configuration and certificates and set owner count to 1.

WARNING: Configuration cannot be changed after using for the first time.

Returns

the new TLS configuration

TLSConfiguration_destroy()

PAL_API void TLSConfiguration_destroy

(

TLSConfiguration

self

)

Release all resource allocated by the TLSConfiguration instance or decrease owner count.

NOTE: Do not use the object after calling this function!

Parameters

self	the TLS configuration instance

TLSConfiguration_enableSessionResumption()

PAL_API void TLSConfiguration_enableSessionResumption	(	TLSConfiguration	self,
		bool	enable )

enable or disable TLS session resumption (default: enabled)

NOTE: Depending on the used TLS version this is implemented by session IDs or by session tickets.

Parameters

enable

true to enable session resumption, false otherwise

TLSConfiguration_resetCRL()

PAL_API void TLSConfiguration_resetCRL

(

TLSConfiguration

self

)

Removes any CRL (certificate revocation list) currently in use.

TLSConfiguration_setAllowOnlyKnownCertificates()

PAL_API void TLSConfiguration_setAllowOnlyKnownCertificates	(	TLSConfiguration	self,
		bool	value )

Set if only known certificates are accepted.

If set to true only known certificates are accepted. Connections with unknown certificates are rejected even if they are signed by a trusted authority.

Parameters

value

true to enable setting, false otherwise

TLSConfiguration_setChainValidation()

PAL_API void TLSConfiguration_setChainValidation	(	TLSConfiguration	self,
		bool	value )

Enables the validation of the certificate trust chain (enabled by default)

Parameters

value

true to enable chain validation, false to disable

TLSConfiguration_setClientMode()

PAL_API void TLSConfiguration_setClientMode

(

TLSConfiguration

self

)

TLSConfiguration_setEventHandler()

PAL_API void TLSConfiguration_setEventHandler	(	TLSConfiguration	self,
		TLSConfiguration_EventHandler	handler,
		void *	parameter )

Set the security event handler.

Parameters

handler	the security event callback handler
parameter	user provided parameter to be passed to the callback handler

TLSConfiguration_setMaxTlsVersion()

PAL_API void TLSConfiguration_setMaxTlsVersion	(	TLSConfiguration	self,
		TLSConfigVersion	version )

Set maximal allowed TLS version to use.

TLSConfiguration_setMinTlsVersion()

PAL_API void TLSConfiguration_setMinTlsVersion	(	TLSConfiguration	self,
		TLSConfigVersion	version )

Set minimal allowed TLS version to use.

TLSConfiguration_setOwnCertificate()

PAL_API bool TLSConfiguration_setOwnCertificate	(	TLSConfiguration	self,
		uint8_t *	certificate,
		int	certLen )

Set own certificate (identity) from a byte buffer.

Parameters

certificate	the certificate buffer
certLen	the lenght of the certificate

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_setOwnCertificateFromFile()

PAL_API bool TLSConfiguration_setOwnCertificateFromFile	(	TLSConfiguration	self,
		const char *	filename )

Set own certificate (identity) from a certificate file.

Parameters

filename

of the certificate file

Returns

true, when the certificate was set, false otherwise (e.g. unknown certificate format)

TLSConfiguration_setOwnKey()

PAL_API bool TLSConfiguration_setOwnKey	(	TLSConfiguration	self,
		uint8_t *	key,
		int	keyLen,
		const char *	keyPassword )

Set the own private key from a byte buffer.

Parameters

key	the private key to use
keyLen	the length of the key
password	the password of the key or null if the key is not password protected

Returns

true, when the key was set, false otherwise (e.g. unknown key format)

TLSConfiguration_setOwnKeyFromFile()

PAL_API bool TLSConfiguration_setOwnKeyFromFile	(	TLSConfiguration	self,
		const char *	filename,
		const char *	keyPassword )

Set the own private key from a key file.

Parameters

filename	filename/path of the key file
password	the password of the key or null if the key is not password protected

Returns

true, when the key was set, false otherwise (e.g. unknown key format)

TLSConfiguration_setRenegotiationTime()

PAL_API void TLSConfiguration_setRenegotiationTime	(	TLSConfiguration	self,
		int	timeInMs )

Set the renegotiation timeout.

After the timeout elapsed a TLS session renegotiation has to occur.

Parameters

timeInMs

session renegotiation timeout in milliseconds

TLSConfiguration_setSessionResumptionInterval()

PAL_API void TLSConfiguration_setSessionResumptionInterval	(	TLSConfiguration	self,
		int	intervalInSeconds )

Set the maximum life time of a cached TLS session for session resumption in seconds.

Parameters

intervalInSeconds

the maximum lifetime of a cached TLS session

TLSConfigVersion_toString()

PAL_API const char * TLSConfigVersion_toString

(

TLSConfigVersion

version

)

Convert TLS version number to string.

Parameters

version

TLS version number

Returns

the TLS version as null terminated string

TLSConnection_getPeerAddress()

PAL_API char * TLSConnection_getPeerAddress	(	TLSConnection	self,
		char *	peerAddrBuf )

Get the peer address of the TLS connection.

Parameters

self	the TLS connection instance
peerAddrBuf	user provided buffer that can hold at least 60 characters, or NULL to allow the function to allocate the memory for the buffer

Returns

peer address:port as null terminated string

TLSConnection_getPeerCertificate()

PAL_API uint8_t * TLSConnection_getPeerCertificate	(	TLSConnection	self,
		int *	certSize )

Get the TLS certificate used by the peer.

Parameters

self	the TLS connection instance
certSize[OUT]	the certificate size in bytes

Returns

address of the certificate buffer

TLSConnection_getTLSVersion()

PAL_API TLSConfigVersion TLSConnection_getTLSVersion

(

TLSConnection

self

)

Get the TLS version used by the connection.

Parameters

self	the TLS connection instance

Returns

TLS version