TLS

Typedefs
typedef struct _tf_tls_context_t	tf_tls_context_t
typedef struct _tf_tls_session_t	tf_tls_session_t
typedef enum _tf_tls_handshake_t	tf_tls_handshake_t
typedef enum _tf_tls_read_t	tf_tls_read_t

Enumerations
enum	_tf_tls_handshake_t { k_tls_handshake_done , k_tls_handshake_more , k_tls_handshake_failed }
enum	_tf_tls_read_t { k_tls_read_zero = -1 , k_tls_read_failed = -2 }

Functions
tf_tls_context_t *	tf_tls_context_create ()
bool	tf_tls_context_set_certificate (tf_tls_context_t *context, const char *certificate)
bool	tf_tls_context_set_private_key (tf_tls_context_t *context, const char *private_key)
bool	tf_tls_context_add_trusted_certificate (tf_tls_context_t *context, const char *certificate)
tf_tls_session_t *	tf_tls_context_create_session (tf_tls_context_t *context)
void	tf_tls_context_destroy (tf_tls_context_t *context)
void	tf_tls_session_destroy (tf_tls_session_t *session)
void	tf_tls_session_set_hostname (tf_tls_session_t *session, const char *hostname)
void	tf_tls_session_start_accept (tf_tls_session_t *session)
void	tf_tls_session_start_connect (tf_tls_session_t *session)
void	tf_tls_session_shutdown (tf_tls_session_t *session)
int	tf_tls_session_get_peer_certificate (tf_tls_session_t *session, char *buffer, size_t bytes)
tf_tls_handshake_t	tf_tls_session_handshake (tf_tls_session_t *session)
int	tf_tls_session_read_plain (tf_tls_session_t *session, char *buffer, size_t bytes)
int	tf_tls_session_write_plain (tf_tls_session_t *session, const char *buffer, size_t bytes)
int	tf_tls_session_read_encrypted (tf_tls_session_t *session, char *buffer, size_t bytes)
int	tf_tls_session_write_encrypted (tf_tls_session_t *session, const char *buffer, size_t bytes)
bool	tf_tls_session_get_error (tf_tls_session_t *session, char *buffer, size_t bytes)

Detailed Description

A minimal wrapper around OpenSSL.

Typedef Documentation

tf_tls_context_t

typedef struct _tf_tls_context_t tf_tls_context_t

A TLS context. May have many tf_tls_session_t instances.

tf_tls_handshake_t

typedef enum _tf_tls_handshake_t tf_tls_handshake_t

The state of a TLS handshake.

tf_tls_read_t

typedef enum _tf_tls_read_t tf_tls_read_t

Possible error statuses from tf_tls_session_read_plain.

tf_tls_session_t

typedef struct _tf_tls_session_t tf_tls_session_t

A TLS session. Belongs to one tf_tls_context_t and represents a single connection.

Enumeration Type Documentation

_tf_tls_handshake_t

enum _tf_tls_handshake_t

The state of a TLS handshake.

_tf_tls_read_t

enum _tf_tls_read_t

Possible error statuses from tf_tls_session_read_plain.

Function Documentation

tf_tls_context_add_trusted_certificate()

bool tf_tls_context_add_trusted_certificate	(	tf_tls_context_t *	context,
		const char *	certificate
	)

Add a trusted certificate.

Parameters

context	The TLS context.
certificate	The certificate in PEM format.

Returns

true if the certificate was added to the trusted list successfully.

tf_tls_context_create()

tf_tls_context_t * tf_tls_context_create

(

)

Create a TLS context. Clean up with tf_tls_context_destroy().

Returns

A new TLS context.

tf_tls_context_create_session()

tf_tls_session_t * tf_tls_context_create_session

(

tf_tls_context_t *

context

)

Create a TLS session from a context. Once created, call tf_tls_session_handshake() until it returns k_tls_handshake_done. Call tf_tls_session_[read/write]_[plain/encrypted]() as data is available.

Parameters

context

The TLS context. Clean up with tf_tls_session_destroy().

Returns

A new TLS session.

tf_tls_context_destroy()

void tf_tls_context_destroy

