Code Security & Lockable Teensy

Once a key is created, Teensyduino produces both standard HEX and encrypted EHEX files. When Teensy Loader communicates with a Teensy having the key in its internal fuse memory, the EHEX file is automatically used.

Standard Versus Lockable Teensy

TODO: photo of standard and lockable (with lock stamp mark) Teensy boards

Standard Teensy is meant to be "unbrickable". Fuse memory settings are configured so boot configuration and security settings can not be changed. This provides a safe platform for experimentation and prototyping, because you can not alter these critical settings in ways which would prevent Teensy from booting and running your code. Standard Teensy should be used for software development and experimenting.

Lockable Teensy allows you to set secure mode. Other boot settings can also be changed. Writing wrong fuse memory settings can make the hardware permanently unable to boot, or "bricked". Even with correct fuse settings, if you lock secure mode but lose your key.pem file, no further programming is possible. Lockable Teensy is only recommended when secure mode is needed to for code security.

Basic Usage with Arduino 1.8.19

You will need to generate key before the other buttons may be used. Only Arduino 1.8.19 with Tensyduino installed (scroll down to Arduino 1.8.x Software Development) is supported. Once your key is created and Lockable Teensy is locked, programming is supported on newer Arduino 2.3.x.

Usually only 1 key used for all boards. If you create multiple keys, you will need to rename or move files to select which key is used. Keeping track of which Teensy boards have which key can become a logistical challenge.

Do not use a virtual machine to generate your key. Key generation requires random numbers. Running on real hardware provides better access to entropy sources for random number generation.

Your key.pem file is stored in your "sketchbook" folder, which by default is {Documents}/Arduino. If you change the sketchbook location from File > Preferences, the Arduino IDE may need to be restarted before your key.pem file is used from the new location.

Fuse Write Sketch

Running this program writes your key and then turns on the Bus Encryption Engine to test whether decryption using your key really is works.

Verify Sketch

Parts of this program may be useful to copy into your own programs, if you wish to verify encryption really is used.

Lock Secure Mode Sketch

Stand Alone Use For Secure Upgrades, Even By Untrusted People

Teensy Loader never accesses your key.pem file.

Secure code upgrade can be performed by providing the EHEX file and Teensy Loader program. Even when used by untrusted people, no access to your original program data is possible.

Pin 25 Issue

void setup() {
  Serial.begin(9600);
  while (!Serial && millis() < 4000) ; // wait up to 4 sec for serial monitor

  uint32_t boot_config_unwritable = (HW_OCOTP_LOCK >> 2) amp; 3;
  if (boot_config_unwritable > 0) {
    Serial.println("Boot config is read-only, sorry\n");
  } else {
    Serial.printf("Disable pin 25 during boot\n");
    IMXRTfuseWrite(&HW_OCOTP_CFG6, 0x00000010);
  }
}

void loop() {
}

Teensy Loader Operational Details

When a HEX file is opened, either by File > Open or by remote control from Arduino, Teensy Loader automatically checks for the presence of a matching EHEX file. The EHEX file is considered a match if it has the same base filename and contains IVT+BootData fields indicating the same data size. Opening a HEX file means either HEX or EHEX is to be used.

However, when an EHEX file is opened by File > Open, no attempt to made to find a matching HEX file. Explicit opening of EHEX means only secure program loading is to be attempted.

When Teensy 4.0, Teensy 4.1 or MicroMod Teensy hardware is detected, Teensy Loader automatically checks whether it supports code security.

Teensy Loader reads the public key hash from the detected Teensy hardware and extracts the public key hash from your EHEX file. If the keys do not match, EHEX loading will not be attempted.

While detecting the hardware's code security capability, Teensy Loader also checks whether security has been locked. For locked hardware, only EHEX loading is possible. If EHEX data is not available, or the public key hashes mismatch, no loading is attempted. This feature prevents erasure of the previously written program in cases where a new program can not be successfully run.

When Teensy Loader detects hardware capable of using HEX or EHEX, where a key has been written to fuse memory but security is not yet locked, the EHEX data is automatically used if present and public key hashes match. Otherwise the HEX data is automatically used.

