Real Time Logic LLC / SharkSSL-Lite

This package includes the SharkSSL lite library and header files.

Dependents:   WebSocket-Client-Example SharkMQ-LED-Demo

SharkSSL-Lite

Description: SharkSSL is an SSL v3.0 TLS v1.0/1.1/1.2 implementation of the TLS and SSL protocol standard. With its array of compile-time options and Raycrypto proprietary cryptographic algorithms, SharkSSL can be fine-tuned to a footprint that occupies less than 20 kB, while maintaining full x.509 authentication. The SharkSSL-Lite download includes a subset of SharkSSL and header files made for use in non-commercial and for evaluation purposes.

Features

Examples

Limitations

SharkSSL-Lite includes a limited set of ciphers. To use SharkSSL-Lite, the peer side must support Elliptic Curve Cryptography (ECC) and you must use ECC certificates. The peer side must also support the new ChaCha20/Poly1305 cipher combination.

ChaCha20 and Poly1305 for TLS is published RFC 7905. The development of this new cipher was a response to many attacks discovered against other widely used TLS cipher suites. ChaCha20 is the cipher and Poly1305 is an authenticated encryption mode.

SharkSSL-Lite occupies less than 20kB, while maintaining full x.509 authentication. The ChaCha20/Poly1305 cipher software implementation is equally as fast as many hardware accelerated AES engines.

Creating ECC Certificates for SharkSSL-Lite

The following video shows how to create an Elliptic Curve Cryptography (ECC) certificate for a server, how to install the certificate in the server, and how to make the mbed clients connecting to the server trust this certificate. The server in this video is installed on a private/personal computer on a private network for test purposes. The video was produced for the embedded.com article How to run your own secure IoT cloud server.

inc/WsClientLib.h@1:d5e0e1dcf0d6, 2016-05-23 (annotated)

