This code example illustrates the imitation of temporarily disabling the debug access port (DAP) and enabling DAP after successful RSA signature verification of the password using the crypto module.
The device used in this code example (CE) is:
The board used for testing is:
- TRAVEO™ T2G evaluation kit (KIT_T2G-B-H_LITE)
In this CE, we configure T2G's access port control register (CPUSS_AP_CTL) to temporarily disable and enable DAP upon successful password verification. Generally, during the NORMAL_PROVISIONED life-cycle stage, access restrictions for DAP are implemented by writing into the NORMAL access restriction (NAR) row in supervisory flash (SFlash). Then the ROM/flash boot reads from the SFlash and configures CPUSS_AP_CTL register accordingly. However, the access restrictions in NAR cannot be widened to lower the existing restrictions. Thus, to avoid permanently locking of the DAPs, we control the access ports (APs) by temporarily writing the CPUSS_AP_CTL register.
To disable the APs, the user can press User Button 1. The interrupt triggered will disable the APs and the debugger connection is lost. Once the user sends the correct signature of the password based on RSA over UART, the APs are enabled and debugging can be resumed. If a wrong password signature is sent 3 times, then the APs are never re-enabled and debugging of the cores is not possible until the device is reset.
DAP
DAP acts as the program and debug interface. This allows the connection to the three access ports: CM0_AP, CM7_AP, and System_AP. The external programmer or debugger, also known as the 'host', communicates with the DAP using either the Serial Wire Debug (SWD) or Joint Test Action Group (JTAG) interface. The DAP also includes the SWD listener which decides if the JTAG interface (default) or SWD interface is active. Note that JTAG and SWD are mutually exclusive because they share pins. The debug port connects to the DAP bus, which in turn connects to one of the three APs.
This CE works with SWD interface and all the APs will be enabled or temporarily disabled.
Debug access restrictions
This determines the debug port access restrictions and has three states corresponding to the protection state: NORMAL, SECURE, and DEAD. This code example focuses on imitating NORMAL access restrictions stored in SFlash. This restriction is written in row 13 of the SFlash. The access restrictions are encoded with a 'Disable' bit and an 'Enable' bit as follows:
- Enable AP - 00
- Disable (temporarily) AP - 01
- Permanently Disable AP - 1x
Here, the Disable bit has a higher priority than the Enable bit. The Boot applies the value of Disable bit and inverse value of the Enable bit. Therefore, '01' corresponds to Disable Bit = 0 and Enable Bit = 0.
When NORMAL access restrictions are requested to be updated and if the new restrictions are wider than the existing ones, this request will be invalid. For instance, if row 13 was written with 'Disable AP', it cannot be updated to 'Enable AP'. An AP that is permanently disabled, cannot be re-enabled. This could lead to permanent locking of the device.
Alternatively, instead of the BOOT applying the NAR configuration, the CPU's access port control register (CPUSS_AP_CTL) can be written through a program to control the APs. This register enables individual APs. Typically, this field is set by the boot code with information from the NAR SFlash row (in NORMAL_PROVISIONED lifecycle stage). To enable the following APs, the register bits should be as follows:
- System AP - SYS_DISABLE bit is '0' and SYS_ENABLE bit is '1'
- CM7_0 and CM7_1 AP - CM7_DISABLE is bit '0' and CM7_ENABLE bit is '1'
- CM0 AP - CM0_DISABLE bit is '0' and CM0_ENABLE bit is '1'
This CE will disable and enable all the above APs.
Cryptography block
The cryptography function block of TRAVEO™ T2G supports Secure Hash Algorithm (SHA). This functionality produces a fixed-length hash (also called 'message digest') of up to 512 bits from a variable-length input data (called 'message').
In this CE, SHA functionality is used to verify the password sent by the user over UART. Asymmetric cryptography is implemented where the sender generates a digital signature of a message using its private key and any receiver can verify this message by using the sender’s public key or vice versa. A popular asymmetric cryptography algorithm is RSA, which is supported by the crypto driver.
Terminologies to be noted:
- Plaintext - An unencrypted message.
- Digital digest/signature - Signature generated by SHA-256 function that operates on a block of data.
- Hash - A crypto algorithm that generates a repeatable but unique digest for a given block of data. SHA is used to derive a hash value from a user password.
- SHA-256 - A cryptographic hash algorithm used to create a digest for a block of data or code. This hash algorithm produces a 256-bit unique digest of the data no matter the size of the data block.
The encrypted signature is created by computing the hash of the plaintext and then encrypting it with a private key. This encrypted signature is stored in Password_Signature.txt. Encrypted Digital Signature is decrypted using the public key, to reveal the decrypted digital signature. The calculated digital digest and the decrypted digital digest (signature) are then checked for an exact match. If they are an exact match, the password is verified.
More details can be found in Technical Reference Manual (TRM), Registers TRM and Data Sheet.
This CE has been developed for:
- TRAVEO™ T2G evaluation kit lite (KIT_T2G-B-H_LITE)
No changes are required from the board's default settings.
A UART serial connection should be made with the computer via the serial port (KitProg3 connector). Use CoolTerm terminal application to see the output on the screen.
In this CE, the device life-cycle stage is NORMAL_PROVISIONED. The program toggles user LED and waits for an interrupt triggered by the user button event. The interrupt handler will disable the access ports and stops toggling the user LED. When the correct password signature is sent over UART and verified by the program, the program will enable the APs and LED will resume toggling.
STDOUT/STDIN setting
Initialization of the GPIO for UART is done in the cy_retarget_io_init() function.
- Initializes the pin specified by CYBSP_DEBUG_UART_TX as UART TX and the pin specified by CYBSP_DEBUG_UART_RX as UART RX (these pins are connected to KitProg3 COM port)
- The serial port parameters are 8N1 and 115200 baud
GPIO pin configuration
The GPIO port address is calculated based on the port number through Cy_GPIO_PortToAddr(). This data is later used for initialization of GPIO pins.
The GPIO pins are initialized using Cy_GPIO_Pin_FastInit(). User LED (USER LED 1) is configured to output mode. The active-low GPIO pin toggles when the APs are enabled.
User button 1 is configured to input mode. It is also associated with an interrupt handler - handleGPIOinterrupt, which is triggered when the button is pressed. The interrupt is set on the falling edge of the signal via Cy_GPIO_SetInterruptEdge() and configures the pin interrupt to be forwarded to CPU using Cy_GPIO_SetInterruptMask().The interrupt is initialized with its interrupt handler through Cy_SysInt_Init().
Crypto initialization
The crypto hardware block is enabled by calling Cy_Crypto_Core_Enable(). As the crypto functions, used in this CE, treat data (such as message or key) in little endian format, Cy_Crypto_InvertEndianness() inverts the endianness.
User input
When the user button is pressed, the program waits for an input - the password to unlock DAP. Using UART serial communication, the user can input password on CoolTerm terminal.
Code example main loop
The endless loop of the CE in main() always toggles the LED by calling Cy_GPIO_Inv() until the user button is pressed. When the button is pressed, checkUARTpassword() is called.
Password check
The handleGPIOinterrupt() function is called when the user button is pressed. The APs are disabled and the LED is turned off via Cy_GPIO_Write(). The handler also clears the triggered interrupt though Cy_GPIO_ClearInterrupt().
Then, checkUARTpassword() checks whether a character has been received from the user via UART (terminal) using cyhal_uart_getc(). The character recieved will be displayed on the terminal using cyhal_uart_putc(). When PASSWORD_SIGNATURE_SIZE (128) bytes are received, signature decryption and verification is performed. However, if incorrect password is sent MAX_PASSWORD_CHECK times, the button interrupt is disabled. This mimics the locking of the device and the user should reset the device and the debugger to start the test again.
Password verification
verifyRSAsignature() verifies the password.
To verify the RSA signature, the following steps are done:
- The RSA public key structure PUBLIC_KEY is assigned with the RSA public key data, which includes the modulus and the exponent part.
- SHA Hash function - Cy_Crypto_Core_Sha() is performed to calculate SHA digest.
- The encrypted signature is decrypted using Cy_Crypto_Core_Rsa_Proc().
- Finally, the decrypted signature is verified with the calculated SHA digest using Cy_Crypto_Core_Rsa_Verify().
If the password is a match, the APs are enabled.
For this CE, CoolTerm terminal is required for displaying outputs and to send data over UART. Install CoolTerm as instructions in this document is based on this terminal application.
After code compilation, perform the following steps for flashing the device:
-
Connect the board to your PC using the provided USB cable through the KitProg3 USB connector.
-
Open CoolTerm and click on Options. Choose the correct KitProg COM port under Port and Baudrate to 115200. To apply the changes, click on OK.
Figure 1. CoolTerm Options Configuration
-
Click on Connect to connect to the COM port.
Figure 2. CoolTerm connect to COM Port
-
To program the board:
- Select the code example project in the Project Explorer.
- In the Quick Panel, scroll down, and click [Project Name] Program (KitProg3_MiniProg4).
-
As this CE requires debugging to verify the test steps, you can debug the example to step through the code. In the IDE, use the [Project Name] Debug (KitProg3_MiniProg4) configuration in the Quick Panel. For details, see the "Program and debug" section in the Eclipse IDE for ModusToolbox™ software user guide.
-
On the UART terminal, a message will be displayed to press User Button 1. The user can press the user button and the user will be prompted to send the password to unlock DAP.
-
To send the password over UART, click on Connection and then Send String.
Figure 3. CoolTerm Send String
-
Check the radio button Hex and enter/paste the password in the box. Then click Send.
Figure 4. CoolTerm Send String in Hex
-
Debugging procedure: The following debugging features are used in the order mentioned below, to test the behaviour:
Figure 5. IDE Debug Features
- Resume the program if it not already running
- Suspend the program
- Step Over a few times
- Resume the program if stepping over is possible (the current debug instruction pointer will step over to the next instruction). Debugging is considered possible if stepping over is possible. (Please read Note 1)
Note 1: While trying to use the debug features after unlocking DAP, it is possible that an error message (such as 'Interrupt failed') might appear. If that is the case:
- Terminate the debug session (if not terminated)
- Go to the Menu bar and click on Run->Debug Configurations..
- Select [Project Name] Attach (KitProg3_MiniProg4) and click on Debug
- Continue with the debugging procedure as mentioned above
Note 2: If Tera Term terminal is used, the password can be sent through UART by sending a binary file, named Password_Signature.bin.
Note 3: (Only while debugging) On the CM7 CPU, some code in main() may execute before the debugger halts at the beginning of main(). This means that some code executes twice: once before the debugger stops execution, and again after the debugger resets the program counter to the beginning of main(). See KBA231071 to learn about this and for the workaround.
Expected behavior
To demonstrate DAP control, ensure the program is run in debug mode to verify the possibility of debugging when APs are disabled.
-
Test 1: Verification with Correct Password
- User LED is toggling. Execute the debugging procedure (in mentioned order). Debugging is possible.
- Press User Button 1 to disable the APs. The LED stops toggling. Execute the debugging procedure. Debugging is not possible.
- Send the correct password (128 bytes) through UART. The correct password is stored in Password_Signature.txt.
- UART terminal displays status of password verification. In this case, 'Correct Password'. LED resumes toggling.
- Execute the debugging procedure. Debugging is possible.
Figure 6. Terminal display for verification with correct password
-
Test 2: Verification with Incorrect Password
- User LED is toggling. Execute the debugging procedure. Debugging is possible.
- Press User Button 1 to disable the APs. The LED stops toggling. Execute the debugging procedure. Debugging is not possible.
- Send an incorrect password (128 bytes) through UART.
- UART terminal displays status of password verification. In this case, 'Incorrect Password'. LED won't resume toggling.
- Send the correct password (128 bytes) through UART. The correct password is stored in Password_Signature.txt.
- UART terminal displays 'Correct Password'. LED resumes toggling.
- Execute the debugging procedure. Debugging is possible.
Figure 7. Terminal display for verification with incorrect password
-
Test 3: Incorrect Password sent Maximum Times
- User LED is toggling. Execute the debugging procedure. Debugging is possible.
- Press User Button 1 to disable the APs. The LED stops toggling. Execute the debugging procedure. Debugging is not possible.
- Send an incorrect password (128 bytes) through UART thrice. In this CE, maximum limit is thrice.
- UART terminal displays status of password verification. In all the cases, 'Incorrect Password' will be displayed. LED won't resume toggling.
- Reset the device and debug mode on IDE again to repeat any other tests.
Figure 8. Incorrect Password sent Maximum Times
Relevant Application notes are:
- AN235305 - GETTING STARTED WITH TRAVEO™ T2G FAMILY MCUS IN MODUSTOOLBOX™
- AN228680 - Secure system configuration in TRAVEO™ T2G family
- AN220253 - Using the CRYPTO module in TRAVEO™ T2G family
ModusToolbox™ is available online:
Associated TRAVEO™ T2G MCUs can be found on:
More code examples can be found on the GIT repository:
For additional training, visit our webpage:
For questions and support, use the TRAVEO™ T2G Forum: