Many practical example programs are included in the SharkSSL source code release. All our examples emphasize establishing a secure connection with the peer side and implementing solutions for tiny devices (microcontrollers).
These example programs are categorized into two sections: client examples and server examples.
SharkSSL client examples
A typical scenario is for a client to authenticate the server by making sure the server's certificate is signed by a trusted source. All of the included client examples both validate the server's certificate and make sure the common name in the certificate matches the "server name" (domain name).
Client Examples
- E-Mail (SMTP) Example: SMTP/SMTP-example.c - Send emails securely by using the included secure SMTP library.
- LED SMQ: LED-SMQ.c - IoT example that uses the secure SMQ library SharkMQ for connecting to our SMQ cluster. The example lets you control LEDs in a device in realtime via a browser. See the Browser to Device LED Control using SMQ tutorial for details. See also the SharkMQ API documentation.
- LED JSON: LED-JSON.c - IoT example that shows how to send and receive JSON IoT messages over a raw socket connection. See the JSON documentation for more information on using JSON for IoT communication. The example requires that you have installed our free JSON library in the root path.
- SharkMQTT Chat Example: Chat-MQTT.c - implements a basic chat client by using the MQTT protocol and the SharkMQTT library. The example, by default, connects to an online MQTT broker we have setup. We usually have a machine chat client also connected to the online MQTT broker, and you may chat with this machine or start a second instance of the MQTT client. Our chat machine is a basic implementation of ELIZA the therapist.
- AWS MQTT - shows how to connect to Amazon's AWS MQTT cloud. You must have an Amazon AWS account in order to use this example. Navigate to your AWS IoT console and register a new device (Register a thing). Take note of the AWS MQTT broker name, open AWS-MQTT.c in an editor, navigate to the line where you find #define AWS_IOT_MQTT_HOST "", and paste the broker name into the name string. Follow the instructions for creating a certificate for the device. On the "Certificate created" page, chose Download for the certificate, private key, and the root CA for AWS IoT. Name these files aws-certificate.pem, aws-private.pem.key, and aws-iot-rootCA.crt. Copy these three files to the directory where you have the example executable. Run the example. You may alternatively embed the certificate, key, and root CA in the executable. To embed the three files, run the two following command line programs as follows: SharkSslParseCert and SharkSSLParseCAList are command line tools included with SharkSSL. Compile the example with the macro EMBED_CERTIFICATES. This macro makes the example include the two generated C header files aws-certificate.h and aws-iot-rootCA.h.SharkSslParseCert aws-certificate.pem aws-private.pem.key > aws-certificate.hSharkSSLParseCAList aws-iot-rootCA.crt > aws-iot-rootCA.h
- WebSocket Echo Client: WsEchoClient.c - connects either to our online ELIZA the therapist WebSocket server (default) or to an online public WebSocket echo server. A #define in the example C code changes what server the client connects to. For the public echo WebSocket server mode, all data entered at the command line is sent to the server which in turn sends or (echoes) the data back to the client.
- SSL Certificate Check: CertCheck.c - a client example that shows how to validate several certificates returned by SSL enabled servers.
- SSL Session Cache Test: SessionCache.c - connects to various servers twice and measures the time difference between non-cached and cached sessions. The first connection is not cached. The second connection uses the SSL session key from the first connection if the server supports this feature.
SharkSSL server examples
The following examples are designed for the Minnow Server. Refer to the online tutorial Creating Single-Page Apps with the Minnow Server for how to best design WebSocket server compatible applications.
- WebSocket Chat Server: a basic chat example that echoes characters entered in the server's console window to the browser window and vice versa.
- WebSocket LED Server: a Single Page Application (SPA) designed for controlling LEDs in a device. This example functions similar to the LED-SMQ example except for that you connect directly to the device from your browser instead of controlling the device via an online SMQ broker (proxy server).
- Minnow Server Reference Platform: a more complete WebSocket example that follows the design guidelines in the tutorial Creating Single-Page Apps with the Minnow Server. The example may be downloaded from GitHub and used with the SharkSSL enabled Minnow Server included in the SharkSSL package.
- SharkTrust: an example that shows how to automate certificate management by using SharkTrust. The example shows how to auto update and maintain a valid certificate for the Minnow Server.
Important information
All server examples include a certificate signed by Real Time Logic's root (CA) certificate. You will receive a browser warning if you do not install Real Time Logic's CA certificate in your browser/certificate store. An explanation on how to install a CA certificate is available online. We recommend reading our certificate management tutorial if you are new to certificates. The server examples only respond to HTTPS connections. You must make sure you enter your https://address:port in the browser when connecting to the server examples.
You may still get a browser SSL warning when connecting to the example server after installing the CA certificate in your browser if the examples are not used correctly. Not only does the browser validate that the certificate is from a trusted source; it also makes sure the certificate's "common name" matches the name entered in the browser's address bar. The common name for the WebSocket Chat Server is "localhost", and the common name for the WebSocket LED Server is "device". The WebSocket Chat Server must, for this reason, run on the same computer as the browser such that you connect to "localhost". The WebSocket LED Server requires an entry in your computer's hosts file so you can enter "device" as the name in the browser's address bar.
SharkSSL example libraries
SharkSSL includes a number of example libraries. These libraries include functionality such as WebSockets and SMTP. These libraries are fully functional, but are delivered as examples since they are not part of the SharkSSL core functionality.
SharkSSL Example Libraries
- A secure socket library: integrates the transport agnostic SharkSSL API with sockets (TCP/IP). All network examples and example libraries require this library.
- E-Mail (SMTP client library).
- WebSocket client library.
- MinnowServer (WebSocket server library).
- SharkMQ (Secure SimpleMQ library).
- SharkMQTT (Secure MQTT library).
See the following SharkSSL product pages: SMTP library, WebSocket client library, and Minnow Server for an introduction to these products.
The following figure shows the relationship between the core SharkSSL library (red), the example libraries (blue), and the provided example programs (green).
SharkSSL example program features
Demonstration Attributes
The (example) libraries above include special features, which may easily go unnoticed without reading the references contained in this section.
- Single Active User: The WebSocket Chat Server and WebSocket LED Server examples are limited to one active user. You may modify these examples such that they will accept more than one active user.
- Forced Browser Closure: The WebSocket Chat Server example and WebSocket LED Server example require that you close the current browser window before connecting a new window.
- Multiple Connected Users: The SMQ-LED and LED-JSON examples are designed to manage multiple connected users. A user is an active browser session that is controlling a device. The two examples include resource management on the server side to handle multiple users. You should try to connect at least two browser windows to one device, and watch both browser windows as you toggle an LED button in the (simulated) device or as you click on an LED in one of the browser Windows.
- Browser Multiple Connection Conflict: The WebSocket Chat Server and WebSocket LED Server examples include dual HTTPS server/WebSocket server functionality. The web page and resource files are initially loaded using HTTPS via the Minnow Server library. JavaScript code in the browser is activated when all resources are loaded, and this JavaScript code initiates a persistent WebSocket connection with the server. The Minnow Server includes both a basic HTTPS server and WebSocket server. The basic HTTPS server is constructed to be as small as possible and can only handle one connection at a time. This creates a conflict with modern browsers that attempt to open multiple HTTPS connections when connecting to an HTTPS server. The connections will remain pending on the server side and most browsers will automatically time out and cause an initial delay before the WebSocket connection is established. The Minnow Server includes information on how this initial delay can be eliminated.
Tinkering with the examples
Client Side Modifications
The Certificate Management for IoT tutorial shows how to create your own Certificate Authority (CA) and how to sign certificates for the SharkSSL client examples by using the CA (root) certificate.
You can modify the client examples and connect to your own server. The server side code that manages the connections from all client examples can be downloaded and executed on your own computer. The Certificate Management for IoT tutorial shows you how to modify the client examples and how to install and operate your own server.
<em>Server Side Modifications</em>
Let's say you want to change the certificate in the WebSocket LED Server (WsLedServer.c) to your own certificate signed by your own Certificate Authority (CA). The below step-by-step instructions will use the Certificate management tool to illustrate the process for creating a complete new chain of trust:
Steps
- Download and install our Certificate Management Tool.
- Use the tool to create the CA certificate. We suggest that you initially create an RSA CA certificate.
- Install the CA certificate in your browser's certificate store. You can use the instructions we provide for our certificates, but remember to install your own CA certificate and not ours.
- Use the Certificate Management tool to create a certificate for the WebSocket LED Server. When you create your own certificates, you can use an IP address as the certificate's "common name"; thus you can use the IP address of the computer where the server will be running. You may also consider creating a Subject Alternative Name (SAN) certificate and use your computer's IP address and a name such as "device" as the alternative names. In this way, you can access the server securely without getting browser warnings by: (1) using the IP address, (2) using the name "device". For example, you can enter one of the following in your browser: https://192.168.1.100 or https://device.
- Add the certificate to the WebSocket LED server example.
- Compile and run the code.
- Navigate to the server by entering https://ip-address in the browser. You should not get any certificate warnings.
In step 5, we convert an X.509 certificate and key to the optimized SharkSSL format. This provides the appropriate APIs that allow you to load a standard X.509 certificate (or) the optimized SharkSSL certificate format. The LED server demo is using the optimized format, but you may change the example and use the SharkSSL APIs to allow a direct load of an X.509 certificate. The SharkSSL source code can be compiled without the X.509 processing code, thus saving memory in constrained devices. See certificate Management with sharkSSL for a detailed explanation.
Signing and Verifying Binaries
The following two examples, which are accompanied by our Securing Edge Nodes Whitepaper, show how to use RayCrypto for signing and verifying binaries such as firmware. The examples can be used as a base for creating secure boot.
Signing Binaries
The signature is typically performed on a host computer, such as Windows or Linux, as part of releasing new firmware. The following example shows how this can be done by creating a C program that runs on say Windows. The private key can be loaded dynamically from the file system, or the key can be embedded directly in the C program by converting the key from PEM format to the SharkSSL format by using the command line tool SharkSslParseKey. In the following example, the private key is embedded in the C program.
Verifying Binaries
The following example shows how to perform the verification process in a device. Note that the public key is embedded in the C program and follows the same construction as the signing example above.
Interfacing LED Demo Programs to Hardware
The SMQ LED demo and the Minnow Server LED demo require that you interface the example code to your development board.
The following code is extracted from the mbed platform example. The code example shows how the required interface functions are connected to the LEDS on an mbed board with four LEDS.