SharkSSL C/C++ Reference
TLS, cryptography, certificates, and PSA integration
Minnow Server

Detailed Description

Compact HTTPS and WebSocket Server.

The Minnow Server is a combined HTTPS and WebSocket server. The HTTPS server main focus is on upgrading HTTPS connections to WebSocket connections as specified in RFC 6455.

See the Minnow Server's home page for an introduction to this product.

See also
WebSocket Client Lib

The following example demonstrates initialization of the WssProtocolHandshake structure so the MS_webServer function can operate as an HTTPS server. In addition to operating as a WebSocket server, (se_accept) returns a new client connection, (SOCKET object) and then a (SharkSslCon) object is created prior to the Web Server function (MS_webServer) being called. The (MS_webServer) function returns an error code for anything that is not a WebSocket upgrade, including valid HTTPS GET requests. The error code signals that we should close the connection and wait for a new connection.

ZipFileSystem zfs;
WssProtocolHandshake wph={0};
wph.fetchPage = msInitZipFileSystem(&zfs, getLedZipReader());
wph.fetchPageHndl=&zfs;
while(se_accept(&listenSock, INFINITE_TMO, &sock) == 1)
{
WssReadState wss={0};
SharkSslCon* scon = SharkSsl_createCon(&sharkSsl);
if( ! MS_webServer(scon,&sock,&wph) )
{
// Successful upgrade: WebSocket code here
}
SharkSsl_terminateCon(&sharkSsl, scon);
se_close(&sock);
}

The MS_webServer function returns 0 when we have successfully upgraded the client HTTPS request to a secure WebSocket connection. At this point, you may either serve the WebSocket connection in the current thread/task or create a new thread/task to handle the new WebSocket connection. Creating a new task/thread is required if you require a WebSocket server that can manage more than one connection. Our included WebSocket examples are single threaded, and all new requests will be pending in our examples until the active WebSocket connection terminates.

Modules

 Minnow Server Error Codes
 Error codes returned by functions in the Minnow Server Lib.
 
 Minnow Server Helper Functions
 Minnow Server Helper Functions.
 
 Minnow Server ZIP File System Plugin
 Optional Minnow Server adapter for an external ZIP reader.
 

Data Structures

struct  WssProtocolHandshake
 The WssProtocolHandshake structure keeps state information for the web server function MS_ebServer. More...
 
struct  WssReadState
 The WS protocol is frame based, and struct WssReadState keeps state information for the Minnow Server's MS_read function. More...
 
struct  MSTBuf
 The Minnow Server Transmission Buffer is used by the Minnow Server Transmission (MST) class when used in non secure mode. More...
 
struct  MST
 The Minnow Server Transmission Class defines a set of functions for reading and writing socket data either in secure mode using SharkSSL or non secure mode. More...
 
struct  MS
 MS: Minnow Server HTTP(S) and (secure) WebSocket Server. More...
 

Macros

#define WSOP_Text   0x81
 
#define WSOP_Binary   0x82
 
#define WSOP_Close   0x88
 
#define WSOP_Ping   0x89
 
#define WSOP_Pong   0x8A
 
#define MAX_HTTP_H_SIZE   20
 
#define MS_constructor(o)   memset(o,0,sizeof(MS))
 Minnow Server Constructor. More...
 
#define MS_setSharkCon(o, sharkCon, socket)
 Set the SharkSSL object and the socket connection after socket select accepts and creates a new server socket. More...
 
#define MS_setSocket(o, socket, rec, recSize, send, sendSize)
 Set the socket connection after socket select accepts and creates a new server socket. More...
 
#define MS_sendBin(o, len)   MS_send(o, WSOP_Binary, len)
 Send a WebSocket binary frame using the SharkSSL zero copy API. More...
 
#define MS_sendText(o, len)   MS_send(o, WSOP_Text, len)
 Send a WebSocket text frame using the SharkSSL zero copy API. More...
 
#define MS_writeBin(o, data, len)   MS_write(o,WSOP_Binary,data,len)
 Sends data as WebSocket text frame(s). More...
 