If you are unsure whether Teensy Loader used the HEX or EHEX file, the best way to check is with the Verify Sketch. Or you can copy some of its code into any other program to check whether the Bus Encryption Engine really is in use while running your code.

Minimum Erase Size

If flash memory between the end of program code and the beginning of EEPROM emulation is used for a LittleFS_Program filesystem or other non-volatile data, it is always erased during each upload when using bootloader version 1.05 or 1.06.

With bootloader version 1.07, only the first 512K in normal mode or first 1M in secure mode is unconditionally erased, if the flash memory contains a previously written program with valid IVT+BootData fields.

While uploading with bootloader version 1.07, flash memory beyond the minimum erase size is erased in 64K blocks on an as-needed basis, depending on the program size. For example, loading a 513K program in normal mode results in 576K flash erased.

Power Consumption

Performance Impact

Initial beta testing shows extreme cases can experience up to 5% overhead.

Key Management

Backups are essential. If you lose your key.pem file, you will have no way to create new EHEX files capable of being written to any Lockable Teensy in secure mode.

Encryption Details

AES-128-CTR uses a 128 bit key, 32 bit "counter", and 96 bit unique nonce number. The key is stored in fuse memory. The 96 bit nonce is stored in the EHEX startup shim. A new unique nonce number is created for each EHEX file by using 32 bit time_t (aka "unixtime") and 64 random bits. If 2 EHEX files are created within the same second, there is a tiny 1 in 2⁶³ chance of using the same random number. Nonce uniqueness is guaranteed when EHEX files are created at least 1 second apart.

Authentication is provided by High Assurance Boot (HAB) which uses a CMS format digital signature. HAB features are described in the IMXRT1060 Reference Manual (rev 2, 12/2019) on page 180.

The CMS signature stores a hash of the program code. This hash is computed over the entire program, including the Flash Boot Data, IVT+BootData, and all program code & data located before the unused 0x00 space meant to hold the signature. See EHEX Memory Layout below for details.

RSA-2048 is used for the CMS signature verification. The public key portion of the RSA-2048 key is included within the digital signature. HAB authentication using RSA verification and comparison of hash values is described in IMXRT1060 Reference Manual (rev 2, 12/2019) in Figure 7-2 on page 179.

Trust is established by storage of a hash of RSA-2048 public key in fuse memory, called "Root public key fingerprint" in the IMXRT1060 Reference Manual. During authentication, the public key which verifies the CMS signature is checked against the hash stored in fuse memory. The signature is trusted only if the public key hash matches.

CMS uses a X509 certificate. Public Key Infrastructure (PKI) and this X509 certificate are not used in any meaningful way to establish trust.

For simplicity in managing keys, Teensyduino stores the X509 certificate, RSA-2048 key, and AES-128 key into a single key.pem file. To streamline user experience, this 3-part key.pem file is usually described as a single key and the combination of BEE on-the-fly decryption and HAB authentication is usually described simply as using encryption.

Fuse Memory

While the exact design of the chip is known only to NXP, the fuse memory is very likely uses antifuse technology. Each fuse bit starts as logical 0. Writing to the fuse permanently changes the bit to logical 1. The writing process creates a physical and irreversible change inside the chip. Unlike Flash and EEPROM technology, the fuse bits can never be erased or restored back to zeros.

Fuse memory total size is only 256 bytes. Some of the design of code security, in particular storage of a hash of the public key rather than the entire public key, revolves around the very limited size of the fuse memory.

NXP documents the fuse hardware in chapter 23 in the IMXRT1060 Reference Manual, and the purpose of specific fuse bits in chapter 22. Unfortunately, the fuse bits related to code security are documented only as "Reserved" in the reference manual. A separate security reference manual, which NXP provides only with a non-disclosure agreement, documents the names and function of those fuses. PJRC developed Teensyduino's code security support using this material and in consultation with NXP. While this secrecy can be quite frustrating to anyone wishing to learn & understand every detail of how the chip works, the essential concept to understand is the keys described above in Encryption Details are stored within this permanent fuse memory and used automatically by the chip's BEE and HAB features.

