Rate this page:

Working with Trust Onboard

On October 31, 2022, support for Programmable Wireless Trust Onboard will end. On this date, Programmable Wireless Trust Onboard certificates will no longer be available for sync or download in Console. Trust Onboard certificates that have already been synced to your backend services can continue to be used to authenticate devices until the device certificates expire in 30 years’ time. Trust Onboard SIMs will continue to work for connectivity as regular Programmable Wireless SIMs, which can connect to T-Mobile USA’s network in the United States and their global connectivity partners around the world.

With Trust Onboard you will be able to use X.509 certificates on the Programmable Wireless SIM to authenticate your devices. In this guide, we’ll show you how to use Trust Onboard features with your IoT products. Use this guide, along with examples published on GitHub, to learn how to implement Trust Onboard.


The Twilio IoT Breakout SDK for Trust Onboard

The Twilio IoT Breakout SDK for Trust Onboard includes tools and examples which will show you how to utilize the two X.509 certificates, Available and Signing, added to Trust Onboard enabled SIM cards. The SDK can be built as a static or dynamic library and linked to your executable. The SDK currently only offers C bindings, which means you can use it with C and C++ applications, or in other languages using the C FFI. The SDK can be built and installed with CMake. Please follow the instructions published in the repository.

Get the SDK from Github

On Raspberry Pi OS 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 the SIM certificates.

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

You can also sync your SIM certificates directly with a cloud backend service like Microsoft Azure using the Console:

  1. Select your SIM from the list at Internet of Things > Programmable Wireless > SIMs.
  2. In the Configure tab, scroll down to Trust Onboard.
  3. Select an option from the Sync to Cloud menu.
  4. Click the Sync button.

Working with Trust Onboard certificates on your IoT device

Using the Available Key certificate and private key

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


        Using the Signing Key certificate

        The Signing Key certificate can be read in the same way as the Available Key certificate, but the Signing Key itself will stay in the SIM. You utilize TLS libraries such as OpenSSL, mBed or wolfSSL that are able to ask the SIM card to sign requests using the Signing Keys.


              Using the certificates with your TLS library

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

              Please refer to the samples in Trust Onboard SDK for the details of how to use these bindings. The short code excerpts below demonstrate all three use cases. Error checking is omitted for brevity. Please refer to the OpenSSL, curl, mbedTLS, and WolfSSL documentation to learn how to use these libraries.


                    Using the Trust Onboard tool to read certificates

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

                    After building and installing the SDK, trust_onboard_tool can be used as follows:

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

                    Please refer to the tool’s help screen for more options.

                    Twilio certificate bundles

                    The certificate bundles below contain the CA certificates used to sign the certificates on Twilio SIM cards. Upload this bundle to your backend services as needed. You should use the first bundles unless your SIM has “Certificates on this SIM are valid until December 2020” written on its label.

                    Generation Two Trust Onboard SIMs (August 2019 onwards)

                    Generation One Trust Onboard SIMs (Prior to August 2019)

                    Connecting to Azure IoT Hub

                    Connecting to Azure IoT Hub involves two steps:

                    1. Registering your device with the Azure Device Provisioning Service (DPS).
                    2. Sending messages to and receiving messages from the IoT Hub itself.

                    You can refer to the temperature measurement sample in the Trust Onboard SDK for a comprehensive example showing both of these steps; below you can find short code excerpts which show the steps in a more brief way.

                    At the time of writing, Trust Onboard requires you to use Twilio’s fork of Azure IoT SDK. On Raspberry Pi OS 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

                    1. DPS registration

                    Registering a device with the DPS involves establishing a TLS connection to an Azure URL, Depending on which certificate you use, DPS will return to you your device’s ID and the IoT Hub URL it should connect to to register itself.

                    The output of the actual registration process is a “connection string” that will be used to provision the device.

                    Functions to perform these tasks are shown in the next code sample.

                    Your certificate should be pre-registered with the DPS. The Trust Onboard Getting Started Guide has information to help you do this.


                          2a. Talking to Azure IoT Hub in C

                          The connection string retrieved during the DPS registration can now be used to talk to the IoT Hub, as shown in the next code sample. Some further setup will still need to be done to use Trust Onboard for IoT Hub communication.

                          Refer to Azure IoT Hub documentation to learn how to send and receive messages. The sample will only show the setup process.


                                2b. Talking to Azure IoT Hub in Python

                                You can use the Azure IoT SDK for Python, installable via pip, to perform the device registration, and to send and receive messages to and from the IoT Hub. As the Python SDK and Python SSL library do not support cryptographic hardware, only the Available Key can be used with Python. To extract the key from the SIM card, use trust_oboard_tool. Please see the Python sample on GitHub 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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                Thank you for your feedback!

                                Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                Sending your feedback...
                                🎉 Thank you for your feedback!
                                Something went wrong. Please try again.

                                Thanks for your feedback!

                                Refer us and get $10 in 3 simple steps!

                                Step 1

                                Get link

                                Get a free personal referral link here

                                Step 2

                                Give $10

                                Your user signs up and upgrade using link

                                Step 3

                                Get $10

                                1,250 free SMSes
                                OR 1,000 free voice mins
                                OR 12,000 chats
                                OR more