Security breaches where private files and personal data are stolen has sadly become commonplace in today’s digital age. Even more terrifying are the security breaches where a hacker gains access to your home, peering through cameras, listening on microphones, and even unlocking your front door. These are some of the risks posed by the Internet of Things (IoT). Several government and technology agencies have proposed rules and guidelines that could be adopted by technology companies to combat the most common security and privacy vulnerabilities, but a more comprehensive strategy is required. Security is a complex and dynamic problem that can’t simply be solved by a dedicated one-time effort. The issue is rapidly increasing as new products and services are introduced. Small developers, focused on creating the next generation of innovative connected products, often don’t have the resources and expertise to properly secure them. This has led to a deluge of highly insecure devices flooding the market and consumers’ homes.
The Open Connectivity Foundation (OCF) has created an open international standard, complete with open source software and a world-class security infrastructure that directly addresses this issue. Industry-leading security has been built into the OCF design: from the specifications, the software, and the development tools, to labs around the world that certify products and manage a Public Key Infrastructure (PKI) system. Using these resources, a fully functional and interoperable IoT prototype that includes world-class security can be built in a matter of minutes. This paper will demonstrate how that is done.
One of the truisms of the modern technological age is: if something can be connected to the Internet it will be connected, if it is connected it can be compromised, and if it is compromised it will be turned into either a botnet drone or a crypto-miner.
When it comes to the IoT, there are two major issues that have held back widespread adoption: interoperability and security. OCF provides a solution for both of these by delivering on the core tenet of secure interoperability. This comes in the form of an international ISO/IEC standard, an open source reference implementation, and development tools that allow developers to get up and running quickly and easily. Using these tools developers can configure and build a device with a test PKI certificate from one of the official OCF certificate authorities in just a few minutes.
This article focuses on building a virtual OCF server device that can be securely joined and operated with any OCF client controller. For a list of OCF certified products please visit OCF’s Certified Products page and get a preview of upcoming products by reading this announcement from CES 2020. An overview of OCF’s security architecture can be found here.
So, get a cup of coffee, stretch out your fingers and let’s get going.
IoTivity-Lite is the official open-source implementation of the OCF specifications, it is implemented in C and will run on constrained devices with limited memory and fewer resources. Additionally, it can be run on Android using Java (SWIG).
While this article will focus on a build environment of Ubuntu Linux 18.04, several other platforms can be used, including other versions of Linux and Windows. Hardware examples using the Raspberry Pi with various Pi “Hat” daughter cards, as well as examples on Arduino-based platforms are supported and currently manufacturers are building OCF into many other platforms. For more information check out the links at the end of this article.
For the example in this article we will be building a very simple binary-switch server, this is a bare-bones OCF device that could control something like a light switch or smart outlet. Figure 1 shows the basic workflow for building a device. Most of this workflow is automated using the following scripts.
Figure 1: Workflow of building a device (Source: OCF)
First, start with a fresh install of Ubuntu 18.04, change to the top of your user directory tree and upgrade it to the most recent packages:
>sudo apt-get upgrade
Get the Code
Next, install the IoTivity-Lite developer environment by issuing this single command:
>curl https://openconnectivity.github.io/IOTivity-Lite-setup/install.sh | bash
This script does an apt-get update and then downloads all the required packages to build IoTivity-Lite. Further, it will download the source of IoTivity-Lite and some resources needed by the binary-switch device we are building. Once the script has completed, you will now have a new directory called ‘iot-lite’ under the top of your user directory tree. Below are the important scripts in that directory and their purpose. These should be run in order:
gen.sh: This script automatically generates the C-code that is used to build the device. In this example the script is pre-configured to build a simple binary (on/off) switch. It reads in a simple JSON file called example.json where all the resources for the devices we are building are stored. It is important to note that you can use gen.sh to automatically generate compliant code for your own custom IoT device just by changing the resources of an input file like example.json. Please see the resources at the bottom of this article for a directory of resources that can be used. This script also automatically downloads a test certificate and trust anchor from one of the OCF certificate authorities.
build.sh: This script compiles the generated code for Linux. To build the code for devices targeting other platforms you can uncomment relevant sections from within this script. (Note: Other platforms may require some additional steps to get the device code properly configured.) The output code for this Linux example will be in the ~/iot-lite/iotivity-lite/port/linux folder. The executable will be called device_builder_server.
reset.sh: This script resets the security state of the device to ready-for-onboarding-transfer-method (RFOTM). This is the state for a new device that is not yet owned by anyone.
run.sh: This script simply runs the new executable.
Generate Device Code
Now let’s see these tools in action. Each command will need to be entered with the “./” prefix. This will force it to look in the current directory for the command script.
A great deal of text will stream by at high speed as the code is generated. At times the scrolling will stop for a bit. Be patient. Depending on your platform, the code generation will take between ~30 seconds and a couple of minutes. Wait until the Linux command line prompt appears again.
Compile Device Code
Again, you will see a lot of debug output scroll by as the device is built. The first time you do this, it may take a few minutes. After the first time, about 99% of your code will already be built, so compiling any new changes will only take a few seconds.
This may not be necessary every time, but it will set the device to a known state (RFOTM) so the rest of this example will work as illustrated. In any case, it doesn’t hurt.
At this point, if everything worked you have successfully built a working OCF device. It should be running and waiting for a controlling application to onboard it. You should see output similar to this:
Figure 2: Command for running device. Shows installation of PKI certificate (Source: OCF)
You have built and run your first secure OCF device, but you are only half done. Now comes the fun part. Let’s build something to connect to it.
Onboarding Tool and Generic Client (OTGC)
OCF has created an open source tool Onboarding Tool and Generic Client (OTGC) to enable OCF devices to be securely onboarded and controlled via an automatically generated user interface. It is expected that manufacturers will take the code for OTGC and add their own branded and customized user interface elements. This should speed development without the concern of getting the security and operational features of a user interface to work from scratch.
OCF supports both Linux and Android versions of OTGC. Support for additional platforms is encouraged via open source contributions. All required features of an OCF client are supported in the core code. Additional platforms only need to add user interface elements.
For Android, there is a pre-built executable application that can be installed as described here:
As we are working from an Ubuntu platform, we will build the Linux version from scratch. While our existing terminal is busy running the server we already built, open another terminal to build and run OTGC. Again, this is all done with a single command.
>curl https://openconnectivity.github.io/otgc-linux/setup.sh | bash
Note: Make sure Java 8 is selected as default:
sudo update-alternatives –config java
On this system version 8 was the number “2” selection.
Figure 3: Command to select Java version. (Source: OCF)
Then run OTGC.
You may need to accept a license agreement before the GUI application appears.
The OTGC starts in discovery mode. Look at the bottom right of the window to see if an indicator is moving back and forth showing that OTGC is trying to discover eligible devices. If it is, just wait a bit. If it isn’t, click on the “Discover” button at the top left of the application.
The device that is running in the other window should show up in OTGC. Wait until the bar at the lower right stops moving. This indicates the discovery process is complete. The process may continue for a bit after your device is discovered because OTGC is looking for ALL the devices on your network, not just the one you built.
Figure 4: OTGC showing one discovered device (Source: OCF)
Next, select your discovered device by clicking on it. The bar to the left of the device should be blue. This indicates the device is unowned (RFOTM) and ready for you to securely onboard. Do this by clicking on the “onboard” button. A box will pop up prompting for the onboarding method. We want to demonstrate PKI onboarding, so select PKI from the drop-down menu. Then click OK.
Figure 5: OTGC showing selection of PKI On-Boarding (Source: OCF)
After a few moments (assuming the onboarding is successful), a box will appear asking you to name the device. It may have a default name already. You can enter any name you want. Then click OK. You should see your new name appear on the device in the left column. You should also see the bar to the left of the device turn green – this means you have successfully and securely onboarded the device with PKI.
If anyone else on the same network using another copy of OTGC were to discover the device, the bar would be orange, indicating that the device is already owned by someone else (you). They will not be able to do anything with that device unless you explicitly authorize them to do so (how to do this is not covered in this article).
Figure 6: OTGC showing onboarded and owned device (Source: OCF)
Let’s explore what you can do with it. Just click on the device and a user interface for a “binary switch” should appear on the right. You should also see a platform ID (a long unique string) that uniquely identifies the device and the manufacturer should be listed as “ocf.” A real manufacturer would typically fill out all those fields specific to its devices.
On the right side of the device GUI, you should see a switch labeled “value.” You can click this switch to change the value of the switch on the device you built a few minutes ago. Try it. You should see the value of the switch on your device terminal window change between “true” and “false” in tandem with the GUI switch.
You have now built a complete and highly secure IoT ecosystem without writing a single line of code. This is not just a canned example; it is exactly what you need to create a real device that can be deployed in the market with state-of-the-art security. Certainly, if you were a manufacturer, you would want to use one of your own certificates that chains up to one of the official OCF PKI production root certificates [Kyrio] or [Eonti], improve the aesthetics of OTGC and connect the server device code to your actual hardware. (See how to do this with the Raspberry Pi examples; the hardware connection only requires two or three lines of additional code.)
When you are done testing your device, you can “offboard” it. This is easily done by clicking on the device and clicking the “offboard” button. After a few moments, the device will be offboarded and returned to the RFOTM state. You can verify this as the bar to the left of the device has changed back to blue.
You can type ctrl-C in your device window to stop the device from running. You can then use “./edit_code.sh” to change the code for your binary switch device. You can also use “./edit_input.sh” to modify the resources used in your device. These scripts just call the textual nano editor. If you have a better editor installed, you don’t need to use the scripts.
Congratulations, you have completed this example of building a PKI secured IoT device and controlling that device with an open source secure client. You are encouraged to use the tools and examples available from OCF. There are several Raspberry Pi examples and a nice emulated graphical light bulb example that runs on Linux.
The most important lesson of this paper, though, is that it shows how fast and easy it is to create flexible and highly secure IoT devices.
Further Reading and Resources
OCF User Guide:
A list of device type and standardized resources can be found here:
The OTGC User Manual can be found here:
For troubleshooting, send an email to the Tools WG reflector: firstname.lastname@example.org
Join Open Connectivity Foundation
|Kyle Haefner is a senior security engineer at CableLabs and the Chair of the Open Connectivity Security Oversight Work Group. He is also a Ph.D. candidate at Colorado State University where his research focuses on IoT behavioral analysis.|
|Clarke Stevens is Principal Architect of emerging technologies at Shaw Communications. In this role, he analyzes emerging technologies and works with senior executives to develop product strategy. Prior to Shaw, Clarke spent over a decade at CableLabs analyzing and developing new technologies for the cable television industry. He is a public speaker on the Internet of Things (IoT) and an active technical contributor to the Open Connectivity Foundation (OCF), an international IoT standards organization.|