#define MS_writeText(o, data, len)   MS_write(o,WSOP_Text,data,len)
 Send data as WebSocket binary frame(s). More...
 

Typedefs

typedef int(* MSFetchPage) (void *hndl, struct MST *mst, U8 *path)
 A page fetch callback function used by function MS_ebServer is typically installed when the web application is stored on the device. More...
 
typedef struct MST MST
 The Minnow Server Transmission Class defines a set of functions for reading and writing socket data either in secure mode using SharkSSL or non secure mode. More...
 

Functions

U8 * MST_getSendBufPtr (MST *o)
 Get the send buffer pointer. More...
 
U16 MST_getSendBufSize (MST *o)
 Get the send buffer size. More...
 
int MST_read (MST *o, U8 **buf, U32 timeout)
 Read data to a secure layer or non secure (standard socket) layer. More...
 
int MST_write (MST *o, U8 *buf, int len)
 Write data to a secure layer or non secure (standard socket) layer. More...
 
U8 * MS_respCT (MS *o, int *dlen, int contentLen, const U8 *extHeader)
 Format a HTTP 200 OK response with Content Length. More...
 
int MS_webServer (MS *o, WssProtocolHandshake *wph)
 The Web Server function is responsible for parsing incoming HTTP requests and upgrading HTTP requests to WebSocket connections. More...
 
U8 * MS_prepSend (MS *o, int extSize, int *maxSize)
 Prepare sending a WebSocket frame using one of MS_sendBin or MS_sendText. More...
 
int MS_write (MS *o, U8 opCode, const void *data, int len)
 Function used by the two inline functions (macros) MS_writeBin and MS_writeText. More...
 
int MS_close (MS *o, int statusCode)
 Sends a WebSocket close frame command to the peer and close the socket. More...
 
int MS_read (MS *o, U8 **buf, U32 timeout)
 Waits for WebSocket frames sent by the peer side. More...
 

Macro Definition Documentation

◆ MAX_HTTP_H_SIZE

#define MAX_HTTP_H_SIZE   20

◆ MS_constructor

#define MS_constructor (   o)    memset(o,0,sizeof(MS))

Minnow Server Constructor.

Parameters
oMS instance

◆ MS_sendBin

#define MS_sendBin (   o,
  len 
)    MS_send(o, WSOP_Binary, len)

Send a WebSocket binary frame using the SharkSSL zero copy API.

Parameters
oMinnow Server instance.
lenis the length of the buffer you copied into the pointer returned by MS_prepSend.
Returns
The data length 'len' on success or an Error Code on error.
See also
MS_writeBin

◆ MS_sendText

#define MS_sendText (   o,
  len 
)    MS_send(o, WSOP_Text, len)

Send a WebSocket text frame using the SharkSSL zero copy API.

Parameters
oMinnow Server instance.
lenis the length of the buffer you copied into the pointer returned by MS_prepSend.
Returns
The data length 'len' on success or an Error Code on error.
See also
MS_writeText

◆ MS_setSharkCon

#define MS_setSharkCon (   o,
  sharkCon,
  socket 
)
Value:
(o)->mst.u.sc=sharkCon, \
(o)->mst.sock=socket, \
(o)->mst.isSecure=TRUE

Set the SharkSSL object and the socket connection after socket select accepts and creates a new server socket.

The Minnow server instance will operate in secure (SSL) mode when this function is called.

Parameters
othe Minnow Server (MS) instance
sharkConthe object returned by SharkSsl_createCon
socketthe SOCKET instance created after accepting a new client
See also
MS_setSocket

◆ MS_setSocket

#define MS_setSocket (   o,
  socket,
  rec,
  recSize,
  send,
  sendSize 
)
Value:
(o)->mst.sock=socket, \
(o)->mst.b.recBuf=rec, \
(o)->mst.b.recBufSize=recSize, \
(o)->mst.b.sendBuf=send, \
(o)->mst.b.sendBufSize=sendSize, \
(o)->mst.isSecure=FALSE

Set the socket connection after socket select accepts and creates a new server socket.

The Minnow server instance will operate in non secure mode when this function is called.

