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/selib.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: selib.h 3854 2016-03-08 17:40:24Z 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 _selib_h
wini 0:e0adec41ad6b 39 #define _selib_h
wini 0:e0adec41ad6b 40
wini 0:e0adec41ad6b 41 #include <SharkSSL.h>
wini 0:e0adec41ad6b 42 #include <SharkSslEx.h>
wini 0:e0adec41ad6b 43
wini 0:e0adec41ad6b 44
wini 0:e0adec41ad6b 45 /** @addtogroup SharkExamples
wini 0:e0adec41ad6b 46
wini 0:e0adec41ad6b 47 @{
wini 0:e0adec41ad6b 48 */
wini 0:e0adec41ad6b 49
wini 0:e0adec41ad6b 50
wini 0:e0adec41ad6b 51 /** @defgroup selib SharkSSL Socket Example Lib
wini 0:e0adec41ad6b 52 @ingroup SharkExamples
wini 0:e0adec41ad6b 53
wini 0:e0adec41ad6b 54 The SharkSSL Socket Example Lib (selib.h/selib.c) is a basic module
wini 0:e0adec41ad6b 55 that wraps the transport agnostic SharkSSL functions for encoding and
wini 0:e0adec41ad6b 56 decoding into functions that interface to TCP/IP socket calls.
wini 0:e0adec41ad6b 57
wini 0:e0adec41ad6b 58 ![Socket Example Lib](@ref SharkSSL-selib.jpg)
wini 0:e0adec41ad6b 59
wini 0:e0adec41ad6b 60 In addition, the file selib.c includes wrappers for standard BSD
wini 0:e0adec41ad6b 61 socket calls at the end of the file. TCP/IP stacks not using the BSD
wini 0:e0adec41ad6b 62 API must define NO_BSD_SOCK and implement the following functions in a
wini 0:e0adec41ad6b 63 separate file: #se_bind, #se_accept, #se_connect, #se_close,
wini 0:e0adec41ad6b 64 #se_sockValid, #se_send, and #se_recv.
wini 0:e0adec41ad6b 65
wini 0:e0adec41ad6b 66 @{
wini 0:e0adec41ad6b 67 */
wini 0:e0adec41ad6b 68
wini 0:e0adec41ad6b 69 /** Use INFINITE_TMO for standard blocking call. */
wini 0:e0adec41ad6b 70 #define INFINITE_TMO (~((U32)0))
wini 0:e0adec41ad6b 71
wini 0:e0adec41ad6b 72 #include <selibplat.h>
wini 0:e0adec41ad6b 73
wini 0:e0adec41ad6b 74 #ifndef XPRINTF
wini 0:e0adec41ad6b 75 #if HOST_PLATFORM
wini 0:e0adec41ad6b 76 #define XPRINTF 1
wini 0:e0adec41ad6b 77 #else
wini 0:e0adec41ad6b 78 #define XPRINTF 0
wini 0:e0adec41ad6b 79 #endif
wini 0:e0adec41ad6b 80 #endif
wini 0:e0adec41ad6b 81
wini 0:e0adec41ad6b 82 #include <string.h>
wini 0:e0adec41ad6b 83 #if XPRINTF
wini 0:e0adec41ad6b 84 #include <stdarg.h>
wini 0:e0adec41ad6b 85 #endif
wini 0:e0adec41ad6b 86
wini 0:e0adec41ad6b 87 #ifndef SE_CTX
wini 0:e0adec41ad6b 88 #define SeCtx void
wini 0:e0adec41ad6b 89 #endif
wini 0:e0adec41ad6b 90
wini 0:e0adec41ad6b 91 /** Infinite wait time option for socket read functions.
wini 0:e0adec41ad6b 92 */
wini 0:e0adec41ad6b 93 #ifndef NO_BSD_SOCK
wini 0:e0adec41ad6b 94 /** The SOCKET object/handle is an 'int' when using a BSD compatible
wini 0:e0adec41ad6b 95 TCP/IP stack. Non BSD compatible TCP IP stacks must set the macro
wini 0:e0adec41ad6b 96 NO_BSD_SOCK and define the SOCKET object. See the header file
wini 0:e0adec41ad6b 97 selib.h for details.
wini 0:e0adec41ad6b 98 */
wini 0:e0adec41ad6b 99 #define SOCKET int
wini 0:e0adec41ad6b 100 #endif
wini 0:e0adec41ad6b 101
wini 0:e0adec41ad6b 102 #ifndef SOCKET_constructor
wini 0:e0adec41ad6b 103 #define SOCKET_constructor(o, ctx) (void)ctx,memset(o,0,sizeof(SOCKET))
wini 0:e0adec41ad6b 104 #endif
wini 0:e0adec41ad6b 105
wini 0:e0adec41ad6b 106
wini 0:e0adec41ad6b 107 #ifdef __cplusplus
wini 0:e0adec41ad6b 108 extern "C" {
wini 0:e0adec41ad6b 109 #endif
wini 0:e0adec41ad6b 110
wini 0:e0adec41ad6b 111 /**
wini 0:e0adec41ad6b 112 Performs the initial SSL handshaking using an asymmetric cipher in
wini 0:e0adec41ad6b 113 order to establish cipher settings and a shared key for the session.
wini 0:e0adec41ad6b 114
wini 0:e0adec41ad6b 115 The function also validates the server's certificate and compares
wini 0:e0adec41ad6b 116 the commonName provided in argument 3 with the common name in the
wini 0:e0adec41ad6b 117 certificate, if commonName is provided (not NULL). The domain name
wini 0:e0adec41ad6b 118 comparison works with and without the clone certificate API
wini 0:e0adec41ad6b 119 (#SHARKSSL_ENABLE_CLONE_CERTINFO).
wini 0:e0adec41ad6b 120
wini 0:e0adec41ad6b 121 <b>Note:</b> the function only performs basic certificate domain
wini 0:e0adec41ad6b 122 name comparison and can only be used with server certificates that
wini 0:e0adec41ad6b 123 does not include Subject Alternative Names (SAN Certificate). Use
wini 0:e0adec41ad6b 124 the more advanced function #SharkSslCon_trusted for certificate
wini 0:e0adec41ad6b 125 trust management if the server uses a SAN Certificate.
wini 0:e0adec41ad6b 126
wini 0:e0adec41ad6b 127 \param s the SharkSslCon object.
wini 0:e0adec41ad6b 128 \param sock the SOCKET object.
wini 0:e0adec41ad6b 129 \param timeout in milliseconds. The timeout can be set to #INFINITE_TMO.
wini 0:e0adec41ad6b 130 \param commonName is optional and is used for certificate domain
wini 0:e0adec41ad6b 131 name verification.
wini 0:e0adec41ad6b 132
wini 0:e0adec41ad6b 133 \return
wini 0:e0adec41ad6b 134
wini 0:e0adec41ad6b 135 - A negative value on error. The negative value is an inverted
wini 0:e0adec41ad6b 136 #SharkSslCon_RetVal value.
wini 0:e0adec41ad6b 137 - Zero on timeout.
wini 0:e0adec41ad6b 138 - The return value is #SharkSslConTrust for any return value
wini 0:e0adec41ad6b 139 greater than zero.
wini 0:e0adec41ad6b 140 */
wini 0:e0adec41ad6b 141 int seSec_handshake(
wini 0:e0adec41ad6b 142 SharkSslCon *s, SOCKET* sock, U32 timeout, const char* commonName);
wini 0:e0adec41ad6b 143
wini 0:e0adec41ad6b 144 /** Read data from socket stream and decode the encrypted data. The
wini 0:e0adec41ad6b 145 buffer is managed by SharkSSL and the data returned is valid until
wini 0:e0adec41ad6b 146 the next SharkSSL call. This function blocks until data is
wini 0:e0adec41ad6b 147 available or until 'timeout' milliseconds.
wini 0:e0adec41ad6b 148
wini 0:e0adec41ad6b 149 \param s the SharkSslCon object.
wini 0:e0adec41ad6b 150 \param sock the SOCKET object.
wini 0:e0adec41ad6b 151 \param buf is a pointer set to the SharkSSL receive buffer offset to
wini 0:e0adec41ad6b 152 the WebSocket payload data.
wini 0:e0adec41ad6b 153 \param timeout in milliseconds. The timeout can be set to #INFINITE_TMO.
wini 0:e0adec41ad6b 154 \return The function returns the number of bytes available in
wini 0:e0adec41ad6b 155 'buf' on success. The function returns 0 on timeout and a negative
wini 0:e0adec41ad6b 156 value on error.
wini 0:e0adec41ad6b 157 */
wini 0:e0adec41ad6b 158
wini 0:e0adec41ad6b 159 int seSec_read(SharkSslCon *s,SOCKET* sock,U8 **buf,U32 timeout);
wini 0:e0adec41ad6b 160
wini 0:e0adec41ad6b 161 /** Encrypts and sends encrypted data to the connected peer side.
wini 0:e0adec41ad6b 162 \return Zero on success or a negative value on error.
wini 0:e0adec41ad6b 163 */
wini 0:e0adec41ad6b 164 int seSec_write(SharkSslCon *s, SOCKET* sock, U8* buf, int maxLen);
wini 0:e0adec41ad6b 165
wini 0:e0adec41ad6b 166 /** Initializes a SOCKET object connected to a remote host/address at
wini 0:e0adec41ad6b 167 * a given port.
wini 0:e0adec41ad6b 168 \return Zero on success.
wini 0:e0adec41ad6b 169 Error codes returned:
wini 0:e0adec41ad6b 170 \li \c -1 Cannot create socket: Fatal
wini 0:e0adec41ad6b 171 \li \c -2 Cannot resolve 'address'
wini 0:e0adec41ad6b 172 \li \c -3 Cannot connect
wini 0:e0adec41ad6b 173 */
wini 0:e0adec41ad6b 174 int se_connect(SOCKET* sock, const char* address, U16 port);
wini 0:e0adec41ad6b 175
wini 0:e0adec41ad6b 176 /** Initializes a SOCKET object bound to a local port, ready to accept
wini 0:e0adec41ad6b 177 client connections.
wini 0:e0adec41ad6b 178 \return Zero on success.
wini 0:e0adec41ad6b 179 Error codes returned:
wini 0:e0adec41ad6b 180 \li \c -1 Cannot create socket: Fatal
wini 0:e0adec41ad6b 181 \li \c -2 Cannot listen: Fatal
wini 0:e0adec41ad6b 182 \li \c -3 Cannot bind: socket in use
wini 0:e0adec41ad6b 183 */
wini 0:e0adec41ad6b 184 int se_bind(SOCKET* sock, U16 port);
wini 0:e0adec41ad6b 185
wini 0:e0adec41ad6b 186 /** Waits for remote connections on the server SOCKET object
wini 0:e0adec41ad6b 187 'listenSock', initialized by function se_bind, and initializes
wini 0:e0adec41ad6b 188 socket object 'outSock' to represent the new connection.
wini 0:e0adec41ad6b 189
wini 0:e0adec41ad6b 190 \return
wini 0:e0adec41ad6b 191 \li \c 1 Success
wini 0:e0adec41ad6b 192 \li \c 0 timeout
wini 0:e0adec41ad6b 193 \li \c -1 error
wini 0:e0adec41ad6b 194 */
wini 0:e0adec41ad6b 195 int se_accept(SOCKET** listenSock, U32 timeout, SOCKET** outSock);
wini 0:e0adec41ad6b 196
wini 0:e0adec41ad6b 197 /** Close a connected socket connection.
wini 0:e0adec41ad6b 198 */
wini 0:e0adec41ad6b 199 void se_close(SOCKET* sock);
wini 0:e0adec41ad6b 200
wini 0:e0adec41ad6b 201 /** Returns TRUE if socket is valid (connected).
wini 0:e0adec41ad6b 202 */
wini 0:e0adec41ad6b 203 int se_sockValid(SOCKET* sock);
wini 0:e0adec41ad6b 204
wini 0:e0adec41ad6b 205 /** Sends data to the connected peer.
wini 0:e0adec41ad6b 206 */
wini 0:e0adec41ad6b 207 S32 se_send(SOCKET* sock, const void* buf, U32 len);
wini 0:e0adec41ad6b 208
wini 0:e0adec41ad6b 209 /** Waits for data sent by peer.
wini 0:e0adec41ad6b 210
wini 0:e0adec41ad6b 211 \param sock the SOCKET object.
wini 0:e0adec41ad6b 212 \param buf is the data to send.
wini 0:e0adec41ad6b 213 \param len is the 'buf' length.
wini 0:e0adec41ad6b 214 \param timeout in milliseconds. The timeout can be set to #INFINITE_TMO.
wini 0:e0adec41ad6b 215 \returns the length of the data read, zero on timeout, or a
wini 0:e0adec41ad6b 216 negative value on error.
wini 0:e0adec41ad6b 217 */
wini 0:e0adec41ad6b 218 S32 se_recv(SOCKET* sock, void* buf, U32 len, U32 timeout);
wini 0:e0adec41ad6b 219
wini 0:e0adec41ad6b 220
wini 0:e0adec41ad6b 221 /* Macro function designed for IPv4
wini 0:e0adec41ad6b 222 sock: a pointer to SOCKET
wini 0:e0adec41ad6b 223 buf: a buf large enough to hold 4 bytes
wini 0:e0adec41ad6b 224 status: int pointer: out value is negative on error and 4 (len) on success
wini 0:e0adec41ad6b 225 */
wini 0:e0adec41ad6b 226 #ifndef se_getSockName
wini 0:e0adec41ad6b 227 #define se_getSockName(sock, buf, status) do { \
wini 0:e0adec41ad6b 228 struct sockaddr_in in; int size=sizeof(struct sockaddr_in); \
wini 0:e0adec41ad6b 229 *(status) = getsockname(*(sock), (struct sockaddr *)&in, &size); \
wini 0:e0adec41ad6b 230 memcpy((buf), &in.sin_addr.s_addr, 4); \
wini 0:e0adec41ad6b 231 if(*(status) == 0) *(status) = 4; \
wini 0:e0adec41ad6b 232 } while(0)
wini 0:e0adec41ad6b 233 #endif
wini 0:e0adec41ad6b 234
wini 0:e0adec41ad6b 235 #if XPRINTF == 1
wini 0:e0adec41ad6b 236 /** The macro xprintf expands to function _xprintf if the code is
wini 0:e0adec41ad6b 237 compiled with XPRINTF set to 1.
wini 0:e0adec41ad6b 238 \param data is standard printf arguments enclosed in parenthesis;
wini 0:e0adec41ad6b 239 thus you must use double parenthesis when using macro xprintf.
wini 0:e0adec41ad6b 240 */
wini 0:e0adec41ad6b 241 #define xprintf(data) _xprintf data
wini 0:e0adec41ad6b 242 /** The example code and macro xprintf requires this function when the
wini 0:e0adec41ad6b 243 code is compiled with macro XPRINTF set to 1.
wini 0:e0adec41ad6b 244 \param fmt the format string.
wini 0:e0adec41ad6b 245 \param ... variable arguments.
wini 0:e0adec41ad6b 246 */
wini 0:e0adec41ad6b 247 #ifndef _xprintf /* to handle #define _xprintf printf */
wini 0:e0adec41ad6b 248 void _xprintf(const char* fmt, ...);
wini 0:e0adec41ad6b 249 #endif
wini 0:e0adec41ad6b 250 #else
wini 0:e0adec41ad6b 251 #ifndef xprintf
wini 0:e0adec41ad6b 252 #define xprintf(data)
wini 0:e0adec41ad6b 253 #endif
wini 0:e0adec41ad6b 254 #endif
wini 0:e0adec41ad6b 255
wini 0:e0adec41ad6b 256 /** Main entry for all example programs */
wini 0:e0adec41ad6b 257 void mainTask(SeCtx* ctx);
wini 0:e0adec41ad6b 258
wini 0:e0adec41ad6b 259 #ifdef __cplusplus
wini 0:e0adec41ad6b 260 }
wini 0:e0adec41ad6b 261 #endif
wini 0:e0adec41ad6b 262
wini 0:e0adec41ad6b 263
wini 0:e0adec41ad6b 264 /** @} */ /* end group selib */
wini 0:e0adec41ad6b 265 /** @} */ /* end group Examples */
wini 0:e0adec41ad6b 266
wini 0:e0adec41ad6b 267 #endif