Generic workflows

This section provides information on workflow for some typical use cases. These chapters are not specific for any processor.

Debug authentication workflow

This section describes the process of opening the debug port. This tool offers Debug Authentication Protocol (DAP) as a mechanism to authenticate the debugger (an external entity) for the field technician, which has the credentials approved by the product manufacturer (OEM) before granting the debug access to the device. For Debug Authentication (DA) to work, processor-specific fuses or PFR fields must be set. For more information see the device user manual, chapter Debug subsystems.

Debug Authentification protocol usage example

To open the debug port, do the following:

Field Technician

1. To get the key type and ROT length, contact the OEM. OEM decides whether to use the generated certificate for any device with the same ROT keys or just one by specifying the UUID.

2. In the SEC Tool, create a workspace for the used target device, switch to the “PKI Management” view

3. Click the Generate a debug key… button and verify that both the key type and length of the DA key match those of the corresponding ROT key.

4. Click the Create debug certificate request… button. Optionally, specify UUID to limit the use of the debug certificate. If the UUID is set to zero, it can be used for any device. UUID can be read from a device via UART or USB if the processor is in ISP mode and in the development life cycle. For processors in an advanced life cycle, the debug probe works. On most devices, CHECK_UUID must be set in the SOCU fuse/PFR field to enable verification of the UUID in the debug certificate.

5. Send the certificate request to OEM

6. After the certificate from OEM is received, click the Open debug port… button. The connected probes are detected upon the dialog display. The list of detected probes can be updated by clicking the Find probes button. Select one of the detected probes. The authentication beacon is an optional parameter and it is independent from the credential beacon provided by the OEM. It is not interpreted by the debug authentication protocol, it is passed to the debugged application. When the dialog is confirmed, a script is generated into workspace\debug_auth\open_debug_port.[bat|sh] and is executed. The dialog will be closed if no error is reported by the script (the operation is successful). In case of failure, refer to section Debug authentication for details on how to enable debug authentication.

   Note: nxpdebugmbox CLI tool can be found in <installation_dir>/tools/spsdk/ folder

Dialog for opening debug port

OEM Developer

After receiving the request, click the Generate debug certificate… button.

The certificate is by default generated into <workspace>/debug_authfolder, debug_auth_cert.dc. A *.zip archive with the same name is created, it contains the certificate and the .txt file note from OEM. The note that is passed from field technician to OEM is displayed in the note field (see Figure “Generation of debug certificate from certificate request”).

• SoC - mask value of DCFG_CC_SOCU controlling which debug domains are accessed via the authentication protocol

• Vendor usage - field that can be used to define a vendor-specific debug policy. The use case can be Debug Credential (DC) certificate revocations, the department identifier, or the model identifier.

• Credential beacon - value that is not interpreted by DAP, it is passed to the application. The value is independent of the authentication beacon that will be provided by the field technician when the port is opened.

• Note - text field where OEM can describe comments about reasons to generate the certificate

• Sign with ROT key - sign the certificate with one of the ROT keys that were used to secure the device.

Generation of debug certificate from certificate request

Example of access rights to debug domains

Examples are intended for testing purposes. Before the final usage, the setting should be revisited and modified to fulfill security requirements. In all examples below, ISP is enabled and UUID check is disabled. For some processors, UUID check must be set to enable the read of UUID by a debug probe.

Table KW45xx/K32W1xx and MCX W71x

Fuse	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU_L1, DCFG_CC_SOCU_L2	0x000000FF	0x0000FFFF	0x00004040
DBG_AUTH_DIS	0x0	0x0	0x0

Table KW47xx and MCX W72x

Fuse	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU_L1, DCFG_CC_SOCU_L2	0x000001FF	0x0003FFFF	0x00008040
DBG_AUTH_DIS	0x0	0x0	0x0

Table LPC55S0x/1x, MCXW236 and NHS52S04

PFR field	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU_NS_PIN, DCFG_CC_SOCU_PIN	0xFF2000DF	0xFF2000DF	0xFFBF0040
DCFG_CC_SOCU_NS_DFLT, DCFG_CC_SOCU_DFLT	0xFFFF0000	0xFF2000DF	0xFFBF0040

Table LPC55S2x

PFR field	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU_NS_PIN, DCFG_CC_SOCU_PIN	0xFF2000DF	0xFF2C00D3	0xFFBF0040
DCFG_CC_SOCU_NS_DFLT, DCFG_CC_SOCU_DFLT	0xFFFF0000	0xFF2C00D3	0xFFBF0040

Table LPC55S3x

PFR field	Everything disabled	Everything enabled*	Controlled by DA
DCFG_CC_SOCU_NS_PIN, DCFG_CC_SOCU_PIN	0xFE3001CF	0xFE3001CF	0xFFFF0000
DCFG_CC_SOCU_NS_DFLT, DCFG_CC_SOCU_DFLT	0xFFBF0040	0xFE3001CF	0xFFFF0000

Note: For debugging, authentication is still required but the domain cannot be disabled by the SoC mask in the DAC.

Table LPC55S6x

PFR field	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU_NS_PIN, DCFG_CC_SOCU_PIN	0xFD0002FF	0xFD0002FF	0xFFBF0040
DCFG_CC_SOCU_NS_DFLT, DCFG_CC_SOCU_DFLT	0xFFBF0040	0xFD0002FF	0xFFBF0040

Table MCX Nx4x and MCX N23x

PFR field	Everything disabled	Everything enabled*	Controlled by DA
DCFG_CC_SOCU_NS_PIN, DCFG_CC_SOCU_PIN	0xF81007EF	0xF81007EF	0xFFBF0040
DCFG_CC_SOCU_NS_DFLT, DCFG_CC_SOCU_DFLT	0xFFBF0040	0xF81007EF	0xFFBF0040

Note: For debugging, authentication is still required but the domain cannot be disabled by the SoC mask in the DAC.

Table RT5xx/6xx

Fuse	Everything disabled	Everything enabled	Controlled by DA
DCFG_CC_SOCU, DCFG_CC_SOCU_NS	0x80FF408D	0x80FFFF20	0x00404088
DCFG_CC_SOCU_AP	0x7F00BF72	0x7F0000DF	0xFFBFBF77

Table RW61x

Fuse	Everything disabled	Everything enabled*	Controlled by DA
DCFG_CC_SOCU, DCFG_CC_SOCU_NS	0x3FFA007E	0x3FFFFF14	0x1002000F
DCFG_CC_SOCU_AP	0xC005FF81	0xC00000EB	0xEFFDFFF0

Note: For debugging, authentication is still required but the domain cannot be disabled by the SoC mask in the DAC.

RT118x does not have any fuse to control debugging rights. Debugging depends on the LC, for OEM_OPEN: all debug allowed, OEM_CLOSE: all closed but can be enabled by DAC, and OEM_LOCKED: all closed and cannot be enabled. The only way to manage debugging rights in OEM_CLOSE is by setting the SoC in DAC. For examples of SoC masks, see the device user manual.

Signature provider workflow

This section describes the process of setting up signature provider and building an image signed by the signature provider. There are examples of the signature provider server located in <install_folder>/sample_data/signature_provider_examples, one working with ROT ECC keys and the other with ROT RSA keys. These examples demonstrate the full implementation of the API; however in the real world, it is expected that the implementation will be changed by communication with HW HSM module or custom HTTPS communication to another server. Both examples of the server can be used as they are to test tool behavior when using the signature provider. Each server has example private keys and prepared public key response for the public_keys_certs endpoint. A prepared ECC/RSA public tree have 4 ROT keys/certs and each ROT key/cert has one IMG key/cert. These keys should not be used in final products.

The figure below displays variants of signature provider, SEC Tool send requests to Custom signature provider HTTP server. This server should pass the request to one of the secure solutions and then pass the response back to the SEC Tool. Prepared examples implement only the Custom signature provider HTTP server. The example server is doing all the operation that should be done by an HSM or external signature provider. It is up to the user to implement a complete solution.