Firmware Cloning Between Boards

Imagine 3 products, called "Good", "Better", "Best", where all have similar hardware but differ by software features. If all use the same key, an attacker can clone the "Best" code onto the least expensive hardware.

One solution is to use 3 different keys. But use of multiple keys can be logistically challenging.

Another solution involves storing the product identity within an unused portion of the fuse memory. The SW_GP1 (32 bits) and GP3 (128 bits) fuses are the recommended location to store this sort of data.

Cloning can also be used to downgrade firmware. Imagine a vulnerability is discovered in your firmware which allows users to perform an unauthorized action. Even after you have fixed the code, an attacker with access to hardware with the old firmware can clone the vulnerable code onto newer hardware (assuming you continue using the same key), causing the new hardware to perform the unauthorized action. Downgrades can be prevented with additional programming to read a minimum allowed version number or other info, which you would write into the fuse memory.

Teensyduino does not provide anti-cloning protection. Other tools which prevent cloning generally do so by utilizing the on-chip hardware to perform some of the encryption using a unique number within each chip. While this results in unique data on each board to thwart cloning, the trade-off is the programming process must be performed by trusted people, because sensitive data is encrypted at the time of writing to flash memory.

Teensyduino is designed so you can safely distribute the EHEX files with all sensitive data fully encrypted, which allows anyone to securely upgrade firmware on boards which have the correct key. But EHEX format and Teensy Loader do not result in unique flash data for each board. If firmware cloning is a concern, you must manage keys or fuse data to prevent cloning.

EHEX file format

Fortunately, the EHEX file uses the exact same format at Intel HEX, which is designed to be easy for human reading. Hopefully the following info can help you to view and understand EHEX files.

Intel HEX Format

Intel HEX is an old format, originally meant for computers with 16 bit address space. So each line of data has a 16 bit address, after the number of bytes, and "00" if the line is ordinary data. The last 2 characters are a simple checksum.

If "04" follows the address, the line is the upper 16 bits of a 32 bit address, which applies to all following lines until another "04" line changes the upper 16 bits. In this example, you can see the Flash Boot Data which begins at address 6000,0000.

Usually data lines have 16 or 32 bytes, though any number of data bytes is considered valid. The following screenshot shows the exact same 160 bytes of Flash Boot Data starting at address 6000,0000.

The size of the HEX or EHEX file on your hard drive does not represent the amount of actual data encoded. This second example uses only 5 data lines rather than 10. Because each line has 11 non-data characters and a newline character (or carriage return and newline if created on Windows), the 2nd example would appear to be 60 or 65 bytes smaller if comparing file sizes, even though both contain exactly the same actual data.

The important concept to reading HEX or EHEX files is recognizing the address fields and which characters from each line are the actual data. Replacing the non-address and non-data characters with spaces can help if your editor does not support syntax highlighting for Intel HEX format.

Memory Layout

This is the boundary between the 2 parts, you should see this. ":00000001FF" is the Intel HEX end of file marker.

The second portion of the HEX file is a loader utility which is temporarily placed in RAM. It is not written to flash. See the Loader Utility section below for details.

The actual memory layout within the HEX and EHEX files comes from Teensyduino's linker script. The locations where code exists, and areas of unused data where digital signatures and the startup shim are written in the EHEX file exist in the HEX file because of the design of Teensyduino's linker scripts.

Flash Boot Data

IVT+BootData

The entry point field in the EHEX file is changed to the startup shim address, so it will run first. Your program's entry point becomes part of the startup shim.

Startup Shim

Program Code

Digital Signature

Signature verification checks that the contents of flash match the signature, and that the public key for the signature matches a public key hash stored in fuse memory.

Loader Utility

Bus Encryption Engine on Standard Teensy

Standard Teensy 4.0 & 4.1 manufactured before June 2021, and all MicroMod Teensy can not use the key in fuse memory for code decryption. If you run the fuse write sketch, the encryption test will fail when the Bus Encryption Engine (BEE) is turned on.

