Custom Teensy and Lockable code

jensa

Well-known member
Hi all,
I'm making a custom board and want to protect the firmware. The process is explained well for boards made by PJRC, but in my case I'm buying the core parts from PJRC and putting them on my own boards. I asked PJRC the following:

So just so I'm sure that I understand this correctly - any MKL02 (from PJRC) can enable this on any iMXRT1060 (from anywhere)? It's the Teensy 4 Security Tool that enables this using firmware in the MKL02 chip?

Paul then replied:

1: Only specific iMXRT1060 chips are supported, as documented on the web page. For example, "1064" parts definitely do not work. Parts with an extra "X" in the part number also will not work. Only specific flash memory chips are supported. Pay attention to "M" vs "Q" in the part number!

2: Yes, a MKL02 chip from PJRC pairs with a brand new IMXRT1062 chip as sold by NXP through distributors. Once paired, that MKL02 only works with that specific IMXRT1062.

3: Custom boards begin the same as Lockable Teensy. Details are thoroughly documented on the code security page. If you haven't already, I would highly recommend you buy at least one Lockable Teensy so you can experience the process of locking before you design a custom PCB. Try using it with Arduino IDE on another PC that doesn't have your key.pem file. Also try copying only the .hex or .ehex file and open it with Teensy Loader on another PC. This stuff is all documented, but there's really no substitute for experiencing it first hand.


Posting his reply here as Paul suggested, so others can find the answer via search. My core takeaway is that for any Teensy from PJRC, these fuses are pre-programmed. On a custom board and a blank MIMXRT1062DVJ6B, you are free to set the fuses as you like. When you set them to be locked (Tools > Teensy 4 Security), they're permanent.
 
Yes, the IMXRT fuse memory absolutely is permanent. Setting a fuse bit physically alters the chip in an irreversible way. NXP doesn't give details of how it's implemented, but the on-chip technology is likely amorphous silicon anti-fuse.

The MKL02 chip will pair with your IMXRT1062 on first use. Part of that process involves setting some of the fuses as needed by all Teensy boards.

When Teensy 4.0 was released in late 2019 and Teensy 4.1 in early 2020, those fuses were set only by PJRC's bed-of-nails test fixture. We couldn't sell the bootloader chips at that time, because they depended upon the test fixture to configure the fuses and do other stuff. The MKL02 bootloader chips became available in 2021 when the pairing process was added. It allows a pre-programmed MKL02 to initialize the IMXRT1062 chip without needing the PJRC test fixture.

When you run the 3 setup programs for code security, step #1 sets fuses with your encryption key. After step #1, your board can run both encrypted .ehex and also regular plaintext .hex. In this mode you code is NOT secure even if encrypted. All 3 steps run checks, but step #2 is purely a verification which doesn't set any fuses. Step #3 sets the fuses needed to permanently set secure mode. Once in secure mode, your board will only run encrypted .ehex files created with your key.pem file.

PJRC signed a non-disclosure agreement with NXP, so I can't talk about some aspects of the fuses and secure mode which NXP considers confidential.

But I will again mention the most important thing in practice: make backup copies of your key.pem file. If you lose your key, there is no recovery method. You need your key.pem file to create new .ehex files which work on all the boards you initialized with those 3 steps.
 
It still unclear to me what is different about the lockable Teensy 4s. Is it that you have configured them differently when they are made? Im making a custom Teensy 4 and need it to be lockable.
 
different about the lockable Teensy 4s.
Basically the Unlocked ship with some fuses NOT preconfigured as required for a commercial product that would allow the end user to make changes that could render the device unusable for no good reason. As noted in p#2 - once set these fuses cannot be altered.

When you buy an Unlocked version those fuses needed to allow the encryption based locking are not set so that the locking feature can be activated, by a purchaser that requested that feature and knows what to do with it.
 
Defragster's explanation is correct. If you really want to dive into the details, you'll need the IMXRT1062 reference manual. It's linked from the Teensy 4.1 product page under "Technical Information" (scroll down near the end of that very long page).

First turn to page 1317 and look at Figure 23-2 "OTP Memory Footprint" for a visual representation of the fuse memory. This small memory starts with the bits as zeros. Writing to the fuses permanently changes 0 bits to 1 bits. Once a fuse has been changed to 1, it can never be returned to the original 0 state. It is truly permanent 1-time programmable memory.

The "LOCK" part is 32 fuses which controls whether the other portions of the fuse memory (represented with different colors in Figure 23-2) are writable. When specific bits in the LOCK fuses are written to 1, other sections of the fuse memory become forever fixed. The hardware simply does not allow writing to fuse regions of the associated bit within the LOCK fuses has been written to 1.

The critically important fuses are BOOT_CFG. You can find some details in the big fuse table on page 1302-1306, but sadly some info is "reserved" and only available from NXP under non-disclosure agreement. PJRC has signed that NDA, so much as I might like to say more, I really can't discuss details of anything marked "reserved".