Parameters
othe Minnow Server (MS) instance
socketthe SOCKET instance created after accepting a new client
reca buffer the Minnow Server instance can use when receiving data
recSizesize of 'rec' buffer
senda buffer the Minnow Server instance can use when writing data
sendSizesize of 'send' buffer
See also
MS_setSharkCon

◆ MS_writeBin

#define MS_writeBin (   o,
  data,
  len 
)    MS_write(o,WSOP_Binary,data,len)

Sends data as WebSocket text frame(s).

The data will be sent as multiple frames if len is longer than the SharkSSL send buffer size.

Parameters
oMinnow Server instance.
datathe data to send.
lendata length.
Returns
Zero on success or an Error Code on error.
See also
MS_sendBin

◆ MS_writeText

#define MS_writeText (   o,
  data,
  len 
)    MS_write(o,WSOP_Text,data,len)

Send data as WebSocket binary frame(s).

The data will be sent as multiple frames if len is longer than the SharkSSL send buffer size.

Parameters
oMinnow Server instance.
datathe data to send.
lendata length.
Returns
Zero on success or an Error Code on error.
See also
MS_sendText

◆ WSOP_Binary

#define WSOP_Binary   0x82

◆ WSOP_Close

#define WSOP_Close   0x88

◆ WSOP_Ping

#define WSOP_Ping   0x89

◆ WSOP_Pong

#define WSOP_Pong   0x8A

◆ WSOP_Text

#define WSOP_Text   0x81

Typedef Documentation

◆ MSFetchPage

typedef int(* MSFetchPage) (void *hndl, struct MST *mst, U8 *path)

A page fetch callback function used by function MS_ebServer is typically installed when the web application is stored on the device.

See also
ZipFileSystem

◆ MST

typedef struct MST MST

The Minnow Server Transmission Class defines a set of functions for reading and writing socket data either in secure mode using SharkSSL or non secure mode.

Function Documentation

◆ MS_close()

int MS_close ( MS *  o,
int  statusCode 
)

Sends a WebSocket close frame command to the peer and close the socket.

Parameters
oMinnow Server instance.
statusCodeis a WebSocket status code.
Returns
The inverted statusCode on success or an Error Code if sending the close frame command to the peer failed.

◆ MS_prepSend()

U8 * MS_prepSend ( MS *  o,
int  extSize,
int *  maxSize 
)

Prepare sending a WebSocket frame using one of MS_sendBin or MS_sendText.

This function returns a pointer to the SharkSSL send buffer, offset to the start of the WebSocket's payload data. The maximum payload data is returned in 'maxSize'.

Parameters
oMinnow Server instance.
extSizeis a Boolean value that should be set to FALSE if the payload will be less than or equal to 125 bytes. The parameter must be set to TRUE if the payload will be greater than 125 bytes.
maxSizeis an out value set to the SharkSSL buffer size minus the WebSocket frame size.
Returns
The SharkSSL send buffer, offset to the start of the WebSocket's payload data. This function cannot fail.

◆ MS_read()

int MS_read ( MS *  o,
U8 **  buf,
U32  timeout 
)

Waits for WebSocket frames sent by the peer side.

The function returns when data is available or on timeout. The function returns zero on timeout, but the peer can send zero length frames, so you must verify that it is a timeout by checking the status of WssReadState::isTimeout.

The WebSocket protocol is frame based, but the function can return a fragment before the complete WebSocket frame is received if the frame sent by the peer is larger than the SharkSSL receive buffer. The frame length is returned in WssReadState::frameLen, and the data consumed thus far is returned in WssReadState::bytesRead. The complete frame is consumed when frameLen == bytesRead.

Parameters
oMinnow Server instance.
bufis a pointer set to the SharkSSL receive buffer, offset to the start of the WebSocket payload data.
timeoutin milliseconds. The timeout can be set to INFINITE_TMO.
Returns
The payload data length or zero for zero length frames and timeout. The function returns one of the See Error Codes on error. An incomplete control frame that reaches the read timeout closes with status 1001. Ordinary data frames may continue after a timeout.

◆ MS_respCT()

U8 * MS_respCT ( MS *  o,
int *  dlen,
int  contentLen,
const U8 *  extHeader 
)

