Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

Working with Trust Onboard

With Trust Onboard you will be able to use X.509 certificates that are on the SIM to authenticate your devices. In this guide, we will demonstrate how to use Trust Onboard features for your IoT solutions. Use this guide along with examples published to learn how to implement Trust Onboard.


Twilio IoT Trust Onboard Breakout SDK

The Twilio IoT Breakout SDK for Trust Onboard offers tools and examples on how to utilize the Available and Signing X.509 certificate available on Twilio IoT's Trust Onboard (ToB) enabled SIM cards. The SDK can be built as a static or dynamic library and linked to your executable. Trust Onboard SDK currently has only C bindings, which means you can use it with C and C++ applications, or in other languages using C FFI. The SDK can be built and installed with CMake. Follow the instructions published on the repository.

Get the SDK from Github.

On Raspbian you can also install the SDK from our debian repository:

echo "deb buster main" | sudo tee -a /etc/apt/sources.list
# Raspbian stretch is also supported
sudo apt-key adv --keyserver hkp:// --recv-keys 379CE192D401AB61
sudo apt update
sudo apt install trust-onboard-sdk

Syncing certificates to your backend

Trust Onboard makes SIM certificates available to you so you can add them to your backend service in order to authenticate connections from your devices. There are couple of ways you can get SIM certificates as shown below.

Download SIM certificates

If you have a home grown backend system, then you can download the SIM Certificates and add them to your backend system.

Sync SIM certificates to your Cloud

With Trust Onboard you can sync your SIM certificates directly with a cloud backend service like Microsoft Azure.


Working with Trust Onboard certificates on your IoT device

To begin using certificates on your IoT device, you need the Breakout SDK for Trust Onboard. If you haven't already done so, take a look at the Prerequisites section to download and set up the SDK on your IoT device.

Using the Available Key certificate and private key

Available Key certificates and the associated private key can be read out of the SIM card using the Breakout SDK. Your code will have access to the full text of the public and private keys and certificate in PEM form.


        Using the Signing Key certificate

        Signing Key certificate can be read out similar to the Available Key certificate, but the signing key itself will stay in the SIM card. You will utilize TLS libraries such as OpenSSL, mBed or wolfSSL that can request the SIM card to sign requests using the Signing keys.


              Using certificates with your TLS library

              Most frequently you will want to use Trust Onboard to establish a TLS connection. With low-level API you can implement the bindings for your own TLS library. We at Twilio have already implemented OpenSSL, mbedTLS and wolfSSL bindings for you to use.

              Please refer to the samples in Trust Onboard SDK for the detail of how to use these bindings. Below you can find short code excerpts demonstrating all the three use-cases. Error checking is omitted for brevity. On how to use OpenSSL, CURL, mbedTLS and WolfSSL, refer to the documentation of these specific libraries.


                    Using the Trust Onboard tool to read certificates

                    If all you want is to extract the TLS credentials and feed it to your application, you might not want to use the Trust Onboard library. For this use-case Trust Onboard SDK contains a command line tool called trust_onboard_tool.

                    After building and installing the SDK, it can be used as

                    trust_onboard_tool --device /dev/ttyACM0 --baudrate 115200 --pin 0000 --available-cert ~/available.cert.pem --available-key ~/available.key.pem

                    Refer to the tool's help for more options.

                    Twilio Certificate bundle Twilio certificate bundles below contain the CA certificates used to sign the certificates on a Twilio SIM card. Use this bundle to upload to your backend services as needed.

                    Generation Two Trust Onboard SIMs (August 2019 onwards)

                    Generation One Trust Onboard SIMs (Prior to August 2019) If your SIM has a label on it with the text "Certificates on this SIM are valid until December 2020".

                    Connecting to Azure IoT Hub

                    Connecting to Azure IoT Hub involves two steps:

                    1. Registering your device on Device Provisioning Service
                    2. Sending and receiving messages to the IoT Hub itself.

                    You can refer to the temperature measurement sample in the Trust Onboard SDK for a comprehensive example of both, below you can find the short excerpts.

                    Note: at the time of writing Trust Onboard requires you to use Twilio's fork of Azure IoT SDK. On Raspbian it can also be installed from Twilio's debian repo:

                    echo "deb buster main" | sudo tee -a /etc/apt/sources.list
                    sudo apt-key adv --keyserver hkp:// --recv-keys 379CE192D401AB61
                    sudo apt update
                    sudo apt install azure-iot-sdk-twilio-dev

                    DPS registration

                    Registering to DPS is basically establishing a TLS connection to a globally know end-point. Based on what certificate you use, DPS will return you the IoT Hub URL to connect to, and your registered device ID.

                    The output of the registration process is a connection string, that will be used to connect to the IoT Hub.

                    Note: your certificate should be pre-registered on the DPS. See the Broadband Kit documentation for detailed instructions.


                          Talking to Azure IoT Hub in C

                          The connection string retrieved during the DPS registration can then be used to talk to the IoT hub. Some set up still needs to be done though to use Trust Onboard for IoT Hub communication as well.

                          Note: refer to Azure IoT Hub documentation for how to send and receive messages. The sample will only show the set-up process.


                                Talking to Azure IoT Hub in Python

                                You can use Azure IoT SDK for Python, also installable via pip to do the registration, and send and receive messages to and from the IoT Hub. As Python SDK, and python ssl library in general do not support cryptographic hardware, only Available key can be used in Python. To extract the key from the SIM card one can shell-out to the trust_oboard_tool. See the Python sample for more details.

                                Rate this page:

                                Need some help?

                                We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.