But I can tell you the main difference between standard Teensy and lockable Teensy is whether those BOOT_CFG fuses are writable. With standard Teensy, the bit within the LOCK fuses that forever prohibits changes to BOOT_CFG is set. Your program can never alter those critical BOOT_CFG fuses. Standard Teensy will always boot as intended (though you can of course create programs which don't work) because you simply can not mess up the BOOT_CFG fuses.

On lockable Teensy, and on a DIY PCB where those LOCK fuses are in their original condition as NXP ships, you can indeed write to the BOOT_CFG. You should only do so with the published programs. If you write to the wrong fuses within BOOT_CFG, you could permanently configure your IMXRT1062 chip to attempt to boot in a way that does not work for your hardware. Of course, you can also have things go badly if you use those programs as intended, and then lose your key.pem file. Your key is needed to create new .ehex files. So even if you never write to BOOT_CFG incorrectly, if you lose your key.pem you will forever be unable to create new firmware which runs on all the lockable Teensy and DIY PCBs you've locked into secure mode with your (lost) key.pem. This is why the Teensy 4 Security dialog box and all the code secuity documentation and every message I write about lockable Teensy has strong advise to make backup copies of your key.pem file!

Standard Teensy is meant to be safe for experimenting and prototyping. That's why it ships with the BOOT_CFG permanently read-only. You simply can not alter its critically important boot configuration fuses. Teensy has a special restore process (that only works on unlocked boards), triggered by holding the pushbutton for 15 seconds, which fully wipes the flash memory and writes a known-good LED blink program. Together with the forever fixed BOOT_CFG, as long as the hardware is undamanged, you can always recover Standard Teensy to a known-good workgin condition from any wrong program or configuration by using that restore process.
 
How would I produce a Standard Teensy on a DIY PCB?

I understand that the fuses for BOOT_CFG are permanently set to read-only in Standard Teensy. Is this the only difference in the initial setup/production of the DIY PCB?

I am guessing that the Standard Teensy for sale has been pre-configured by PJRC after manufacture (or during manufacture) but before delivery to the customer. In contrast, the Lockable has not been pre-configured. I.e., once the MKL_02 and IMXRT are paired and the initial blink sketch is transferred, the Lockable Teensy is ready to ship, leaving the fused OTP prepared for a key and configuration to secure mode.

You mention that you should only program the fuses with published programs. Are you referring to the sketches produced by PJRC to enable secure mode or some other program for programming chips?

Are there published sketches that will configure the fused OTP in a way that results in a Standard Teensy? Or is it just advised to prevent OTP manipulation by activating secure mode?
 
PJRC T_4.x products as sold Standard or Lockable are ready to run and tested. For general use a Lockable is no different than the other - except those fuses are still open to adjustment.

The PJRC bootloader chips as noted do a one time pairing with a factory compatible NXP 1062, and the bootloader as bought knows what to do with regard to the fuses set for Standard usage or configure specific to leaving it Lockable when first properly powered up.

When Locking is an option, it is an NXP NDA controlled process that PJRC has managed to present with the Arduino provided specific sketches. Only those prepared sketches know and understand the process for creating the key.pem file and presenting it in sketch #1, then to prepare the #2 sketch to load and test is buildable to see that the key is prepared while still unlocked, then sketch #3 to commit the locking that only allows .eHex properly encoded to execute on that processor. {going by memory on the three steps}

<edit> sketch that will take a Lockable 1062 safely into Standard configuration ... see p#9, though it seems PJRC could develop that to Lock out the ability to alter the fuses in a way that would make it Locked to a key.pem file when that is not desired.

I can say that during beta testing before the sketches #1,2,3 were perfected it took a simple PJRC change to prevent the user from bricking a Teensy, so these sketches are very exacting and specific in what they do with "NDA Reserved - undocumented" areas. They expose only what is needed and with no user adjustable parts and run as a normally built Arduino sketch.
 
Last edited:
How would I produce a Standard Teensy on a DIY PCB?

Are there published sketches that will configure the fused OTP in a way that results in a Standard Teensy? Or is it just advised to prevent OTP manipulation by activating secure mode?

If you look at the <webpage> where the MKL02 bootloader controller for the T4 is available for purchase, search for the section titled "Disabling Boot Configuration Changes". There you will find a snippet of code (see below) for locking out any changes to the boot & security settings. Based on the statement that appears there with the code ("If this program is run before secure mode is set, it will forever prevent locking secure mode. Changes to other fuses which might affect boot are also prohibited."), it should hold true that executing this code on a lockable T4 before doing any of the steps that activate & configure the code locking mechanism (as discussed in earlier posts) should result in a normal (non-lockable) T4.


Code:
void setup() {
  /* Prevent changes to boot & security configuration */
  IMXRTfuseWrite(&HW_OCOTP_LOCK, 0x00400004);
}

void loop() {
}

Hope that helps . . .

Mark J Culross
KD5RXT
 
Back
Top