Expected structure of signature provider

Run the server

Ensure python 3.12 or higher is installed. Open the directory where the server implementation and specify version of SPSDK package in requirements.txt to be used (use same version as listed in main menu > Help > About) and run the following commands:

# ensure, venv is installed
pip install virtualenv
# create virtual environment into .venv subfolder
python -m venv ".venv"
# activate it
.venv\Scripts\activate
# install all required packages into venv
pip install -r requirements.txt
# start the server
python server.py

The server logs every action, so it is possible to review what actions were executed.

Set up in the SEC Tool

To use the signature provider example with the SEC Tool, follow these steps:

1. Create/use workspace for the processor.

2. Select the check-box Use sign. provider on the PKI tab. If there are keys in the workspace, they are moved to a back-up subfolder in the workspace.

3. Open the signature provider dialog by clicking Configure… next to the check-box from step 2.

4. Review the default parameters of your signature provider. If using the signature provider server from resources\signature_provider_examples, the default settings will work.

5. Select the prehash option in the parameters table. When prehash is enabled, only a hash of the data is sent to the server for signing.

6. Click the Test connection button to verify if the server is configured properly.

7. There are two options to Import public keys:

   • In the same dialog, click the Import public keys button to import public keys from the server; this is a recommended way, however it can be used only if the server implements optional API public_keys_certs.

   • If the Import public keys command is not supported, the alternative way is to use Import keys from the PKI management tab. Make sure that public keys match private keys that are used on the signature provider site (copy the keys to the folder with the signature provider example).

8. On the Build tab, select the key as normally, now the config files for SB, MBI, and certification block will be using the signature provider configuration.

9. Now, the signature provider is configured. It is possible to build a signed image.

Signature provider and debug authentication

The SEC Tool supports signing of the DA certificate by the signature provider. The field technician flow of the DA key generation is the same as without the signature provider; the debug key pair generation is supported only locally. The only difference is that in the DAC generation on the OEM site, the signature provider is used for signing. This is transparent to the user as the public key is selected from the workspace keys. The only difference is in the generated configuration file, where the sign_provider field is set according to the signature provider setting.

Script hooks workflow

Script hooks are executed before or during build, write, and manufacturing script execution. Script hooks enable script customization outside the generated scripts. Hook scripts are located in the “hooks” subfolder and the new workspace contain the examples for the selected processor. Script hooks are not generated by the tool; they are expected to be fully under user control. If the hook script does not exist, it can be created with a single click in the GUI.

Build script hooks

1. Pre-build hook: pre_build_<os-name>.bat/sh is executed before the build script. This script can be generated to sign the MCUboot application image. This script does not have any argument and it is called only from the GUI before the build script is executed.

2. Build context hook: build_context_<os-name>.bat/sh is called at the beginning of the build script and allows users to add or modify the environment variables. This hook is called without arguments.

3. Build hook: the build_.bat/sh script is executed after each main step in the build script. This script is called from the build script and the name of the previous step is passed as an argument. All the supported steps are handled in the generated examples. If a hook step call fails, the build script execution stops and exits with an error.

Write script hooks

1. Write the context hook: the write_context_<os-name>.bat/sh script is called at the beginning of the write script and allows users to add or modify the environment variables. This hook is called without arguments.

2. Write the hook: the write_<os-name>.bat/sh script is executed after every main step in the write script. The script is called from the write script and the name of the previous step is passed as an argument. All the supported steps are handled in the generated example. If a hook step call fails, the write script execution stops and exits with an error.

Manufacturing hooks

Manufacturing hook: manufacturing_<os-name>.bat/sh is called at the beginning and end of the manufacturing process before the first task is started and after the last task is finished. If manufacturing hook execution for step started fails, planned manufacturing steps are not executed. The call for step finished has an additional argument status that can have two values ok or fail that denote the execution status of the manufacturing process: ok if all tasks were finished successfully, fail otherwise.

Typical usage

Here are a few examples how the hook scripts can be used to customize the build, write, or manufacturing script without the modification of the script generated from the SEC Tool:

