SharkSSL Socket Example Lib

Detailed Description

The SharkSSL Socket Example Lib (selib.h/selib.c) is a basic module that wraps the transport agnostic SharkSSL functions for encoding and decoding into functions that interface to TCP/IP socket calls.

Socket Example Lib

In addition, the file selib.c includes wrappers for standard BSD socket calls at the end of the file. TCP/IP stacks not using the BSD API must define NO_BSD_SOCK and implement the following functions in a separate file: se_bind, se_accept, se_connect, se_close, se_sockValid, se_send, and se_recv.

Modules
	Bare Metal Systems

Macros
#define	INFINITE_TMO   (~((U32)0))
	Use INFINITE_TMO for standard blocking call.
#define	SOCKET   int
	Infinite wait time option for socket read functions. More...
#define	printCiphersuite(notused)
	Print the selected ciphersuite.
#define	xprintf(data)   _xprintf data
	The macro xprintf expands to function _xprintf if the code is compiled with XPRINTF set to 1. More...

Functions
void	se_disableTrace (int disable)
	Disable/enable the trace when XPRINTF is defined.
int	seSec_handshake (SharkSslCon *s, SOCKET *sock, U32 timeout, const char *commonName)
	Performs the initial SSL handshaking using an asymmetric cipher in order to establish cipher settings and a shared key for the session. More...
int	seSec_read (SharkSslCon *s, SOCKET *sock, U8 **buf, U32 timeout)
	Read data from socket stream and decode the encrypted data. More...
int	seSec_write (SharkSslCon *s, SOCKET *sock, U8 *buf, int maxLen)
	Encrypts and sends encrypted data to the connected peer side. More...
int	se_connect (SOCKET *sock, const char *address, U16 port)
	Initializes a SOCKET object connected to a remote host/address at a given port. More...
int	se_bind (SOCKET *sock, U16 port)
	Initializes a SOCKET object bound to a local port, ready to accept client connections. More...
int	se_accept (SOCKET **listenSock, U32 timeout, SOCKET **outSock)
	Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection. More...
void	se_close (SOCKET *sock)
	Close a connected socket connection.
int	se_sockValid (SOCKET *sock)
	Returns TRUE if socket is valid (connected).
S32	se_send (SOCKET *sock, const void *buf, U32 len)
	Sends data to the connected peer.
S32	se_recv (SOCKET *sock, void *buf, U32 len, U32 timeout)
	Waits for data sent by peer. More...
void	_xprintf (const char *fmt,...)
	The example code and macro xprintf requires this function when the code is compiled with macro XPRINTF set to 1. More...
void	mainTask (SeCtx *ctx)
	Main entry for all example programs.

Macro Definition Documentation

SOCKET

#define SOCKET   int

Infinite wait time option for socket read functions.

The SOCKET object/handle is an 'int' when using a BSD compatible TCP/IP stack. Non BSD compatible TCP IP stacks must set the macro NO_BSD_SOCK and define the SOCKET object. See the header file selib.h for details.

xprintf

#define xprintf

(

data

)

_xprintf data

The macro xprintf expands to function _xprintf if the code is compiled with XPRINTF set to 1.

Parameters

data	is standard printf arguments enclosed in parenthesis; thus you must use double parenthesis when using macro xprintf.

Function Documentation

_xprintf()

void _xprintf	(	const char *	fmt,
			...
	)

The example code and macro xprintf requires this function when the code is compiled with macro XPRINTF set to 1.

Parameters

fmt	the format string.
...	variable arguments.

se_accept()

int se_accept	(	SOCKET **	listenSock,
		U32	timeout,
		SOCKET **	outSock
	)

Waits for remote connections on the server SOCKET object 'listenSock', initialized by function se_bind, and initializes socket object 'outSock' to represent the new connection.

Returns

• 1 Success
• 0 timeout
• -1 error

se_bind()

int se_bind	(	SOCKET *	sock,
		U16	port
	)

Initializes a SOCKET object bound to a local port, ready to accept client connections.

Returns

Zero on success. Error codes returned:

• -1 Cannot create socket: Fatal
• -2 Cannot listen: Fatal
• -3 Cannot bind: socket in use

se_connect()

int se_connect	(	SOCKET *	sock,
		const char *	address,
		U16	port
	)

Initializes a SOCKET object connected to a remote host/address at a given port.

Returns

Zero on success. Error codes returned:

• -1 Cannot create socket: Fatal
• -2 Cannot resolve 'address'
• -3 Cannot connect

se_recv()

S32 se_recv	(	SOCKET *	sock,
		void *	buf,
		U32	len,
		U32	timeout
	)

Waits for data sent by peer.

Parameters

sock	the SOCKET object.
buf	is the data to send.
len	is the 'buf' length.
timeout	in milliseconds. The timeout can be set to INFINITE_TMO.

Returns

the length of the data read, zero on timeout, or a negative value on error.

seSec_handshake()

int seSec_handshake	(	SharkSslCon *	s,
		SOCKET *	sock,
		U32	timeout,
		const char *	commonName
	)

Performs the initial SSL handshaking using an asymmetric cipher in order to establish cipher settings and a shared key for the session.

The function also validates the server's certificate and compares the commonName provided in argument 3 with the common name in the certificate, if commonName is provided (not NULL). The domain name comparison works with the clone certificate API.

Note: the function only performs basic certificate domain name comparison and can only be used with server certificates that does not include Subject Alternative Names (SAN Certificate). Use the more advanced function SharkSslCon_trusted for certificate trust management if the server uses a SAN Certificate.

Parameters

s	the SharkSslCon object.
sock	the SOCKET object.
timeout	in milliseconds. The timeout can be set to INFINITE_TMO.
commonName	is optional and is used for certificate domain name verification.

Returns

• A negative value on error. The negative value is an inverted SharkSslCon_RetVal value.
• Zero on timeout.
• The return value is SharkSslConTrust for any return value greater than zero.

seSec_read()

int seSec_read	(	SharkSslCon *	s,
		SOCKET *	sock,
		U8 **	buf,
		U32	timeout
	)

Read data from socket stream and decode the encrypted data.

The buffer is managed by SharkSSL and the data returned is valid until the next SharkSSL call. This function blocks until data is available or until 'timeout' milliseconds.

Parameters

s	the SharkSslCon object.
sock	the SOCKET object.
buf	is a pointer set to the SharkSSL receive buffer offset to the WebSocket payload data.
timeout	in milliseconds. The timeout can be set to INFINITE_TMO.

Returns

The function returns the number of bytes available in 'buf' on success. The function returns 0 on timeout and a negative value on error.

seSec_write()

int seSec_write	(	SharkSslCon *	s,
		SOCKET *	sock,
		U8 *	buf,
		int	maxLen
	)

Encrypts and sends encrypted data to the connected peer side.

Returns

Zero on success or a negative value on error.