(

tf_tls_context_t *

context

)

Destroy a TLS context.

Parameters

context

The TLS contextx created by tf_tls_context_create().

tf_tls_context_set_certificate()

bool tf_tls_context_set_certificate	(	tf_tls_context_t *	context,
		const char *	certificate
	)

Set the TLS context's server certificate.

Parameters

context	The TLS context.
certificate	The certificate in PEM format.

Returns

true if set successfully.

tf_tls_context_set_private_key()

bool tf_tls_context_set_private_key	(	tf_tls_context_t *	context,
		const char *	private_key
	)

Set the TLS context's server certificate's private key.

Parameters

context	The TLS context.
private_key	The private key in PEM format.

Returns

true if set successfully.

tf_tls_session_destroy()

void tf_tls_session_destroy

(

tf_tls_session_t *

session

)

Destroy a TLS session.

Parameters

session

A TLS sesssion created by tf_tls_context_create_session().

tf_tls_session_get_error()

bool tf_tls_session_get_error	(	tf_tls_session_t *	session,
		char *	buffer,
		size_t	bytes
	)

Retrieve the last error from a TLS session.

Parameters

session	The TLS session.
buffer	A buffer to receive the error text.
bytes	The size of the buffer.

Returns

true if an error was retrieved.

tf_tls_session_get_peer_certificate()

int tf_tls_session_get_peer_certificate	(	tf_tls_session_t *	session,
		char *	buffer,
		size_t	bytes
	)

Get the certificate from the remote end of a TLS session if available.

Parameters

session	The TLS session.
buffer	A buffer to receive the certificate.
bytes	The size of the buffer.

Returns

The size of the returned certificate, or -1 on failure.

tf_tls_session_handshake()

tf_tls_handshake_t tf_tls_session_handshake

(

tf_tls_session_t *

session

)

Update the TLS handshake. Call repeatedly as new data is available until it returns done.

Parameters

session

The TLS session.

Returns

The current state of the handshake process.

tf_tls_session_read_encrypted()

int tf_tls_session_read_encrypted	(	tf_tls_session_t *	session,
		char *	buffer,
		size_t	bytes
	)

Read encrypted data from the TLS session that needs to be sent.

Parameters

session	The TLS session.
buffer	A buffer to receive the data.
bytes	The size of the buffer.

Returns

The number of bytes returned.

tf_tls_session_read_plain()

int tf_tls_session_read_plain	(	tf_tls_session_t *	session,
		char *	buffer,
		size_t	bytes
	)

Read decrypted data from the TLS session.

Parameters

session	The TLS session.
buffer	A buffer to receive the data.
bytes	The size of the buffer.

Returns

The number of bytes returned.

tf_tls_session_set_hostname()

void tf_tls_session_set_hostname	(	tf_tls_session_t *	session,
		const char *	hostname
	)

Set the remote hostname for a session.

Parameters

session	The TLS session.
hostname	The hostname.

tf_tls_session_shutdown()

void tf_tls_session_shutdown

(

tf_tls_session_t *

session

)

Begin the clean shutdown process for a TLS session.

Parameters

session

The TLS session.

tf_tls_session_start_accept()

void tf_tls_session_start_accept

(

tf_tls_session_t *

session

)

Begin an outgoing TLS session.

Parameters

session

The TLS session.

tf_tls_session_start_connect()

void tf_tls_session_start_connect

(

tf_tls_session_t *

session

)

Begin an incoming TLS session.

Parameters

session

The TLS session.

tf_tls_session_write_encrypted()

int tf_tls_session_write_encrypted	(	tf_tls_session_t *	session,
		const char *	buffer,
		size_t	bytes
	)

Write encrypted data to the TLS session.

Parameters

session	The TLS session.
buffer	The encrypted data.
bytes	The number of bytes written.

tf_tls_session_write_plain()

int tf_tls_session_write_plain	(	tf_tls_session_t *	session,
		const char *	buffer,
		size_t	bytes
	)

Write unencrypted data to the TLS session.

Parameters

session	The TLS session.
buffer	The data to encrypt.
bytes	The size of the data.

Returns

1 on success, 0 on failure.