• Update the input source file(s) for the build.

• Fix the problem in the write script or apply an additional action that updates the previous action.

• Synchronize the manufacturing operation with the assembly line.

Manufacturing workflow

For the manufacturing operations, the tool offers a simplified user interface focused on the manufacturing only.

Create manufacturing package

OEM can create a manufacturing package (*.zip) that can be used to transfer files to the factory. The manufacturing package can be created:

• On the Write image view - for provisioning using the current write script

• In the SB editor - to apply commands specified in the SB file

Create Manufacturing Package dialog

The Create Manufacturing Package dialog allows the user to:

• Review files included in the package.

• Check the write script arguments, the arguments are in the same format as they are used in Manufacturing Tool.

• Select the output manufacturing package file path.

• Set the password for the ZIP file. The AES algorithm is used to encrypt files in the ZIP file; however, the file metadata (like file names and file sizes) are not encrypted.

• For the EdgeLock 2GO provisioning, it is possible to optionally specify the API key in the manufacturing package, but it can be specified later during manufacturing

Performance optimization

It is supposed that the provisioning/write script will be executed several times to address different development issues, so the script is designed primary for this use case and may contain some parts that are not necessary in manufacturing when the provisioning is applied to an empty processor. Here are some tips to improve manufacturing performance by manually modifying the generated script:

• It might not be needed to erase boot memory. If the processor is new, the flash is already erased.

• It might not be needed to detect if the chip is already secured; this part in the write script allows updating application for secured processors (for chips where it is supported)

• A longer sequence of blhost operations might not be optimal, because the blhost initialization time is not insignificant. It might be better to move the operations into the SB file (see SB editor) or use blhost batch command (see SPSDK documentation for details).

• If the processor is reset during manufacturing, there is a delay time until it boots and the OS driver reconnects. By default it is 3 seconds. The time can be adjusted in preferences.

Manufacturing operations

On the manufacturing site, the manufacturing package can be imported using main menu > File > Import Manufacturing Package…. During import, the files from the package are extracted into the new workspace - called manufacturing workspace. For more information about importing the package, see Import workspace from the ZIP.

Once the workspace is created (or reopened), the Manufacturing Tool (for details, see Manufacturing Tool ) is displayed, and the rest of the tool functionality is not available. If the Manufacturing Tool is closed, the whole tool operation is finished. If you restart the tool, it offers to continue manufacturing, or to select another workspace:

Confirmation to reopen manufacturing

If the manufacturing package contains a write script, check if the SPT_INSTALL_BIN environment variable in the script points to the installation directory on the computer. If not, it is recommended to set the environment variable globally or update the write script manually.

For serial connection: Adjust the baud rate, the default value is 115200; however, for several processors, baud rates up to 1000000 were successfully tested.

Steps in the manufacturing production

1. Connect one or more processors via USB or serial line or I2C or SPI and click the Autodetect button to detect the connected devices. In case the tool detects devices that should not be affected by the manufacturing, such as serial ports used by other devices, disable them. Then click Test connection below to check the connection with all enabled processors and ensure the test pass.

2. To start the trust provisioning operation, click the Start button. Wait until all operations are finished.

3. If any problem is reported, click to the status cell to show the log and fix the problem.

4. Continue with step 1

The number of successfully provisioned devices is displayed on the bottom of the Manufacturing Tool window, but it is not 100% reliable.

Manufacturing logs

Manufacturing logs are stored in the manufacturing workspace, in the subdirectory logs/YYYY-MM-DD/. The log file name is manufacturing_log_YYYY-MM-DD_hh-mm-ss_#.log, where # represents index of the manufacturing task being executed in parallel. It is possible to export them using the Export logs button from the manufacturing window. The export allows to select one day (a date) or all logs and exports the selected logs into the ZIP file.

MCUboot workflow

MCUboot is an open source secure bootloader for 32-bit microcontrollers. For details, see MCUboot Documentation. It has been ported to many NXP processors, and you can find it supported in the MCUXpresso SDK. For details, see boards\<board>\ota_examples\mcuboot*.

