メニュー

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?

Adding Credentials

Sync for IoT is currently in Developer Preview, which means access is by invite only. If you'd like to try what you see in these docs, sign up for the developer preview and the team at Twilio will get you onboarded as soon as possible.

In the previous sections of IoT Device Manager guide, we went through details around use of fleets, enrolling and deploying devices. In order to finalize the device registration process, we want to make sure that authentication is secured.

There are two types of credentials that your devices may present to perform authentication.

  1. Certificate: either a self-signed TLS client certificate or signed by your own CA.
  2. Key: a randomly generated shared secret.

For more details about device authentication and establishing connectivity with Twilio for Deployed Devices gateways, refer to Connecting to MQTT Gateway document. For additional guidance on the security topics, consult the IoT Security Primer.

Registering a Certificate

Certificate based device authentication is the preferred mechanism in IoT Device Manager, as it results in a more secure credential.

  1. Log into Twilio developer Console and navigate to Deployed Devices > Fleets > Devices.
  2. Pick a device that you want to register a certificate for and click on it to get to Configure Device page.
  3. Click on Certificates in the context menu on the left.
  4. Click the Create a Certificate button (or + button if some certificates exist already).
  5. Optionally, specify a Friendly Name for your certificate. If you leave it blank, a randomly generated SID will be displayed instead in the certificate listing table, and it will be tricker to find later.
  6. Check Generate box to have the certificate helper tool generate a new certificate and its private key for you. Note: Twilio does not store your private key in any way, and it is returned as part of ephemeral website content. The key is made available only once after its creation, make sure you fetch it. Note: the generated certificate is self-signed, uses RSA signature, and is valid for one year. You can always provide your own certificate here (refer to the alternative flow below).
  7. Leave the Device SID unchanged, it points to your selected device already. In a different provisioning flow, you may want to create a decoupled certificate instead which is not used by any device yet (e.g. if devices are not yet manufactured).
  8. Click Create button, your new certificate is now registered, with some additional artifacts produced and displayed.
    • Certificate SID: regardless of whether the friendly name was set or not, the resulting SID is going to be unique way to address your device certificate.
    • Thumbprint: this is a fingeprint of your certificate (SHA256 hash) that is used to guarantee certificate uniqueness.
    • Certificate download: click to download the generated certificate in PEM format. The name of the file will match the certificate SID.
    • Private Key download: click to download the private key in PEM format to be used with above certificate, and provision to your device securely. Note the passphrase that is used to decrypt the private key.
    • Date created: contains current date/time, will never change after creation.
    • Date updated: contains date/time of the last certificate resource update, which is initially set to the creation time.

In a similar manner, you can later locate your certificate in the listing and update its attributes. You can also reassign the certificate to another valid device. Note that the certificate may represent only one device at a time, in order guarantee the consistent and secure identification of your devices.

Alternatively, instead of having Twilio generating a certificate for you automatically in step (6) above, you may prefer enrolling your own certificate that is generated offline. This is useful if you want to have extra security or control over the certificate issuance process, or your certificate facility has no access to public internet. This way, you can also specify custom expiration date or supply extra attributes in the certificate.

For IoT applications, we recommend to use the ECC cryptography instead of RSA to reduce key and certificate footprint and minimize resulting mTLS handshake traffic.
Generate your private key using OpenSSL command line utility like illustrated below:

$ openssl ecparam -genkey -name prime256v1 -out device-key.pem

Alternatively, if your device's TLS stack does not support ECC, feel free to use RSA as well

$ openssl genrsa -out device-key.pem 2048

In both cases, produce the final self-signed certificate valid for 365 days using OpenSSL "req" command:

$ openssl req -new -x509 -sha256 -days 365 -key device-key.pem -out device-cert.pem

Fill out country name, organization and other certificate metadata as you see fit: they are not interpreted by Twilio backend.

Make sure that device-key.pem is securely persited on your target device and avoid any other copies. The certificate file, device-cert.pem is public: copy & paste its content to IoT Device Manager Certificate Data field, leaving the Generate option unchecked.

Unregistering a Certificate

  1. Log into Twilio developer Console and navigate to the fleet that contains your certificates, e.g. Deployed Devices > Default Fleet > Certificates.
  2. Click on the certificate that you wish to unregister and click on Delete this Certificate link.

Note: certificate removal is an irreversible operation. The devices that were authenticated by a removed certificate may no longer use it. They will be eventually disconnected from Twilio gateways as the system will no longer accept old credentials.

Creating a Key

Shared key + secret based device authentication is an alternative mechanism in IoT Device Manager, resulting in a simpler credential that may be used for development purposes.

  1. Log into Twilio developer Console and navigate to Deployed Devices > Fleets > Devices.
  2. Pick a device that you want to register a key for and click on it to get to Configure Device page.
  3. Click on Keys in the context menu on the left.
  4. Click the Create a Key button (or + button if some keys exist already).
  5. Optionally, specify a Friendly Name for your key. If you leave it blank, a randomly generated SID will be displayed instead in the key listing table, and it will be tricker to find later.
  6. Leave the Device SID unchanged, it points to your selected device already. In a different provisioning flow, you may want to create a decoupled key instead which is not used by any device yet (e.g. if devices are not yet manufactured).
  7. Click Create button, your new key is now created, with some additional attributes generated and displayed.
    • Key SID: regardless of whether the friendly name was set or not, the resulting SID is going to be unique way to address your device key.
    • Secret: securely transfer the generated key secret to your target device. It is displayed only once in developer Console, and will become unavailable after key creation.
    • Date created: contains current date/time, will never change after creation.
    • Date updated: contains date/time of the last key resource update, which is initially set to the creation time.

In a similar manner, you can later locate your device key in the listing and update its attributes. You can also reassign the key to another valid device. Note that the key may represent only one device at a time, in order guarantee the consistent and secure identification of your devices.

Removing a Key

  1. Log into Twilio developer Console and navigate to the fleet that contains your device keys, e.g. Deployed Devices > Default Fleet > Keys.
  2. Click on the key that you wish to remove and click on Delete this Key link.

Note: key removal is an irreversible operation. The devices that were authenticated by a removed key may no longer use it. They will be eventually disconnected from Twilio gateways as the system will no longer accept old credentials.

REST API

Like everything in Twilio, all above functions may be invoked from your service backend programmatically, via REST APIs.

Rate this page:

ヘルプが必要ですか?

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.