Format a HTTP 200 OK response with Content Length.

Parameters
oMinnow Server.
dlendestination buffer length.
contentLenContent Lengt.
extHeaderoptional extra header values.
Returns
The input parameter 'dest' on success or NULL if the destination buffer is not sufficiently large for the response.

◆ MS_webServer()

int MS_webServer ( MS *  o,
WssProtocolHandshake *  wph 
)

The Web Server function is responsible for parsing incoming HTTP requests and upgrading HTTP requests to WebSocket connections.

It's main functionality is designed for upgrading an HTTPS request to a WebSocket connection; however, it also includes basic functionality for responding to HTTP static content requests such as fetching HTML files, JavaScript code, etc.

Note: WssProtocolHandshake::fetchPage must have been initialized for the function to respond to HTTP GET requests.

WebSocket upgrades require GET, HTTP/1.1, Host, the Upgrade/Connection tokens, version 13, and a base64 key encoding 16 bytes. Invalid upgrades receive HTTP 400. Split headers must fit the existing send buffer and the available receive storage; larger headers return a size error.

Returns
Zero on successful WebSocket connection upgrade. Returns an error code for all other operations, including fetching static content using the callback MSFetchPage – in this case, MS_ERR_NOT_WEBSOCKET is returned. See Error Codes for more information.
Parameters
oMS *; required initialized server instance bound to the accepted transport.
wphWssProtocolHandshake *; required caller-initialized authentication/page-handler configuration. Receives parsed request/header pointers borrowed from the transport buffer; consume before the next buffer-reusing operation.
Returns
int: 0 for a completed WebSocket upgrade; MS_ERR_NOT_WEBSOCKET after handling an ordinary HTTP request (including a page or 404 response); another negative MS_ERR_* on failure. NOT_WEBSOCKET is not proof that a requested page existed.

◆ MS_write()

int MS_write ( MS *  o,
U8  opCode,
const void *  data,
int  len 
)

Function used by the two inline functions (macros) MS_writeBin and MS_writeText.

Parameters
oMinnow Server instance.
opCodethe WebSocket opcode.
datathe data to send.
lendata length.
Returns
zero success or an Error Code on error.
See also
MS_writeText

◆ MST_getSendBufPtr()

U8 * MST_getSendBufPtr ( MST *  o)

Get the send buffer pointer.

Parameters
oMST *; required initialized Minnow transport with a live socket and configured receive/send buffers or TLS connection.
Returns
U8 *; borrowed writable send buffer. Do not free it or retain it across operations that reuse TLS/transport storage.

◆ MST_getSendBufSize()

U16 MST_getSendBufSize ( MST *  o)

Get the send buffer size.

Parameters
oMST *; required initialized Minnow transport with a live socket and configured receive/send buffers or TLS connection.
Returns
U16; writable send capacity in bytes, for plaintext in a secure transport.

◆ MST_read()

int MST_read ( MST *  o,
U8 **  buf,
U32  timeout 
)

Read data to a secure layer or non secure (standard socket) layer.

Parameters
oMST *; required initialized Minnow transport with a live socket and configured receive/send buffers or TLS connection.
bufU8 **; required output pointer to borrowed received bytes, valid until the next operation reuses the receive/TLS buffer.
timeoutU32; wait in milliseconds, or INFINITE_TMO.
Returns
int: positive byte count, 0 on timeout, negative on socket/TLS failure. The result can be only part of an application message.

◆ MST_write()

int MST_write ( MST *  o,
U8 *  buf,
int  len 
)

Write data to a secure layer or non secure (standard socket) layer.

Rejects negative lengths and zero-copy lengths above the send-buffer capacity before socket I/O.

Parameters
oMST *; required initialized Minnow transport with a live socket and configured receive/send buffers or TLS connection.
bufU8 *; input bytes borrowed for this call, or NULL for data already in the send buffer.
lenint; nonnegative byte count. NULL input must fit MST_getSendBufSize; secure copy-mode input is limited to 65535 bytes.

An incomplete transport write closes the socket.

Returns
int: len after the complete write, or a negative error. A zero length is a no-op.