For most of the processors, the SEC Tool contains a default configuration compatible with project examples provided in the MCUXpresso SDK. Therefore, there is a “sample application” built from MCUXpresso SDK for the EVK/FRDM board and the default imgtool parameters match MCUXpresso SDK.

Steps to start MCUboot for NXP board via New Workspace

1. Open the New Workspace dialog and select the processor.

2. Connect the board via UART, ensure that the processor boot is in ISP mode. It is possible to use other connections, the UART is used because the mcuboot application is built with the debug console and prints the status that can be verified using the terminal.

3. Select the MCUboot bootloader image, and the corresponding sample application for the selected processor (including both the bootloader and executable image) will be automatically chosen. If no image is selected, it indicates that a sample application is not available for the selected processor. In such cases, refer to the manual configuration instructions below

4. Select the required profile with memory settings compatible with the sample application, and create the workspace. For MCX N series, IFR must be used.

5. The MCUboot Sign Image dialog will open with all required options preselected, so it is possible to save the options and sign the image.

6. Build and write the bootable image into the processor. Note: To verify everything works correctly, refer to step 9. of the manual configuration below.

Steps to start MCUboot with such a processor manually

1. Create a new workspace for the selected processor.

2. Connect the board via UART, ensure that the processor boot is in ISP mode, and check the connection (main menu > Target > Connection…). It is possible to use other connections, the UART is used because the mcuboot application is built with the debug console and prints the status that can be verified using the terminal.

3. Verify the selected boot memory in main menu > Target > Boot Memory…. For MCX N series, IFR must be used.

4. On the Build image view, select the “mcuboot opensource” application as “Source executable image”. The prebuilt application is available in sample_data\targets\<processor>\source_images\<board>_mcuboot_opensource.s19. You can also build your own from MCUXpresso SDK. If the application contains a configuration of the external flash (FCB), the tool detect and offers to use it. It is recommended to accept.

5. Open main menu > Tools > MCUboot > Sign Image and configure the following:

   • The secondary application to be signed; the prebuilt application is available in sample_data\targets\<processor>\source_images\<board>_ota_mcuboot_basic.s19

   • The signing key; it is located in the same folder that the prebuilt application or in MCUXpresso SDK, in folder boards\<board>\ota_examples\mcuboot_opensource\keys\. Depending on the platform. use either sign-rsa2048-priv.pem or sign-ecdsa-p256-priv.pem. Keys protected by a password are not supported yet.

   • The imgtool arguments by default should match the SDK example. It is not needed to change them.

   • Click the Sign button to sign the application; fix problems, if any.

   • Ensure that the check boxes below are selected:

     • the first check-box: the tool creates the pre-build hook script that signs the application before each build

     • second check-box: the tool reconfigures additional images, so the signed image is written to the target address; keep “Image 1”

   • Verify the target address of the application.

   • Close the dialog by clicking the Save & Close button.

6. On the Build tab, double-check that the Build script hooks section contains the pre-build script.

7. Open Additional Images and check that the signed application is properly configured as “Image 1”.

8. Build and write the bootable image into the processor.

9. Open a terminal (in MCUXpresso IDE go to main menu > Windows > Show View > Other > Terminal), select the UART port, confirm, and reset the processor. You should receive the following text:

   hello sbl.
   Bootloader Version 2.0.0
   Primary   slot: version=1.0.0+0
   Image 0 Secondary slot: Image not found
   writing copy_done; fa_id=0 off=0xfffd0 (0xfffd0)
   Image 0 loaded from the primary slot
   Bootloader chainload address offset: 0x0
   Reset_Handler address offset: 0x400
   Jumping to the image
   
   Booting the primary slot - flash remapping is disabled
   
   *************************************
   * Basic MCUBoot application example *
   *************************************
   Built Apr 16 YYYY 12:34:56
   

To sign and write a second copy of the application, follow additional steps:

1. Disconnect the terminal if it is still open. Reset the board to ISP mode.

