sslsessions.h File Reference

SSL/TLS communication library. More...

#include "gate/net/gate_net_api.h"
#include "gate/strings.h"
#include "gate/streams.h"

Data Structures
struct	gate_ssl_session_params_class
	A set of parameters used to create a TLS/SSL session object. More...

Macros
#define	GATE_SSL_SESSION_TYPE_AUTO   0
#define	GATE_SSL_SESSION_TYPE_SSL_2   0x02
#define	GATE_SSL_SESSION_TYPE_SSL_3   0x03
#define	GATE_SSL_SESSION_TYPE_TLS_1_0   0x10
#define	GATE_SSL_SESSION_TYPE_TLS_1_1   0x11
#define	GATE_SSL_SESSION_TYPE_TLS_1_2   0x12
#define	GATE_SSL_SESSION_TYPE_TLS_1_3   0x13

Typedefs
typedef struct gate_ssl_session_params_class	gate_ssl_session_params_t
	A set of parameters used to create a TLS/SSL session object.

Functions
GATE_NET_API gate_result_t	gate_ssl_init (gate_bool_t crypto_api_only)
	Initializes the ssl library implementation.
GATE_NET_API gate_result_t	gate_ssl_thread_init ()
	Initializes resources for TLS/SSL for the current thread.
GATE_NET_API gate_result_t	gate_ssl_thread_uninit ()
	Releases resources for TLS/SSL allocated on the current thread.
GATE_NET_API gate_result_t	gate_ssl_session_create (gate_ssl_session_params_t const *params, gate_ssl_session_t *session)
	Creates a new TLS/SSL session.
GATE_NET_API gate_result_t	gate_ssl_session_destroy (gate_ssl_session_t session)
	Releases all resources associated with an existing session handle.
GATE_NET_API gate_result_t	gate_ssl_session_is_negotiated (gate_ssl_session_t session, gate_bool_t *completed)
	Queries the session state and indicates if the session is ready to transmit data.
GATE_NET_API gate_result_t	gate_ssl_session_negotiate (gate_ssl_session_t session)
	Processes and generates further negotiation messages.
GATE_NET_API gate_result_t	gate_ssl_session_write (gate_ssl_session_t session, char const *plaindatabuffer, gate_size_t bufferlen, gate_size_t *datawritten)
	Writes plain data into a negotiated TLS/SSL session.
GATE_NET_API gate_result_t	gate_ssl_session_get_encoded_data (gate_ssl_session_t session, char *encodedbuffer, gate_size_t bufferlen, gate_size_t *bufferused)
	Retrieves encoded bytes from the session which are safe to be transmitted to a remote peer.
GATE_NET_API gate_result_t	gate_ssl_session_add_encoded_data (gate_ssl_session_t session, char const *encodedbuffer, gate_size_t bufferlen, gate_size_t *bytesadded)
	Adds encoded data from a remote peer which shall be processed and decoded.
GATE_NET_API gate_result_t	gate_ssl_session_read (gate_ssl_session_t session, char *paindatabuffer, gate_size_t bufferlen, gate_size_t *datareturned)
	Reads decoded data from a TLS/SSL session.
GATE_NET_API gate_result_t	gate_ssl_stream_create (gate_ssl_session_params_t const *params, gate_stream_t *transport_stream, gate_stream_t **ptr_ssl_stream)
	Creates an SSL communication stream.

Detailed Description

SSL/TLS communication library.

Macro Definition Documentation

GATE_SSL_SESSION_TYPE_AUTO

#define GATE_SSL_SESSION_TYPE_AUTO   0

Automatically negotiate the best version of both sides

GATE_SSL_SESSION_TYPE_SSL_2

#define GATE_SSL_SESSION_TYPE_SSL_2   0x02

Use only SSLv2 standard

GATE_SSL_SESSION_TYPE_SSL_3

#define GATE_SSL_SESSION_TYPE_SSL_3   0x03

Use only SSLv3 standard

GATE_SSL_SESSION_TYPE_TLS_1_0

#define GATE_SSL_SESSION_TYPE_TLS_1_0   0x10

Use only TLSv1.0 standard

GATE_SSL_SESSION_TYPE_TLS_1_1

#define GATE_SSL_SESSION_TYPE_TLS_1_1   0x11

Use only TLSv1.1 standard

GATE_SSL_SESSION_TYPE_TLS_1_2

#define GATE_SSL_SESSION_TYPE_TLS_1_2   0x12

Use only TLSv1.2 standard

GATE_SSL_SESSION_TYPE_TLS_1_3

#define GATE_SSL_SESSION_TYPE_TLS_1_3   0x13

Use TLSv1.3 standard or a compatible mode

Function Documentation

gate_ssl_init()

GATE_NET_API gate_result_t gate_ssl_init

(

gate_bool_t

crypto_api_only

)

