Enabling Read Protection or Write Protection for EM35x Chips
01/05/2018 | 07:57 PM
When preparing EM35x devices for field deployments, it is often desirable to secure the flash contents of the EM35x chip to prevent accidental/unauthorized access or modification. This can be done using the chip’s memory protection (Read Protection and Write Protection) mechanism, described in the EM35x Datasheet in Sections 5.2.1 (Flash Memory) and 5.3 (Memory Protection Unit).
Below are some of the common questions that customers ask when considering this kind of protection for their devices:
Q: What kinds of protection are available and what is protected by them?
A: The chip offers Read Protection and Write Protection.
Read Protection, when enabled, disconnects all flash from everything else when the chip’s SerialWire/JTAG interface (SWJ) is connected to something. This effectively prevents reading of all flash memory on the device, including the full 128KB or 192KB of main flash block (which covers the bootloader area, application code & data areas, and SimEEPROM token area), plus the FIB (flash information block where Ember-programmed manufacturing tokens and low-level flash read/write routines are stored) and the CIB (customer information block where customer-programmable manufacturing tokens are stored). This also prevents the use of the SWJ bus for SerialWire and JTAG operations such as debugger access and flash programming. Since read protection can only be disabled by writing a specific, non-zero, non-0xFF value to a specific location, the act of erasing of the CIB memory page (where the read protection option byte is contained), whether intentional or accidental, will still leave the chip read-protected until the appropriate option byte is set to the appropriate value.
Write Protection, when enabled, prevents writing or erasing of the main flash block [MFB], either by external means or through execution of code from flash or RAM. Unlike read protection, write protection is enabled on a per-region basis with each region being 4 pages of flash or 8KB.
Q: What kind of protection does Ember recommend using for deployed devices into mass production?
A: For devices that are deployed into the field in scenarios where no further debug or advanced testing is required, Ember recommends enabling Read Protection (which is chip-wide) as well as Write Protection of the first 8KB region, which is the section of the MFB where the bootloader firmware resides.
Q: How do I enable these recommended protection settings using the ISA3 and ISA3 Utilities?
A: Enabling these settings requires the use of the ISA3 Utilities from the command line; InSight Desktop does not currently provide an interface for passing these options to the loader through its GUI.
Enabling Write Protection
To enable write protection of the first region of main flash (where the bootloader resides), clear (write 0) only Bit 0 of the first option byte for write protection (Option Byte 4) and leave all other bits set (erased state of 1) for a final bitmask of 0xFFFFFE (0xFFFFFFFE for any chips with 512 KB of flash). This can be accomplished with the “—programwrprot” option in em3xx_load or em3xx_buildimage such as:
em3xx_load.exe --programwrprot FFFFFE
Note that current Ember implementations are such that write protection of this first region is currently done automatically whenever read protection is enabled. However, setting the write protection mask explicitly to include this first flash region is recommended to ensure consistent results should this automatic behavior change in future tool/silicon revisions.
Enabling Read Protection
NOTE: Enabling read protection should always be the last operation you perform on the device with em3xx_load or em3xx_buildimage since setting this option effectively inhibits any future changes to the chip/image state until read protection is disabled (which, in turn, causes the MFB and CIB to be erased).
To enable read protection, Option Byte 0 of the CIB can be set to 0×00 (though any value other than the special value of 0xA5 will suffice). This can be done using the “—enablerdprot” flag in em3xx_load or em3xx_buildimage, such as:
em3xx_buildimage.exe --em357 --chipimage myimage.hex serial-uart-bootloader.s37 sensor.ebl --enablerdprot
This builds an EM357 chip image output file, myimage.hex, from the two input files, serial-uart-bootloader.s37 and sensor.ebl. At the same time, read protection is enabled in the CIB content of the HEX file by setting option byte 0 to the value 0×00. Programming this chip image (the HEX file) to a fresh device will ensure that it contains the necessary application code, bootloader code and read protection. Additional manufacturing token content in the CIB can be set using the “—cibtokenspatch” argument with a manufacturing tokens patch file (as explained by the “—cibtokenspatch-help” argument to em3xx_buildimage or em3xx_load).
Q: If I enable write protection, how will that affect the bootloader?
A: (Note that the following applies to all of the bootloader types offered by Ember.) By write-protecting the first 8KB portion of main flash, where the bootloader resides, you prevent accidental/unauthorized overwrites of the bootloader code and the chip’s reset vectors. However, if regions beyond this are write-protected, this will prevent the bootloader from writing the downloaded firmware image into the application area of the MFB, thus rendering it ineffective. This is why Ember recommends leaving write protection disabled for the remaining flash regions if a bootloader is used in the memory map.
If, for some reason, you wish to deploy a device that doesn’t allow bootloading, you may protect additional regions of the MFB. However, take care not to enable write protection over the area used for Simulated EEPROM, usually the last 8KB region of the MFB (or the last 32KB in some EZSP network coprocessor designs), as this will prevent the stack from writing to the network and security-related tokens that it requires as part of normal operation.
Q: What about the areas that aren't covered by the write protection settings? Aren't they vulnerable to writes from an external debugger/programmer then?
A: Yes, areas that are not covered by write protection are potentially vulnerable to erasure and writing from an external debugger/programmer or from errant code executing flash-writing routines, even if read protection is enabled. Read protection will prevent reading of the flash, but the erasing and writing occurs through a flash interface controller, which is never disconnected and is capable of working without needing to read. (Note that Ember’s programming tools will prohibit writing/erasing of the flash when read protection is found to be active, which prevents accidental or malicious corruption of flash data when using Ember’s tools.) Therefore, the safest and most secure mode of operation is to write protect all sensitive areas of flash, except the Simulated EEPROM which must remain writable, and enable read protection. (As discussed above, write-protecting flash regions covered by application code will inhibit updating of the code via the bootloader.)
Q: What happens if there is a failure, such as reset, while writing an option byte?
A: If the option bytes themselves were to somehow become corrupted, the chip has a means to detect this state and will only boot into deep sleep mode until the failure is corrected through erasing/reprogramming of the CIB memory page. When corruption is detected, the option bytes are assumed to be the erased state, which will activate read protection. Ember’s em3xx_load tool can detect this failure/corruption, and using the “—fixobfail” argument with this tool will fix the issue.
Q: What kinds of debugging mechanisms will still be available on a device that has read and write protection enabled in the recommended configuration?
A: The DEI Port features (which are just TTL interfaces to the GPIOs) of the ISA3 and the PacketTrace Interface [PTI] features (which use alternate functions of the GPIOs for a digital, 2-wire protocol) of the ISA3 are still viable even when Read Protection is enabled. Additionally, normal digital I/O and serial controller usage remain possible when read protection and/or write protection are enabled.
Q: What about the Virtual UART interface (Serial 0 in InSight Desktop Console)?
A: Since the Virtual UART mechanism is implemented on top of the ARM Cortex’s SerialWire protocol, which uses the SerialWire/JTAG [SWJ] bus, it isn’t available when read protection is enabled. Read protection and SWJ bus access are mutually exclusive. However, you can still utilize the physical UART of the chip (TXD and RXD pins, PB1 and PB2) if the chip’s running firmware enables it. These TTL signals can be routed through the DEI interface of the ISA3 for access as “Serial 1” in the InSight Desktop Console as illustrated on the EM35x Breakout Board hardware.
Q: If I enable read and write protection, can I disable them later?
A: Yes, it’s possible to disable read protection and/or write protection using the ISA3 Utilities.
Disabling read protection is accomplished through the use of the “—disablerdprot” command argument with em3xx_load or em3xx_buildimage, which causes Option Byte 0 to be set to the special value of 0xA5. Any other state for Option Byte 0 causes read protection to remain active. Note that disabling this feature on an actual chip (with em3xx_load) will cause its MFB and CIB (besides Option Byte 0) to be fully erased back to 0xFF bytes.
While enabling read protection with em3xx_load requires a file to be specified in the command, disabling read protection does not include a file in the command:
C:\>em3xx_load my_file.s37 --enablerdprot
C:\>em3xx_load --disablerdprot
In addition, depending on your version of Windows, em3xx_load may need to be explicitly run in Admin mode.
Disabling write protection is accomplished using the “—programwrprot” command argument to set the write protection option bytes back to an all-0xFF state, such as “em3xx_load —programwrprot FFFFFF”. (Note that a “programmed” state of 0xFFFFFF is handled differently than an erased [unprogrammed] state, since checksum values for each option byte are also programmed by the ISA3 Utilities when an option bye is programmed. Once an option byte is programmed, the CIB must be erased before that option byte’s value can be changed.)
Q: After disabling read protection, is anything NOT erased?
A: Yes, the FIB (where Ember-programmed manufacturing tokens are stored) is left intact after read protection has been disabled. The MFB and CIB are not preserved when read protection has been disabled. Although the chip’s automatic erasure during deactivation of read protection only affects the MFB (where stack and application tokens reside along with bootloader and stack/application firmware), the act of patching the option bytes in the CIB to deactivate read protection requires that the entire CIB page be erased and re-written (as erasures can only occur on a per-page basis), and since the existing CIB content is unreadable until the unprotected state (value 0xA5 for Option Byte 0) is written, the newly written CIB page resulting from the CIB patching process must consist of fully erased bytes (other than Option Byte 0), meaning that none of the original CIB content can be preserved.
Enabling Read Protection or Write Protection for EM35x Chips
When preparing EM35x devices for field deployments, it is often desirable to secure the flash contents of the EM35x chip to prevent accidental/unauthorized access or modification. This can be done using the chip’s memory protection (Read Protection and Write Protection) mechanism, described in the EM35x Datasheet in Sections 5.2.1 (Flash Memory) and 5.3 (Memory Protection Unit).
Below are some of the common questions that customers ask when considering this kind of protection for their devices:
Q: What kinds of protection are available and what is protected by them?
A: The chip offers Read Protection and Write Protection.
Read Protection, when enabled, disconnects all flash from everything else when the chip’s SerialWire/JTAG interface (SWJ) is connected to something. This effectively prevents reading of all flash memory on the device, including the full 128KB or 192KB of main flash block (which covers the bootloader area, application code & data areas, and SimEEPROM token area), plus the FIB (flash information block where Ember-programmed manufacturing tokens and low-level flash read/write routines are stored) and the CIB (customer information block where customer-programmable manufacturing tokens are stored). This also prevents the use of the SWJ bus for SerialWire and JTAG operations such as debugger access and flash programming. Since read protection can only be disabled by writing a specific, non-zero, non-0xFF value to a specific location, the act of erasing of the CIB memory page (where the read protection option byte is contained), whether intentional or accidental, will still leave the chip read-protected until the appropriate option byte is set to the appropriate value.
Write Protection, when enabled, prevents writing or erasing of the main flash block [MFB], either by external means or through execution of code from flash or RAM. Unlike read protection, write protection is enabled on a per-region basis with each region being 4 pages of flash or 8KB.
Q: What kind of protection does Ember recommend using for deployed devices into mass production?
A: For devices that are deployed into the field in scenarios where no further debug or advanced testing is required, Ember recommends enabling Read Protection (which is chip-wide) as well as Write Protection of the first 8KB region, which is the section of the MFB where the bootloader firmware resides.
Q: How do I enable these recommended protection settings using the ISA3 and ISA3 Utilities?
A: Enabling these settings requires the use of the ISA3 Utilities from the command line; InSight Desktop does not currently provide an interface for passing these options to the loader through its GUI.
Enabling Write Protection
To enable write protection of the first region of main flash (where the bootloader resides), clear (write 0) only Bit 0 of the first option byte for write protection (Option Byte 4) and leave all other bits set (erased state of 1) for a final bitmask of 0xFFFFFE (0xFFFFFFFE for any chips with 512 KB of flash). This can be accomplished with the “—programwrprot” option in em3xx_load or em3xx_buildimage such as:
em3xx_load.exe --programwrprot FFFFFE
Note that current Ember implementations are such that write protection of this first region is currently done automatically whenever read protection is enabled. However, setting the write protection mask explicitly to include this first flash region is recommended to ensure consistent results should this automatic behavior change in future tool/silicon revisions.
Enabling Read Protection
NOTE: Enabling read protection should always be the last operation you perform on the device with em3xx_load or em3xx_buildimage since setting this option effectively inhibits any future changes to the chip/image state until read protection is disabled (which, in turn, causes the MFB and CIB to be erased).
To enable read protection, Option Byte 0 of the CIB can be set to 0×00 (though any value other than the special value of 0xA5 will suffice). This can be done using the “—enablerdprot” flag in em3xx_load or em3xx_buildimage, such as:
em3xx_buildimage.exe --em357 --chipimage myimage.hex serial-uart-bootloader.s37 sensor.ebl --enablerdprot
This builds an EM357 chip image output file, myimage.hex, from the two input files, serial-uart-bootloader.s37 and sensor.ebl. At the same time, read protection is enabled in the CIB content of the HEX file by setting option byte 0 to the value 0×00. Programming this chip image (the HEX file) to a fresh device will ensure that it contains the necessary application code, bootloader code and read protection. Additional manufacturing token content in the CIB can be set using the “—cibtokenspatch” argument with a manufacturing tokens patch file (as explained by the “—cibtokenspatch-help” argument to em3xx_buildimage or em3xx_load).
Q: If I enable write protection, how will that affect the bootloader?
A: (Note that the following applies to all of the bootloader types offered by Ember.) By write-protecting the first 8KB portion of main flash, where the bootloader resides, you prevent accidental/unauthorized overwrites of the bootloader code and the chip’s reset vectors. However, if regions beyond this are write-protected, this will prevent the bootloader from writing the downloaded firmware image into the application area of the MFB, thus rendering it ineffective. This is why Ember recommends leaving write protection disabled for the remaining flash regions if a bootloader is used in the memory map.
If, for some reason, you wish to deploy a device that doesn’t allow bootloading, you may protect additional regions of the MFB. However, take care not to enable write protection over the area used for Simulated EEPROM, usually the last 8KB region of the MFB (or the last 32KB in some EZSP network coprocessor designs), as this will prevent the stack from writing to the network and security-related tokens that it requires as part of normal operation.
Q: What about the areas that aren't covered by the write protection settings? Aren't they vulnerable to writes from an external debugger/programmer then?
A: Yes, areas that are not covered by write protection are potentially vulnerable to erasure and writing from an external debugger/programmer or from errant code executing flash-writing routines, even if read protection is enabled. Read protection will prevent reading of the flash, but the erasing and writing occurs through a flash interface controller, which is never disconnected and is capable of working without needing to read. (Note that Ember’s programming tools will prohibit writing/erasing of the flash when read protection is found to be active, which prevents accidental or malicious corruption of flash data when using Ember’s tools.) Therefore, the safest and most secure mode of operation is to write protect all sensitive areas of flash, except the Simulated EEPROM which must remain writable, and enable read protection. (As discussed above, write-protecting flash regions covered by application code will inhibit updating of the code via the bootloader.)
Q: What happens if there is a failure, such as reset, while writing an option byte?
A: If the option bytes themselves were to somehow become corrupted, the chip has a means to detect this state and will only boot into deep sleep mode until the failure is corrected through erasing/reprogramming of the CIB memory page. When corruption is detected, the option bytes are assumed to be the erased state, which will activate read protection. Ember’s em3xx_load tool can detect this failure/corruption, and using the “—fixobfail” argument with this tool will fix the issue.
Q: What kinds of debugging mechanisms will still be available on a device that has read and write protection enabled in the recommended configuration?
A: The DEI Port features (which are just TTL interfaces to the GPIOs) of the ISA3 and the PacketTrace Interface [PTI] features (which use alternate functions of the GPIOs for a digital, 2-wire protocol) of the ISA3 are still viable even when Read Protection is enabled. Additionally, normal digital I/O and serial controller usage remain possible when read protection and/or write protection are enabled.
Q: What about the Virtual UART interface (Serial 0 in InSight Desktop Console)?
A: Since the Virtual UART mechanism is implemented on top of the ARM Cortex’s SerialWire protocol, which uses the SerialWire/JTAG [SWJ] bus, it isn’t available when read protection is enabled. Read protection and SWJ bus access are mutually exclusive. However, you can still utilize the physical UART of the chip (TXD and RXD pins, PB1 and PB2) if the chip’s running firmware enables it. These TTL signals can be routed through the DEI interface of the ISA3 for access as “Serial 1” in the InSight Desktop Console as illustrated on the EM35x Breakout Board hardware.
Q: If I enable read and write protection, can I disable them later?
A: Yes, it’s possible to disable read protection and/or write protection using the ISA3 Utilities.
Disabling read protection is accomplished through the use of the “—disablerdprot” command argument with em3xx_load or em3xx_buildimage, which causes Option Byte 0 to be set to the special value of 0xA5. Any other state for Option Byte 0 causes read protection to remain active. Note that disabling this feature on an actual chip (with em3xx_load) will cause its MFB and CIB (besides Option Byte 0) to be fully erased back to 0xFF bytes.
While enabling read protection with em3xx_load requires a file to be specified in the command, disabling read protection does not include a file in the command:
In addition, depending on your version of Windows, em3xx_load may need to be explicitly run in Admin mode.
Disabling write protection is accomplished using the “—programwrprot” command argument to set the write protection option bytes back to an all-0xFF state, such as “em3xx_load —programwrprot FFFFFF”. (Note that a “programmed” state of 0xFFFFFF is handled differently than an erased [unprogrammed] state, since checksum values for each option byte are also programmed by the ISA3 Utilities when an option bye is programmed. Once an option byte is programmed, the CIB must be erased before that option byte’s value can be changed.)
Q: After disabling read protection, is anything NOT erased?
A: Yes, the FIB (where Ember-programmed manufacturing tokens are stored) is left intact after read protection has been disabled. The MFB and CIB are not preserved when read protection has been disabled. Although the chip’s automatic erasure during deactivation of read protection only affects the MFB (where stack and application tokens reside along with bootloader and stack/application firmware), the act of patching the option bytes in the CIB to deactivate read protection requires that the entire CIB page be erased and re-written (as erasures can only occur on a per-page basis), and since the existing CIB content is unreadable until the unprotected state (value 0xA5 for Option Byte 0) is written, the newly written CIB page resulting from the CIB patching process must consist of fully erased bytes (other than Option Byte 0), meaning that none of the original CIB content can be preserved.