2. Open main menu > Tools > MCUboot > Sign Image…

3. Keep the same input application image.

4. Change the output image name, for example add suffix 1_1

5. In imgtool arguments, change version to 1.1

6. In the Set additional image section change:

   • Image 2

   • Target address - increase the address by the slot size (see the slot size parameter in the imgtool arguments)

7. Save and Close.

   Note: The pre-build script will be overwritten and it will sign Image 2. The previously signed Image 1 remains on the disk untouched and it will be written to flash at the original location.

8. Open Additional Images and check that there are two applications: “Image 1” and “Image 2”.

9. Build and write.

10. Connect the terminal, switch the board to boot from the selected boot memory, and reset. The terminal should receive the following text:

    hello sbl.
    Bootloader Version 2.0.0
    Primary   slot: version=1.0.0+0
    Secondary slot: version=1.1.0+0
    writing copy_done; fa_id=1 off=0xfffd0 (0x1fffd0)
    Image 0 loaded from the secondary slot
    Bootloader chainload address offset: 0x100000
    Reset_Handler address offset: 0x100400
    Jumping to the image
    
    Booting the secondary slot - flash remapping is enabled
    
    *************************************
    * Basic MCUBoot application example *
    *************************************
    
    Built Apr 16 YYYY 13:24:56
    

EdgeLock 2GO trust provisioning workflow

EdgeLock 2GO is a fully managed cloud platform operated by NXP that provides secure provisioning services for easy deployment and maintenance of IoT devices using supported NXP products. The service allows creating and managing secure objects, such as symmetric keys, key-pairs, and certificates that are then securely provisioned into your NXP MCU or MPU.

The tool supports the following flows:

• EdgeLock 2GO with device ID flow, where manufacturing facility retrievs secure objects from EdgeLock 2GO cloud server during the production process

• EdgeLock 2GO per product type flow, where OEM retrieves secure objects database from EdgeLock 2GO server and production in manufacturing facility can operate without online access to EdgeLock 2GO server

EdgeLock 2GO with device ID, high-level description

The figures below correspond to the sequence of actions indicated on Figure “EdgeLock 2GO trust provisioning workflow”.

Configuration process

1. OEM prepares a secure configuration and verifies it locally. Then the SEC Tool provides all secure objects, and the OEM uploads them via the EdgeLock 2GO web portal.

2. OEM send to manufacturing facility manufacturing package generated from SEC Tool.

Manufacturing process for EdgeLock 2GO with device ID

3. The tool fetches the processor UUID

4. The tool requests secure objects for the given UUID. The EdgeLock 2GO server validates UUID, generates secure objects, and encrypts them with EdgeLock 2GO root of trust. Secure objects are downloaded to the manufacturing machine.

5. Secure objects and EdgeLock 2GO provisioning firmware are loaded to the target processor. The firmware is invoked to install the secure objects into the target location. The application image is applied into the target boot memory.

EdgeLock 2GO trust provisioning workflow

EdgeLock 2GO per product type, high-level description

Configuration process

1. OEM prepares a secure configuration and verifies it locally. Then the SEC Tool provides all secure objects, and the OEM uploads them via the EdgeLock 2GO web portal.

2. OEM downloads the database of secure objects and provides the database and manufacturing package to the manufacturing facility.

Manufacturing process for EdgeLock 2GO per product type

3. The tool fetches secure objects from the database.

4. Secure objects and EdgeLock 2GO provisioning firmware are loaded to the target processor. The firmware is invoked to install the secure objects into the target location. The application image is applied into the target boot memory.

EdgeLock 2GO flow, step by step

To configure EdgeLock 2GO provisioning, do the following steps:

1. Turn on secure boot mode and verify that the application works properly.

2. On the EdgeLock 2GO server, create the device group for the product and create an API key. For details, see EdgeLock 2GO Configuration via web portal.

3. In the main menu > Target > Trust Provisioning Mode, select EdgeLock 2GO. Select either EdgeLock 2GO with device ID or EdgeLock 2GO per product type. Fill the EdgeLock 2GO parameters and Test connection to the server.

4. Install the GnuPG Tool and take advantage of the prepared encryption script.

   OS-specific notes:

   • Windows: Kleopatra for Windows is recommended: Kleopatra for Windows (GPG4Win). The encryption can also be done both manually using “Kleopatra GUI”. See EdgeLock 2GO Quick Start Guide (document AN13255 on EdgeLock 2GO server) or using the way described above (GnuPG utilities are installed with gpg4win).

   • Ubuntu: use the gpg package in the Ubuntu repositories.

   • macOS: gnupg available in the brew package system is a recommended option; GnuPG for OS X should also work (see GnuPG downloads )

5. Steps needed to enable the GPG encryption in the build script:

   • The encryption is done in the el2go/encrypt_el2go_files.* script generated into the workspace. Use the Update files button on the Build page to update the script.

   • Import the EdgeLock 2GO public key for encryption, see the generated script for how to do it

   • Generate RSA key pair for signing - gpg –full-generate-key. Use 2048 or 4096 key size.

   • Set environment variables

     • EL2GO_GPG_PASSWORD - password for the generated key pair

     • EL2GO_GPG_SIGN_KEY - identify which key should be used for signing using key ID available by gpg–list-secret-keys. If the EL2GO_GPG_SIGN_KEY environment variable is defined, the encryption is invoked from the build script as a part of the build action.

6. Ensure that the development life cycle is selected in the main menu > Target > Life Cycle. For development purposes, the EdgeLock 2GO verification is supported with the open life cycle. This is not intended for production.

7. On the build page, click Build image to build the application. Ensure that there are no errors.

8. Open the <workspace>/el2go/publish subfolder and upload all secure assets into the EdgeLock 2GO server. Follow the instructions provided in EdgeLock 2GO Configuration via web portal.

   Note: Files for the EdgeLock 2GO server are also displayed on the build page. In the generated files, they are marked by the el2go cloud icon. The description is displayed in the tooltip.

9. For EdgeLock 2GO per product flow, follow Create database with secure objects for EdgeLock 2GO per product type.

10. Go to the Write page and run the Write operation.

11. If everything works as expected, set the deployment life cycle and repeat steps 7-9.

12. Create the manufacturing package. For details, see Create manufacturing package. For API key distribution, see API key to access EdgeLock 2GO server.

For processor-specific information, see Processor-specific workflows.

API key to access EdgeLock 2GO server

• For development, the API key must be specified in the Trust Provisioning Mode dialog.

• For EdgeLock 2GO per product type, the API key is not used in the manufacturing

• For EdgeLock 2GO with device ID, the API key is also needed for manufacturing:

  • For the manufacturing package, the API key can be specified optionally; if it is specified, it is recommended to encrypt the package with a password to protect the access.

  • If the API key is not specified in the manufacturing package, it can be specified in the manufacturing dialog or via the environment variable SEC_EL2GO_API_KEY.

  • For EdgeLock 2GO trust provisioning, the following access needs to be enabled for the manufacturing API key on the EdgeLock 2GO server:

    • View - View device groups

    • General - Register devices

    • Remote trust provisioning - View secure objects and their intermediate CAs

  • For EdgeLock 2GO WPC provisioning, the following access needs to be enabled for the manufacturing API key on the EdgeLock 2GO server:

    • View - View Qi related data

    • Manage - Assign and unassign Qi templates to Device Groups and query jobs for batch processing

EdgeLock 2GO configuration via web portal

EdgeLock 2GO web portal URL: EdgeLock 2GO web portal

The following Application Note provides detailed information: EdgeLock 2GO Provisioning via Secure Provisioning Tool (SEC) for MCUs (document AN14624).

How to create device group

• Devices > New Device Group

• Assign any name

• Hardware family type: MPU and MCU

• Hardware option: product name

• Hardware type and product name: select a processor by name

How to create RKTH secure object

• Secure Objects > New Secure Object

• Select type: OEM FW Authentication Key Hash

• Assign any name

• Provide a binary file: <upload the file>