Newer Standard Teensy 4.0 & 4.1 have configuration where the Bus Encryption Engine can decrypt code. But encryption alone without secure mode is not secure. JTAG remains enabled, and HAB authentication is not required. Use of encryption for code without secure mode is like locking your door but leaving a window wide open. Teensy Loader is not able to detect the capability of standard Teensy 4.0 or 4.1 boards, so it will not upload the EHEX file, even to the newer boards which are capable of running EHEX files. As a workaround, you can delete the HEX file and rename the EHEX file to HEX. But remember, running EHEX this way is not secure!

If you do program EHEX onto standard Teensy, you may wish to add code to check HAB authentication data at startup.

Only Lockable Teensy provides strong code security, and only when secure mode has been permanently locked. Uploading code from Arduino to Lockable Teensy still works as with Standard Teensy, as long as you have the correct key.pem.

Integration with Non-Arduino Development Tools

Usage: teensy_secure encrypthex <board> <file.hex> [key.pem]
       teensy_secure fuseino <key.pem>
       teensy_secure testdataino <key.pem>
       teensy_secure verifyino <key.pem>
       teensy_secure lockino <key.pem>
       teensy_secure keygen <key.pem>
       teensy_secure keycheck <key.pem>

    teensy_secure: Copyright 2021 PJRC.COM, LLC.  All rights reserved.

    This product includes software developed by the OpenSSL Project
    for use in the OpenSSL Toolkit (http://www.openssl.org/)
    Copyright (c) 1998-2019 The OpenSSL Project.  All rights reserved.

    This product includes cryptographic software written by Eric Young
    (eay@cryptsoft.com).  This product includes software written by Tim
    Hudson (tjh@cryptsoft.com).

    THIS SOFTWARE IS PROVIDED BY ERIC YOUNG ``AS IS'' AND ANY EXPRESS
    OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
    WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
    ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE
    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
    OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
    PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA,
    OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
    THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR
    TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
    OF SUCH DAMAGE.

The "encrypthex" option causes teensy_secure to encrypt a HEX file, writing the results to the same filename with EHEX extension. The "board" input is expected to be "teensy40" or "teensy41" or "teensy_micromod". If the key.pem filename is omitted, teensy_secure attempts to locate Arduino's sketchbook folder and read the file from that location. Use by most non-Arduino tools will likely give the full pathname to the user's key.pem file.

The "fuseino", "testdataino", "verifyino", and "lockino" generate the files for the programs to set up Teensy hardware with the key. Generated code is already printed to stdout.

The "keygen" option creates a new key.pem file, renaming any old file as needed to avoid overwriting any prior keys. The "keycheck" option reads the key file and performs basic syntax checks, and prints the public key hash to stdout.

The teensy_secure program uses the OpenSSL library, according to the OpenSSL License.

  OpenSSL License
  ---------------

/* ====================================================================
 * Copyright (c) 1998-2019 The OpenSSL Project.  All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions
 * are met:
 *
 * 1. Redistributions of source code must retain the above copyright
 *    notice, this list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright
 *    notice, this list of conditions and the following disclaimer in
 *    the documentation and/or other materials provided with the
 *    distribution.
 *
 * 3. All advertising materials mentioning features or use of this
 *    software must display the following acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
 *
 * 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
 *    endorse or promote products derived from this software without
 *    prior written permission. For written permission, please contact
 *    openssl-core@openssl.org.
 *
 * 5. Products derived from this software may not be called "OpenSSL"
 *    nor may "OpenSSL" appear in their names without prior written
 *    permission of the OpenSSL Project.
 *
 * 6. Redistributions of any form whatsoever must retain the following
 *    acknowledgment:
 *    "This product includes software developed by the OpenSSL Project
 *    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
 *
 * THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
 * EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
 * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
 * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 * OF THE POSSIBILITY OF SUCH DAMAGE.
 * ====================================================================
 *
 * This product includes cryptographic software written by Eric Young
 * (eay@cryptsoft.com).  This product includes software written by Tim
 * Hudson (tjh@cryptsoft.com).
 *
 */

Source code for the Teensy 4 Security tool in the Arduino IDE is available on github. It just runs "teensy_secure" to perform all operations.