SharkSSL™ Embedded SSL/TLS Stack
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
datais 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
fmtthe 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
sockthe SOCKET object.
bufis the data to send.
lenis the 'buf' length.
timeoutin 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
sthe SharkSslCon object.
sockthe SOCKET object.
timeoutin milliseconds. The timeout can be set to INFINITE_TMO.
commonNameis 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
sthe SharkSslCon object.
sockthe SOCKET object.
bufis a pointer set to the SharkSSL receive buffer offset to the WebSocket payload data.
timeoutin 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.