• Usage policies: add a custom policy. Select the Open or Closed/Locked policy. Open is used for development and testing, Closed and Closed/Locked are used for production. The policy is to be aligned with the life cycle selected in the tool. For details, see processor-specific recommendations.

How to create CUST-MK-SK secure object

• Secure Objects > New Secure Object

• Select type: OEM FW Decryption Key

• Assign any name

• Provide the key material (.asc): provide a signed and encrypted key. It is generated by a SEC Tool via GnuPG.

• Provide the public key to use it for verifying the signature of the encrypted key. (.asc): your public key

• Usage policies: same as RKTH; the policy must be the same for all secure objects used in one device group.

Other secure object

See processor-specific information in Processor-specific workflows.

Create database with secure objects for EdgeLock 2GO per product type

There are two types of the databases:

• static database: does not contain any processor specific secure objects

• dynamic database: contains processor-specific certificates

To create a database of secure objects for “offline” provisioning (EdgeLock 2GO per product type), follow these steps:

1. Open main menu > Targets > Trust Provisioning Mode… and ensure EdgeLock 2GO per product type is selected.

2. In Per Product Database panel specify:

   • number of devices per database

   • number of databases to be generated

   These parameters will be used for dynamic database only. For a static database, the parameters will be ignored.

3. Click the button to start generation. Mind the generation of dynamic databases may take significant time (typically several hours) and there is a displayed progress bar with the estimated time. Do not close the window until the database is generated.

4. Click the Download button to download the databases from the server.

For the write operation, the database name is hard-coded to <workspace>/trust_provisioning/el2go_product_batch.db. For manufacturing operation, the database name and location can be selected in the manufacturing dialog.

Databases are not included in the manufacturing package and are expected to be delivered separately.

Merge Images Tool workflow

This section describes merging two separate images into one single image. The reason for merging might be signing both images together during the build process. This section is written for MCUXpresso IDE with the Trust zone hello world SDK example, which contains two separate projects _hello_world_s and _hello_worlds_ns linked together. It is necessary to remove the link between the projects (MCUXpresso IDE) to generate two separated images instead of one image created during the build process by merging both projects together. As an example processor the MIMXRT595 is used. For other processors the workflow is the same, except of the start addresses.

Building the TrustZone example projects for merge

1. Remove linking between both projects by selecting the non-secured project _hello_world_ns go to Project > Properties > Project References and unchecking the _hello_world_s from the references.

2. Build both projects without any modifications

3. This example uses .s19 files so the final .axf files need to be converted. To do so, go to the Debug folder for both projects, right-click the generated _hello_world_*.axf file, and choose Binary Utilities > Create S-Record.

Merging two images into one

1. Open the Merge Tool by selecting main menu > Tools > Merge Tool.

2. Select _hello_world_s.s19. The target address will be automatically set to 0x18001000 (secured memory area)

3. For MIMXRT595 processors, only the non-secured address can be written by the user. The given address of the first image is in the secured memory map. Change the target address of the first image to 0x08001000 (non-secured memory area)

4. Select _hello_world_ns.s19. The target address will be automatically set to 0x08100000 (non-secured memory area)

5. Check the Apply the merged images as the Source executable image on Build image view checkbox

6. Leave the rest as it is and press the OK button

7. Check that the image is automatically applied as a Source executable image and its start address is updated as well

Signing merged image

To sign and build the merged image, see the Booting signed image using shadow registers section, but use the merged image as a Source executable image instead.

Custom USB VID and PID devices workflow

If you have a device with custom VID&PID, it is possible to select the custom VID&PID in the main menu > Target > Connection. Selected VID&PID is used for the whole write operation. Write script does not support a change of VID&PID during its execution. It is recommended to change VID&PID prior to the write operation (for example, using PFR configuration or OTP configuration in Advanced mode), reset the processor and then start the write operation with custom VID&PID.

For manufacturing operation, custom VID&PID must be selected in the Connection configuration during the creation of the manufacturing package. With such configuration, the manufacturing operation accepts both default and custom VID&PID.