Initializes the ssl library implementation.

Parameters

crypto_api_only

Loads only crypto functions and skips SSL/TLS functions

Returns

GATE_RESULT_* result code

gate_ssl_thread_init()

GATE_NET_API gate_result_t gate_ssl_thread_init

(

)

Initializes resources for TLS/SSL for the current thread.

Returns

GATE_RESULT_* result code

gate_ssl_thread_uninit()

GATE_NET_API gate_result_t gate_ssl_thread_uninit

(

)

Releases resources for TLS/SSL allocated on the current thread.

Returns

GATE_RESULT_* result code

gate_ssl_session_create()

GATE_NET_API gate_result_t gate_ssl_session_create	(	gate_ssl_session_params_t const *	params,
		gate_ssl_session_t *	session )

Creates a new TLS/SSL session.

Parameters

params	input parameters for the new session
session	new session handle is written to the given address

Returns

GATE_RESULT_* result code

gate_ssl_session_destroy()

GATE_NET_API gate_result_t gate_ssl_session_destroy

(

gate_ssl_session_t

session

)

Releases all resources associated with an existing session handle.

Parameters

session

handle to identify the session which will be destroyed

Returns

GATE_RESULT_* result code

gate_ssl_session_is_negotiated()

GATE_NET_API gate_result_t gate_ssl_session_is_negotiated	(	gate_ssl_session_t	session,
		gate_bool_t *	completed )

Queries the session state and indicates if the session is ready to transmit data.

Parameters

session	handle to identify the session which will be destroyed
completed	output address that receives TRUE if the session is ready to transmit data, otherwhise FALSE

Returns

GATE_RESULT_* result code

gate_ssl_session_negotiate()

GATE_NET_API gate_result_t gate_ssl_session_negotiate

(

gate_ssl_session_t

session

)

Processes and generates further negotiation messages.

Parameters

session

handle to identify the session

Returns

GATE_RESULT_* result code

gate_ssl_session_write()

GATE_NET_API gate_result_t gate_ssl_session_write	(	gate_ssl_session_t	session,
		char const *	plaindatabuffer,
		gate_size_t	bufferlen,
		gate_size_t *	datawritten )

Writes plain data into a negotiated TLS/SSL session.

Parameters

session	handle to identify the session
plaindatabuffer	buffer to data which is going to be encoded
bufferlen	length of plaindatabuffer in bytes
datawritten	pointer to address where the amout of processed bytes are written

Returns

GATE_RESULT_* result code

gate_ssl_session_get_encoded_data()

GATE_NET_API gate_result_t gate_ssl_session_get_encoded_data	(	gate_ssl_session_t	session,
		char *	encodedbuffer,
		gate_size_t	bufferlen,
		gate_size_t *	bufferused )

Retrieves encoded bytes from the session which are safe to be transmitted to a remote peer.

Parameters

session	handle to identify the session
encodedbuffer	pointer to buffer that receives encoded bytes
bufferlen	length of encodedbuffer in bytes
bufferused	pointer to address where the bytes used from the buffer is written to

Returns

GATE_RESULT_* result code

gate_ssl_session_add_encoded_data()

GATE_NET_API gate_result_t gate_ssl_session_add_encoded_data	(	gate_ssl_session_t	session,
		char const *	encodedbuffer,
		gate_size_t	bufferlen,
		gate_size_t *	bytesadded )

Adds encoded data from a remote peer which shall be processed and decoded.

Parameters

session	handle to identify the session
encodedbuffer	pointer to buffer of encoded data received from a remote peer
bufferlen	length of encodedbuffer in bytes
bytesadded	pointer to address where the amount of processed bytes from the buffer is written to

Returns

GATE_RESULT_* result code

gate_ssl_session_read()

GATE_NET_API gate_result_t gate_ssl_session_read	(	gate_ssl_session_t	session,
		char *	paindatabuffer,
		gate_size_t	bufferlen,
		gate_size_t *	datareturned )

Reads decoded data from a TLS/SSL session.

Parameters

session	handle to identify the session
paindatabuffer	pointer to buffer that receives decoded bytes
bufferlen	length of paindatabuffer in bytes
datareturned	pointer to address where the amount of decoded bytes is written to

Returns

GATE_RESULT_* result code

gate_ssl_stream_create()

GATE_NET_API gate_result_t gate_ssl_stream_create	(	gate_ssl_session_params_t const *	params,
		gate_stream_t *	transport_stream,
		gate_stream_t **	ptr_ssl_stream )

Creates an SSL communication stream.

Parameters

[in]	params	SSL/TLS session configuration parameters
[in]	transport_stream	Pointer to input/output stream to transfer encoded SSL/TLS data
[out]	ptr_ssl_stream	Pointer to location where created SSL stream pointer is placed

Returns

GATE_RESULT_* result code