Committer:
wini
Date:
Mon May 23 13:56:30 2016 +0000
Revision:
1:d5e0e1dcf0d6
Parent:
0:e0adec41ad6b 
Type conflict fix (U8-U32) for latest mbed release.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
wini 0:e0adec41ad6b 1 /*
wini 0:e0adec41ad6b 2 * ____ _________ __ _
wini 0:e0adec41ad6b 3 * / __ \___ ____ _/ /_ __(_)___ ___ ___ / / ____ ____ _(_)____
wini 0:e0adec41ad6b 4 * / /_/ / _ \/ __ `/ / / / / / __ `__ \/ _ \/ / / __ \/ __ `/ / ___/
wini 0:e0adec41ad6b 5 * / _, _/ __/ /_/ / / / / / / / / / / / __/ /___/ /_/ / /_/ / / /__
wini 0:e0adec41ad6b 6 * /_/ |_|\___/\__,_/_/ /_/ /_/_/ /_/ /_/\___/_____/\____/\__, /_/\___/
wini 0:e0adec41ad6b 7 * /____/
wini 0:e0adec41ad6b 8 *
wini 0:e0adec41ad6b 9 * SharkSSL Embedded SSL/TLS Stack
wini 0:e0adec41ad6b 10 ****************************************************************************
wini 0:e0adec41ad6b 11 * PROGRAM MODULE
wini 0:e0adec41ad6b 12 *
wini 0:e0adec41ad6b 13 * $Id: WsClientLib.h 3616 2014-12-03 00:40:53Z wini $
wini 0:e0adec41ad6b 14 *
wini 0:e0adec41ad6b 15 * COPYRIGHT: Real Time Logic LLC, 2013
wini 0:e0adec41ad6b 16 *
wini 0:e0adec41ad6b 17 * This software is copyrighted by and is the sole property of Real
wini 0:e0adec41ad6b 18 * Time Logic LLC. All rights, title, ownership, or other interests in
wini 0:e0adec41ad6b 19 * the software remain the property of Real Time Logic LLC. This
wini 0:e0adec41ad6b 20 * software may only be used in accordance with the terms and
wini 0:e0adec41ad6b 21 * conditions stipulated in the corresponding license agreement under
wini 0:e0adec41ad6b 22 * which the software has been supplied. Any unauthorized use,
wini 0:e0adec41ad6b 23 * duplication, transmission, distribution, or disclosure of this
wini 0:e0adec41ad6b 24 * software is expressly forbidden.
wini 0:e0adec41ad6b 25 *
wini 0:e0adec41ad6b 26 * This Copyright notice may not be removed or modified without prior
wini 0:e0adec41ad6b 27 * written consent of Real Time Logic LLC.
wini 0:e0adec41ad6b 28 *
wini 0:e0adec41ad6b 29 * Real Time Logic LLC. reserves the right to modify this software
wini 0:e0adec41ad6b 30 * without notice.
wini 0:e0adec41ad6b 31 *
wini 0:e0adec41ad6b 32 * http://realtimelogic.com
wini 0:e0adec41ad6b 33 * http://sharkssl.com
wini 0:e0adec41ad6b 34 ****************************************************************************
wini 0:e0adec41ad6b 35 *
wini 0:e0adec41ad6b 36 */
wini 0:e0adec41ad6b 37
wini 0:e0adec41ad6b 38 #ifndef _WsClientLib_h
wini 0:e0adec41ad6b 39 #define _WsClientLib_h
wini 0:e0adec41ad6b 40
wini 0:e0adec41ad6b 41
wini 0:e0adec41ad6b 42 #include "selib.h"
wini 0:e0adec41ad6b 43
wini 0:e0adec41ad6b 44 /** @addtogroup WsClientLib
wini 0:e0adec41ad6b 45 @{
wini 0:e0adec41ad6b 46 */
wini 0:e0adec41ad6b 47
wini 0:e0adec41ad6b 48 /** @defgroup WebSocketOpcodes WebSocket Opcodes
wini 0:e0adec41ad6b 49 @ingroup WsClientLib
wini 0:e0adec41ad6b 50
wini 0:e0adec41ad6b 51 \brief WebSocket Opcodes
wini 0:e0adec41ad6b 52
wini 0:e0adec41ad6b 53 RFC6455 Page 29 - Opcode - 4 bits
wini 0:e0adec41ad6b 54
wini 0:e0adec41ad6b 55 WebSocket Opcodes with FIN=1. We do not manage WebSocket fragments
wini 0:e0adec41ad6b 56 (FIN=0/1) since it is rarely used and the complexity is not
wini 0:e0adec41ad6b 57 something you want in a tiny device.
wini 0:e0adec41ad6b 58 @{
wini 0:e0adec41ad6b 59 */
wini 0:e0adec41ad6b 60
wini 0:e0adec41ad6b 61 /** Text */
wini 0:e0adec41ad6b 62 #define WSOP_Text 0x81
wini 0:e0adec41ad6b 63 /** Binary */
wini 0:e0adec41ad6b 64 #define WSOP_Binary 0x82
wini 0:e0adec41ad6b 65 /** RFC6455 5.5 - Control Frame - Close */
wini 0:e0adec41ad6b 66 #define WSOP_Close 0x88
wini 0:e0adec41ad6b 67 /** RFC6455 5.5 - Control Frame - Ping */
wini 0:e0adec41ad6b 68 #define WSOP_Ping 0x89
wini 0:e0adec41ad6b 69 /** RFC6455 5.5 - Control Frame - Pong */
wini 0:e0adec41ad6b 70 #define WSOP_Pong 0x8A
wini 0:e0adec41ad6b 71
wini 0:e0adec41ad6b 72 /** @} */ /* end group WebSocketOpcodes */
wini 0:e0adec41ad6b 73
wini 0:e0adec41ad6b 74
wini 0:e0adec41ad6b 75
wini 0:e0adec41ad6b 76 /** The WebSocket protocol is frame based and the following struct keeps state
wini 0:e0adec41ad6b 77 information for #wscRead.
wini 0:e0adec41ad6b 78 */
wini 0:e0adec41ad6b 79 typedef struct
wini 0:e0adec41ad6b 80 {
wini 0:e0adec41ad6b 81 /** The WebSocket frame length */
wini 0:e0adec41ad6b 82 int frameLen;
wini 0:e0adec41ad6b 83 /** Read frame data until: frameLen - bytesRead = 0 */
wini 0:e0adec41ad6b 84 int bytesRead;
wini 0:e0adec41ad6b 85
wini 0:e0adec41ad6b 86 U8* overflowPtr; /* Set if: consumed more data from stream than frame len */
wini 0:e0adec41ad6b 87 int overflowLen; /* overflowPtr len is used internally in wsRawRead */
wini 0:e0adec41ad6b 88 int frameHeaderIx; /* Cursor used when reading frameHeader from socket */
wini 0:e0adec41ad6b 89 U8 frameHeader[4]; /*[0] FIN+opcode, [1] Payload len, [2-3] Ext payload len*/
wini 0:e0adec41ad6b 90
wini 0:e0adec41ad6b 91 /** Set when the read function returns due to a timeout. */
wini 0:e0adec41ad6b 92 U8 isTimeout;
wini 0:e0adec41ad6b 93 } WscReadState;
wini 0:e0adec41ad6b 94
wini 0:e0adec41ad6b 95
wini 0:e0adec41ad6b 96 #ifdef __cplusplus
wini 0:e0adec41ad6b 97 extern "C" {
wini 0:e0adec41ad6b 98 #endif
wini 0:e0adec41ad6b 99
wini 0:e0adec41ad6b 100
wini 0:e0adec41ad6b 101 /** Upgrades (morphs) an HTTPS request/response pair to a WebSocket
wini 0:e0adec41ad6b 102 connection. Sends the HTTP request header to the server and
wini 0:e0adec41ad6b 103 validates the server's HTTP response header -- the function
wini 0:e0adec41ad6b 104 simulates a very basic HTTP client library. The function is designed
wini 0:e0adec41ad6b 105 to be as simple as possible and the code is, for this reason, making
wini 0:e0adec41ad6b 106 a few assumptions that could fail when used with a non traditional
wini 0:e0adec41ad6b 107 HTTP server. Read the comments in the source code file WsClientLib.c
wini 0:e0adec41ad6b 108 if you should experience problems.
wini 0:e0adec41ad6b 109
wini 0:e0adec41ad6b 110 \param wss the WebSocket protocol state information is stored in this
wini 0:e0adec41ad6b 111 structure. All wss attributes must be initialized to zero before
wini 0:e0adec41ad6b 112 calling this function for the first time.
wini 0:e0adec41ad6b 113 \param s the SharkSslCon object
wini 0:e0adec41ad6b 114 \param sock the SOCKET object
wini 0:e0adec41ad6b 115 \param tmo in milliseconds. The timeout can be set to #INFINITE_TMO.
wini 0:e0adec41ad6b 116 \param host is the server's host name
wini 0:e0adec41ad6b 117 \param path is the path component of the wss URL and the path must
wini 0:e0adec41ad6b 118 be to the server's WebSocket service.
wini 0:e0adec41ad6b 119 \param origin some WebSocket server's may require an origin URL:
wini 0:e0adec41ad6b 120 http://tools.ietf.org/html/rfc6455#section-10.2. Set the parameter
wini 0:e0adec41ad6b 121 to NULL if it's not required by the server. The Origin header should
wini 0:e0adec41ad6b 122 only be required by a server when the request is sent from a
wini 0:e0adec41ad6b 123 browser.
wini 0:e0adec41ad6b 124 \return Zero success.
wini 0:e0adec41ad6b 125 */
wini 0:e0adec41ad6b 126 int wscProtocolHandshake(WscReadState* wss,SharkSslCon *s,SOCKET* sock,U32 tmo,
wini 0:e0adec41ad6b 127 const char* host,const char* path,const char* origin);
wini 0:e0adec41ad6b 128
wini 0:e0adec41ad6b 129
wini 0:e0adec41ad6b 130 /** Sends binary data to server.
wini 0:e0adec41ad6b 131
wini 0:e0adec41ad6b 132 The function sets the WS frame header's opcode to binary. The WS
wini 0:e0adec41ad6b 133 protocol supports two payload frame types, UTF8 and binary (RFC6455:
wini 0:e0adec41ad6b 134 5.6 Data Frames). We are assuming that you will be using the binary
wini 0:e0adec41ad6b 135 protocol for all data exchange.
wini 0:e0adec41ad6b 136 */
wini 0:e0adec41ad6b 137 int wscSendBin(SharkSslCon *s, SOCKET* sock, U8* buf, int len);
wini 0:e0adec41ad6b 138
wini 0:e0adec41ad6b 139 /** Sends a WebSocket control frame.
wini 0:e0adec41ad6b 140
wini 0:e0adec41ad6b 141 The code is used internally by the WebSocket functions. You can also use
wini 0:e0adec41ad6b 142 this function to send your own control frames such as #WSOP_Ping.
wini 0:e0adec41ad6b 143
wini 0:e0adec41ad6b 144 See RFC6455: 5.5. Control Frames
wini 0:e0adec41ad6b 145 */
wini 0:e0adec41ad6b 146 int wscSendCtrl(
wini 0:e0adec41ad6b 147 SharkSslCon *s,SOCKET* sock,U8 opCode, const U8* buf,int len);
wini 0:e0adec41ad6b 148
wini 0:e0adec41ad6b 149 /** Sends a WebSocket close control frame to the server and closes the
wini 0:e0adec41ad6b 150 connection.
wini 0:e0adec41ad6b 151
wini 0:e0adec41ad6b 152 \param s the SharkSslCon object.
wini 0:e0adec41ad6b 153 \param sock the SOCKET object.
wini 0:e0adec41ad6b 154
wini 0:e0adec41ad6b 155 \param statusCode is a <a target="_blank" href=
wini 0:e0adec41ad6b 156 "http://tools.ietf.org/html/rfc6455#section-7.4">
wini 0:e0adec41ad6b 157 WebSocket status code</a>.
wini 0:e0adec41ad6b 158 */
wini 0:e0adec41ad6b 159 int wscClose(SharkSslCon *s, SOCKET* sock, int statusCode);
wini 0:e0adec41ad6b 160
wini 0:e0adec41ad6b 161
wini 0:e0adec41ad6b 162 /** Wait for WebSocket frames sent by the server. The function
wini 0:e0adec41ad6b 163 returns when data is available or on timeout. The function returns
wini 0:e0adec41ad6b 164 zero on timeout, but the peer can send zero length frames so you must
wini 0:e0adec41ad6b 165 verify that it is a timeout by checking the status of
wini 0:e0adec41ad6b 166 WscReadState#isTimeout.
wini 0:e0adec41ad6b 167
wini 0:e0adec41ad6b 168 The WebSocket protocol is frame based, but the function can return
wini 0:e0adec41ad6b 169 a fragment before the complete WebSocket frame is received if the frame
wini 0:e0adec41ad6b 170 sent by the peer is larger than the SharkSSL receive buffer. The
wini 0:e0adec41ad6b 171 frame length is returned in WscReadState#frameLen and the data
wini 0:e0adec41ad6b 172 consumed thus far is returned in WscReadState#bytesRead. The
wini 0:e0adec41ad6b 173 complete frame is consumed when frameLen == bytesRead.
wini 0:e0adec41ad6b 174
wini 0:e0adec41ad6b 175 \param wss is the WebSocket read state.
wini 0:e0adec41ad6b 176
wini 0:e0adec41ad6b 177 \param s the SharkSslCon object.
wini 0:e0adec41ad6b 178 \param sock the SOCKET object.
wini 0:e0adec41ad6b 179
wini 0:e0adec41ad6b 180 \param buf is a pointer set to the SharkSSL receive buffer offset to
wini 0:e0adec41ad6b 181 the start of the WebSocket payload data.
wini 0:e0adec41ad6b 182
wini 0:e0adec41ad6b 183 \param timeout in milliseconds. The timeout can be set to #INFINITE_TMO.
wini 0:e0adec41ad6b 184
wini 0:e0adec41ad6b 185 \return The payload data length or zero for zero length frames and
wini 0:e0adec41ad6b 186 timeout. The function returns a negative value on error.
wini 0:e0adec41ad6b 187 */
wini 0:e0adec41ad6b 188 int wscRead(
wini 0:e0adec41ad6b 189 WscReadState* wss, SharkSslCon *s,SOCKET* sock, U8 **buf, U32 timeout);
wini 0:e0adec41ad6b 190
wini 0:e0adec41ad6b 191 #ifdef __cplusplus
wini 0:e0adec41ad6b 192 }
wini 0:e0adec41ad6b 193 #endif
wini 0:e0adec41ad6b 194
wini 0:e0adec41ad6b 195 /** @} */ /* end group WsClientLib */
wini 0:e0adec41ad6b 196
wini 0:e0adec41ad6b 197 #endif