Level up your Twilio API skills in TwilioQuest, an educational game for Mac, Windows, and Linux. Download Now

Menu

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?

What is Trust Onboard

If you received a Twilio Broadband IoT Developer Kit, then check out this tutorial to learn how to set it up and build your first IoT application.

Description

Trust Onboard is a feature where Programmable Wireless SIM cards contain two X.509 certificates. These client-side certificates can be used to authenticate SIM cards in HTTPS connections. You can also authenticate with cloud providers such as Microsoft Azure or against your homegrown systems using the TLS handshake.

No additional pre-shared keys (API tokens, passwords, request signing) are needed - only a Twilio SIM card with Trust Onboard. The SIM cards are manufactured with two unique certificates and key pairs with different capabilities, described below.

Check out the usage guide to learn how to use Trust Onboard for your IoT solution.

General use cases

Category Description
Device identity Device identity differentiation at the point of manufacturing, without the installation of custom software or hardware by the device manufacturer
Device protection Software integrity
Secure communication API authentication and authorization

How Trust Onboard starts

  1. Twilio generates a public key, private key, and two certificates (Available Key and Signing Key) per SIM card.
  2. Certificates are loaded on the SIM card during SIM manufacturing.
  3. Twilio provides you with an ICCID to certificate mapping and the ability to sync certificates to your backend.
  4. Using the Twilio Breakout SDK for Trust Onboard, you can use the certificates and keys on the SIM card to authenticate your device to your backend service and setup a TLS connection.

SIM certificates onboard

  • Available Key certificates will be on the SIM card but the text is freely available on the device. Your code will have access to the full text of the public and private keys and certificate. This is intended to be used with hardware that requires you to hand over this data for HTTPS communication. These live in a simple global platform applet that holds files with only read operations.
  • Signing Key certificates will be inside the SIM card with no way to export the text contents. You will utilize TLS libraries such as mBed that can request the SIM card to sign requests using the keys and perform request encryption. This is intended for use cases where your hardware allows you to offload the TLS communication to the SIM card. These live in a global platform applet called mIAS that implements a full security suite (similar to OpenSSL).

Twilio Breakout SDK for Trust Onboard

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.

Get the SDK from Github.

SIM certificates lifetime

The SIM certificates have long expiration periods (30 years).

  • Available Key certificates that are able to be extracted out of the SIM onto the device memory can never be replaced. The files (public, private key and certificate) live in a location on the SIM card that is not writable. For this reason the keys are effectively permanent and the certificate should outlive the physical device.
  • Signing Key has the same 30 year expiration period as Available Key.
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.