Use an example to establish a working TLS connection or verify a firmware signature before adapting the code to your product. Client examples initiate connections; server examples accept them. The ECDSA verification example runs without a network connection.
Choose a first example
| Goal | Example |
|---|---|
| Inspect a server certificate and trust result | CertCheck.c |
| Connect a device to an MQTT broker with a client certificate | AWS-MQTT.c |
| Exchange messages over WebSocket | WsEchoClient.c |
| Compare full and resumed connections | SessionCache.c |
| Accept HTTPS and WebSocket connections on a device | Minnow Server examples below |
| Verify a firmware signature made with OpenSSL | ECDSA-Verify |
Before running a network example, check its configured endpoint, port, trust store, and any required account credentials. Online endpoints and cloud setup steps can change. Treat supplied certificates and private keys as demonstration credentials and provision your own identities for a product.
A client must check both certificate trust and the expected server name before exchanging sensitive data. Review the application's handling of seSec_handshake results; completion alone does not mean that its trust policy accepted the server.
Initialize the random number generator
Examples that initialize the random number generator (RNG) use a function address as a demonstration seed, for example:
This passes a U32 value derived from the function address; it does not register or call an entropy callback. The pattern avoids a desktop-specific entropy API in the example, but a function address is predictable and provides no cryptographic entropy. Repeating this call does not make the seed secure.
Before using the code in a product, replace the demonstration seed with proper seeding from the platform's hardware entropy source or operating-system cryptographic RNG. Follow the selected RNG's initialization and reseeding requirements, and handle failures before TLS, key generation, signing, or WebSocket client masking. In a PSA consumer build, sharkssl_entropy initializes the provider and ignores the supplied value; configure entropy in that provider. See the RNG declarations in SharkSslCrypto.h for the API contracts.
SharkSSL client examples
A TLS client authenticates the server against its configured trust store and expected domain name. SharkSslCon_trusted checks the name against the certificate; its date checks depend on SHARKSSL_CHECK_DATE. Preserve the example's trust-result handling when changing the server or certificate configuration.
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. 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 checks that the certificate identifies the name entered in the browser's address bar, normally through a DNS Subject Alternative Name (SAN). Check the certificate supplied with your package. The documented test 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
Use a digital signature to check that firmware matches an image signed with your trusted signing key before accepting an update. The signing computer holds the private key; the device verifies the signature with the matching public key. The following examples use RayCrypto, the cryptographic engine in SharkSSL. See also the Securing Edge Nodes Whitepaper.
Start with Verify firmware signatures with SharkSSL in examples/ECDSA-Verify. It includes a small C verifier, matching OpenSSL test data, a Windows build script, and instructions for signing your own firmware. The demo checks both a valid signature and a deliberately changed digest.
For signing and verification within SharkSSL, see examples/RayCrypto-ECDSA.c. The integration sketches below show where hashing and verification belong in a firmware workflow. Their disk, network and flash functions are application placeholders, not SharkSSL APIs; read errors and installation policy must be handled by the application.
Both APIs take a binary digest and a hash identifier as the final argument. For SHA-256, use SHARKSSL_HASHID_SHA256. SHARKSSL_SHA256_HASH_LEN is the 32-byte digest size and is only used to size the digest buffer. The signature uses binary DER encoding, and verification needs its actual byte length.
Signature verification is one part of secure boot or a firmware updater. Keep the verification public key in trusted device storage and apply your version/rollback and safe-installation policies before activating an image.
Signing Binaries
Sign firmware on a host computer as part of the release process. The following sketch embeds a demonstration private key converted with SharkSslParseKey. A signing application can instead load PEM text from a file and convert it with sharkssl_PEM_to_ECCKey; release the converted key with SharkSslECCKey_free when finished. A production signer must protect its own private key and initialize SharkSSL's cryptographic random number generator with suitable entropy before signing. Keep the private key off the device that only verifies updates.
Verifying Binaries
On the device, hash the original firmware bytes and verify the received signature against that digest. The embedded public key below matches the demonstration signing key above. Stage incoming data in an inactive area; activate it only after verification and the application's other update checks succeed. A read or signature-extraction error must abort the update.
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.