Skip to main content
Per-file encryption (PFE) allows AI model files to be encrypted individually before delivery, so that they remain encrypted at rest on the device until an application explicitly decrypts them. This guide walks you through the steps to
  • encrypt and publish an AI model file using Thistle Release Helper (TRH), and
  • fetch the encrypted AI model file and decrypt it on-device using Thistle Update Client (TUC)

​
Tools needed

  • Version 1.8.0 (or above) of TUC and TRH for your platform
  • On the Thistle Control Center App. Visit the settings section of a project to obtain the API token (“Project Access Token”) to be used as THISTLE_TOKEN in the configuration step below. Project's Access Token In “Settings > General > Project Configuration”, make sure the “Encrypted OTA” feature is on. Encrypted OTA Configuration

​
TRH configuration and initialization

Configure your Thistle project’s access token for TRH 
$ export THISTLE_TOKEN=$(cat)
(paste access token, press enter, then ctrl-d)
$ ./trh --signing-method="remote" init
Here, we first initialize the local working environment by executing the trh init command. This creates a Cloud-KMS-backed key pair on the Thistle backend; if a key pair already exists on the backend, the public key portion is returned. The private key in the key pair is used to sign the OTA update bundle and encrypt AI model files. An OTA update manifest file template manifest.json is also created locally in the current directory.
Your local working environment is now ready.

​
Prepare and release an encrypted AI model file

Package an OTA update bundle containing a dummy AI model file, model.pt, which will be installed in encrypted form at path /tmp/ota/pfe-install/model.pt.thistlepfe on a device. 
$ mkdir -p ota_release
# Create a dummy AI model file for demonstration
$ echo "This is a dummy PyTorch AI model file" > ota_release/model.pt
# Note the --encrypt-ai-model flag
$ trh --signing-method="remote" prepare \
    --target="ota_release" \
    --file-base-path="/tmp/ota/pfe-install/" \
    --encrypt-ai-model
When the --encrypt-ai-model flag is present, trh prepare iterates over all files under the target release directory and encrypts each file to produce a per-file encrypted (PFE) artifact with the .thistlepfe extension. In our case, ota_release/model.pt is encrypted as ota_release/model.pt.thistlepfe, which will be delivered and stored on-device at /tmp/ota/pfe-install/model.pt.thistlepfe.

​
Publish the encrypted AI model file for OTA update

Release the prepared OTA update bundle including the encrypted AI model file to Thistle backend. 
trh --signing-method="remote" release

​
Get encrypted AI model file with TUC

Create a TUC configuration file tuc-config.json for a device. 
$ trh --signing-method="remote" gen-device-config \
    --device-name="encrypted-ai-model-demo-device" \
    --enrollment-type="pre-enroll" \
    --persist="/tmp/ota" \
    --config-path="./tuc-config.json"
Put the generated tuc-config.json on a device where tuc is run to receive the encrypted AI model. In this guide, we will run tuc on the same machine where trh is run. 
$ tuc --log-level info -c tuc-config.json &
When the OTA update finishes successfully, you should see the encrypted AI model file at path /tmp/ota/pfe-install/model.pt.thistlepfe. The file remains encrypted at rest until explicitly decrypted.

​
Decrypt AI model on device

To decrypt the AI model file for use, an application calls tuc with the decrypt-file subcommand, supplying the encrypted file path and the desired output path. 
$ mkdir -p /tmp/decrypted
$ tuc -c tuc-config.json decrypt-file \
    /tmp/ota/pfe-install/model.pt.thistlepfe \
    /tmp/decrypted/model.pt
.. Device id: 1fe727a68b07e852a60a366d422e43be
!! Thistle client starting up - version 1.8.0
.. success
The application can then load the decrypted model from /tmp/decrypted/model.pt.

​
Combining with other flags

The --encrypt-ai-model flag can be combined with other trh prepare flags:
  • Encrypted OTA (--encrypt-ota --zip-target): Encrypts the entire OTA bundle in transit and in the cloud, while also per-file encrypting each AI model at rest on the device.
  • AI model signing (--sign-ai-model): When both --encrypt-ai-model and --sign-ai-model are present, the signature is generated for the encrypted AI model file (the .thistlepfe artifact).
For example, to combine all three: 
$ trh --signing-method="remote" prepare \
    --target="ota_release" \
    --file-base-path="/tmp/ota/pfe-install/" \
    --encrypt-ai-model \
    --sign-ai-model \
    --encrypt-ota --zip-target

​
More options

In this get started guide, we explained the usage of the Thistle Update Client alongside the Thistle Release Helper to deliver per-file encrypted AI models - and many more use cases are supported!