GBL3 Commands#

GBL3 File Creation#

Creates a Gecko Bootloader version 3 (GBL3) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL3 file using a keyfile generated by the util genkey command.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <filename> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create app.gbl.encrypted --app example.s37 --encrypt key.txt

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

GBL3 File Creation with Compression#

Creates a compressed Gecko Bootloader version 3 (GBL3) file from an application image and writes the output to the specified filename. Can optionally encrypt the GBL3 file using a keyfile generated by the util genkey command.

The currently supported compression algorithms are lz4 and lzma. The bootloader on the targeted devices must support decompressing the selected compression type.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <filename> --compress <compression algorithm> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create app.gbl --app example.s37 --compress lz4

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Compressing using lz4...
Writing GBL file app.gbl...
DONE

Create a GBL3 File for Bootloader Upgrade#

Creates a Gecko Bootloader version 3 (GBL3) file from a bootloader image and writes the output to the specified bootloader image filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --bootloader <bootloader image file> [--encrypt <keyfile>]

Command Line Input Example

$ commander gbl3 create bootloader.gbl --bootloader bootloader.s37

Command Line Output Example

Initializing GBL file...
Adding bootloader to GBL...
Writing GBL file bootloader.gbl...
DONE

Creating a GBL3 File for Secure Engine Upgrade#

The Secure Engine on EFR32xG21 devices can be upgraded using a Secure Engine upgrade binary provided by Silicon Labs. This command creates a GBL3 file containing a Secure Engine upgrade file and writes the output to the specified GBL3 filename. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --app <application image>

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --seupgrade se_fw_upgrade_app_1v0p0.seu --app myapp.s37

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Engine upgrade image to GBL...
Writing GBL file se-upgrade.gbl...
DONE

Creating a Signed and Encrypted GBL3 Upgrade Image File from an Application#

Creates a GBL3 file, signs the GBL3 file, and encrypts the GBL3 file. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <app image file> --sign <signing key> [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl3 create example.gbl --app example.s37 --sign ecdsakey --encrypt aeskey

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Signing GBL...
Image SHA256: 74b126bdbad680470487e32d7d7b3ec7f12b15d9988e028b26c2dd54f81dcfb7
R = 055A23A44CDEDA34506EE72F4530FE174CFC85F48933C1379C1360F8BC1AA75B
S = 1C9EF6C3F5CAA0D5B92ECC2569E4A8251F8561DAF52DE54D3E59591A5001B9EA
Writing GBL file example.gbl...
DONE

Preparing a GBL3 Upgrade File for Use with a Hardware Security Module#

It is often not desirable to keep the private keys used for signing/encrypting locally on the computer that creates the GBL3 images. A good way to increase security is to use a Hardware Security Module (HSM) to encrypt the GBL3 data and generate the actual signatures.

Simplicity Commander supports both external encryption and external signing of GBL3 files. To enable external encryption, specify the --extencrypt option when running the gbl3 create command. To enable external signing, use the --extsign option. You can use the options together to create a GBL3 file that is encrypted and signed externally. The following sections describe a generic workflow for enabling external encryption, external signing, or both.

  1. Prepare the GBL3 file for external encryption and/or signing using Simplicity Commander.

  2. If external encryption is used:

    a. Encrypt the relevant data using an HSM.

    b. Use Simplicity Commander to assemble the encrypted data into an encrypted GBL3 file.

  3. If external signing is used:

    a. Create an Elliptic Curve Digital Signature Algorithm (ECDSA) signature of the relevant data using an HSM.

    b. Use Simplicity Commander to sign the partial GBL3 file using the signature from the HSM, completing the GBL3 file.

Step 1 is described in Preparing a GBL3 File for External Encryption and Preparing a GBL3 File for External Signing. Steps 2a and 3a are specific to the HSM you are using. Step 2b is described in Completing an Encrypted GBL3 Using a Hardware Security Module, and step 3b is described in Completing a Signed GBL3 File Using a Hardware Security Module. A walkthrough of the process of both externally encrypting and externally signing is provided in Creating a Signed and Encrypted GBL3 File Using a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Preparing a GBL3 File for External Encryption#

To prepare a GBL3 for external encryption, use the gbl3 create command with the --extencrypt option. This command creates a partial GBL3 file that an external party can encrypt. The data to be encrypted is written to the <app image file>.extencrypt file. It also creates intermediate files named <app image file>.extencrypt.header and <app image file>.extencrypt.footer. Do not modify or delete these files. They are required to construct the final encrypted GBL file when using the gbl3 encrypt command, as is described in Completing an Encrypted GBL3 Using a Hardware Security Module.

Note: When encrypting the encryption-ready file, the name of the resulting encrypted file must be <app image file>.extencrypt.encrypted.

Command Line Syntax

$ commander gbl3 create <output partial GBL3 file for external encryption> --app <app image file> --extencrypt

Command Line Input Example

$ commander gbl3 create example.gbl --app example.s37 --extencrypt

Command Line Output Example

Parsing file example.s37...
Initializing GBL3 file...
Adding application to GBL...
Preparing GBL for external encryption...
Encryption-ready file written to: 'example.gbl.extencrypt'.
Intermediate files written to: 'example.gbl.extencrypt.header' and 'example.gbl.extencrypt.footer'.
NOTE: Only 'example.gbl.extencrypt' should be encrypted by the external party. The name of the encrypted file must be 'example.gbl.extencrypt.encrypted'!
      The intermediate files are used to construct the final encrypted GBL file using the 'gbl3 encrypt' command.
DONE

Preparing a GBL3 File for External Signing#

To prepare a GBL3 for external signing, use the gbl3 create command with the --extsign option. This command creates a partial GBL3 file named <app image file>.extsign that an external party can sign. To complete the GBL3 file, append the generated signature to the partial GBL3 file by using the gbl3 sign command, as described in Completing a Signed GBL3 File Using a Hardware Security Module.

Command Line Syntax

$ commander gbl3 create <output partial GBL3 file for external signing> --app <app image file> --extsign [--encrypt <encryption key>]

Command Line Input Example

$ commander gbl3 create example.gbl.extsign --app example.s37 --extsign

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Preparing GBL for external signing...
Writing GBL file example.gbl.extsign...
DONE

Completing an Encrypted GBL3 Using a Hardware Security Module#

Completes an encrypted GBL3 file from the intermediate files created by the gbl3 create command with the --extencrypt option and the encrypted data file from an HSM.

Note: The nonce must be a 16-byte hexadecimal string in the format 02<12-byte random number>000001. The HSM generates the random number component. Use the same nonce that was used to encrypt the GBL3 body ciphertext.

Command Line Syntax

$ commander gbl3 encrypt <GBL3 body ciphertext> --nonce <nonce> --outfile <encrypted GBL3 file>

Command Line Input Example

$ commander gbl3 encrypt example.gbl.extencrypt.encrypted --nonce 0200112233445566778899aabb000001 --outfile example.gbl

Command Line Output Example

Reading header section from file example.gbl.extencrypt.header...
Reading GBL body cipher text from file example.gbl.extencrypt.encrypted...
Reading footer section from file example.gbl.extencrypt.footer...
Parsing header section...
Preparing encryption initialization tag...
Writing complete GBL file to example.gbl...
DONE

Completing a Signed GBL3 File Using a Hardware Security Module#

Completes a signed GBL3 file from a partial GBL3 file and an ECDSA signature file in Distinguished Encoding Rules (DER) format generated as described in Preparing a GBL3 Upgrade File for Use with a Hardware Security Module. For more information, see UG266: Silicon Labs Gecko Bootloader User's Guide for GSDK 3.x and Lower or UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Silicon Labs recommends that you use the --verify option with the public key corresponding to the private key used by the HSM to ensure the integrity of the generated GBL3 file.

Command Line Syntax

$ commander gbl3 sign <partial GBL3 file for external signing> --signature <signature from HSM> [--verify <public key file>] --outfile <signed GBL3 file>

Command Line Input Example

$ commander gbl3 sign example.gbl.extsign --signature example.gbl.extsign.sig --verify ecdsakey.pub --outfile example-signed.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing signature to GBL...
Verifying GBL...
Image SHA256: 4d7325b09ade0ea272eb9895096c8137b18451f694a4eca9a5782f5c08dea03a
Q_X: 60BA97B850291456217C2149061AA344B32BBFB69A91A94BBF2F274744308D39
Q_Y: 41927DA5DB171E1C723C6B59C2BC88EDFF5A37014B0473775BA5B15921686ECA
R = 2E73426A1052E12BFFFEFBA9BE2AA50CEA815B630C3CA878494EEF26088A5673
S = C218596DB9958AB30924B516953D2E5107644963B4CA128072AC965BE5C2992D
Writing GBL file example-signed.gbl...
DONE

Creating a Signed and Encrypted GBL3 File Using a Hardware Security Module#

To create a GBL3 file that is both signed and encrypted by using a HSM, split the process into multiple steps, as described in the following sections.

Creating the partial GBL3 file for external encryption and signing#

To create a partial GBL3 file for external encryption and signing, use the --extencrypt and --extsign options with the gbl3 create command. Doing so creates a partial GBL3 file that is ready to be encrypted and then signed by an external party.

Command Line Syntax

$ commander gbl3 create <output file> --app <app image file> --extencrypt --extsign

Command Line Input Example

$ commander gbl3 create example.gbl --app example.s37 --extencrypt --extsign

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Preparing GBL for external signing...
Preparing GBL for external encryption...
Encryption-ready file written to: 'example.gbl.extsign.extencrypt'.
Intermediate files written to: 'example.gbl.extsign.extencrypt.header' and 'example.gbl.extsign.extencrypt.footer'.
NOTE: Only 'example.gbl.extsign.extencrypt' should be encrypted by the external party. The name of the encrypted file must be 'example.gbl.extsign.extencrypt.encrypted'!
      The intermediate files are used to construct the final encrypted GBL file using the 'gbl3 encrypt' command.
DONE

Encrypting the GBL3 Data Using a Hardware Security Module#

The relevant data is encrypted by using an external HSM tool. In the next step, Commander requires the nonce that was used to encrypt the data. The nonce is a 16-byte hexadecimal value in the format 02<12-byte random number>000001, where the random number is generated by the HSM.

Applying the external encryption to the partial GBL3 file#

To apply external encryption to the partial GBL3 file, run the gbl3 encrypt command.

After this step, the GBL3 file is still not a valid GBL file. The file is complete only after you calculate the signature and append it to the GBL file.

See Completing an Encrypted GBL3 Using a Hardware Security Module for more information.

Command Line Syntax

$ commander gbl3 encrypt <partial GBL3 file for external encryption> --nonce <nonce> --outfile <output encrypted partial GBL3 file>

Command Line Input Example

$ commander gbl3 encrypt example.gbl.extsign.extencrypt.encrypted --nonce 0200112233445566778899aabb000001 --outfile example.gbl.extsign

Command Line Output Example

Reading header section from file example.gbl.extsign.extencrypt.header...
Reading GBL body cipher text from file example.gbl.extsign.extencrypt.encrypted...
Reading footer section from file example.gbl.extsign.extencrypt.footer...
Parsing header section...
Preparing encryption initialization tag...
Writing encrypted GBL file to example.gbl.extsign...
WARNING: This file is not a valid GBL file until signing has been completed using the 'gbl sign' command!
DONE

Signing the GBL3 File Using a Hardware Security Module#

Sign the encrypted GBL3 file by using the external HSM tool. The <filename>.extsign file contains the data to be signed. Write the resulting signature to a file, which will be used in the next step.

Applying the external signature to the encrypted partial GBL3 file#

To apply the external signature to the encrypted partial GBL3 file, use the gbl3 sign command. After this step, the GBL3 file is complete and can be used.

See Completing a Signed GBL3 File Using a Hardware Security Module for more information.

Command Line Syntax

$ commander gbl3 sign <encrypted partial GBL3 file> --signature <signature from HSM> [--verify <public key file>] --outfile <output signed GBL3 file>

Command Line Input Example

$ commander gbl3 sign example.gbl.extsign --signature example.gbl.extsign.sig --outfile example.gbl

Command Line Output Example

Reading GBL data from example.gbl.extsign...
Parsing signature file example.gbl.extsign.sig...
R = C1D6EA30B0029DF7E07450FA72E1694CB14D702DC4F87CD99E7CB188C112F672
S = 44ED2C8443811675BCB0268A944799ED1D692D2EDEBD7123F902345515713ABC
Writing signature to GBL...
Writing GBL file example.gbl...
DONE

Creating a Signed GBL File Using an Intermediate Certificate#

Creates a GBL file with a signed intermediate certificate and signs the GBL file using the private key that corresponds to the public key in the certificate.

A suitable certificate can be generated and signed using the util gencert command - see Generate Certificate for details.

Note: To use GBL files with intermediate certificates the bootloader must be configured to:

  • Use certificate-based signing.

  • Include an intermediate certificate to authenticate the certificate embedded in the GBL file.

Command Line Syntax

$ commander gbl create <gblfile> --app <app image file> --sign <signing key> --certificate <signed certificate file>

Command Line Input Example

$ commander gbl create example.gbl --app example.s37 --sign ecdsakey --certificate signed_cert.bin

Command Line Output Example

Parsing file example.s37...
Initializing GBL file...
Adding application to GBL...
Adding certificate to GBL...
Signing GBL...
Image SHA256: 6b5c6b5b4236c31931ce68d98abc65dfdf9a663ce4bd5a96d747811ea32e003a
R = 04B146AF5757307108CF09D0E2E34E99E1585BD80E6F121B5E643A251BEC4C0C
S = FEC5F26782A05508183486F6EDD2D8AA7F20A527066715243AB4AD9C7DB2BD2E
Writing GBL file example.gbl...
DONE

GBL File Parsing#

Parses a Gecko Bootloader version 3 (GBL3) file and writes the application image to the specified filename. Optionally decrypts an encrypted GBL3 file. The keyfile must be the same as was used for encrypting the encrypted GBL3 file.

Command Line Syntax

$ commander gbl3 parse <gbl filename> --app < filename> [--decrypt <key filename>]

Command Line Input Example

$ commander gbl3 parse example.gbl.encrypted --app app.s37 --decrypt key.txt

Command Line Output Example

Reading GBL data...
Decrypting GBL...
Reading application...
Writing application to app.s37...
DONE

GBL3 Key Generation#

This command is deprecated. See Key Generation for more information about key generation.

Generating a Signing Key#

This command is deprecated. See Generating a Signing Key for more information about generating a signing key.

Generate a Signing Key Using a Hardware Security Module#

This command is deprecated. See Key to Token for more information about generating a signing key using a hardware security module.

Create a GBL3 File from an ELF File#

Creates a Gecko Bootloader version 3 (GBL3) file from an Executable and Linkable Format (ELF) file and writes the output to the specified file. If neither the --include-section nor the --exclude-section option is used, Simplicity Commander will include all sections that appear to be part of the application.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <application image file> [--include-section <section> --exclude-section <section>]

Command Line Input Example

$ commander gbl3 create app.gbl --app app.out --exclude-section text_apploader --exclude-section text_signature

Creates a GBL3 file containing an ELF application, excluding the text_apploader and text_signature sections from the application.

Command Line Output Example

Parsing file app.out...
Initializing GBL file...
Adding application to GBL...
Encrypting GBL...
Writing GBL file app.gbl.encrypted...
DONE

Create an Encrypted GBL3 File with an Unencrypted Secure Engine Upgrade File#

Creates an encrypted Gecko Bootloader version 3 (GBL3) file containing an unencrypted Secure Engine upgrade file and then writes the output to the specified GBL3 file.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --seunencrypted --app <application image> --encrypt <AES key file>

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --seupgrade sl_fw.seu --seunencrypted --app myapp.s37 --encrypt aes-key.txt

Creates an encrypted GBL3 file with a Secure Engine upgrade file outside the encrypted area of the file.

Command Line Output Example

Parsing file myapp.s37...
Initializing GBL file...
Adding application to GBL...
Adding Secure Engine upgrade image to GBL...
Encrypting GBL...
Writing GBL file se-upgrade.gbl...
DONE

Create a GBL3 File with Version Dependencies#

Any version dependencies between application, bootloader, and Secure Engine upgrade files in a Gecko Bootloader version 3 (GBL3) file may be resolved using the --dep-app, --dep-boot, and --dep-se options.

Command Line Syntax

$ commander gbl3 create <gblfile> --seupgrade <SE upgrade file> --app <application image> --dep-app <statement:version> --dep-se <statement:version> --dep-boot <statement:version>

Dependency Statement

The dependency statement may be one of the following:

Simplicity Commander Input

Statement

g

Greater than

geq

Greater than or equal

eq

Equal

leq

Less than or equal

l

Less than

The --dep-app option takes an uint32 as version input, while the --dep-se and --dep-boot options take the version input in the format major.minor.patch.

Command Line Input Example

$ commander gbl3 create se-upgrade.gbl --app myapp.s37 --seupgrade se_fw.seu --bootloader my-bootloader.s37 --dep-app geq:0x01020002 --dep-boot l:0.5.7 --dep-se g:1.2.3

Creates a GBL3 where the application version must be greater than or equal to version 0x01020002, bootloader version must be less than version 0.5.7, and Secure Engine upgrade version must be greater than version 1.2.3.

Command Line Output Example

Parsing file myapp.s37
Initializing GBL file...
Setting version dependency of Application to >= 0x00120002
Setting version dependency of Bootloader to < 0x00050007
Setting version dependency of SE upgrade image to > 0x00010203
Adding version dependencies to GBL...
Adding application to GBL...
Adding bootloader to GBL...
Adding Secure Engine upgrade image to GBL...
Writing GBL file se-upgrade.gbl
DONE

Create a Delta GBL3 File#

Creates a Gecko Bootloader version 3 (GBL3) file which contains the difference between two specific application versions for minimal upgrade file size. For more information on delta updates, see UG489: Silicon Labs Gecko Bootloader User's Guide for GSDK 4.0 and Higher.

Command Line Syntax

$ commander gbl3 create <gblfile> --app <new application image file>  --delta-app <old application image file> [--compress lzma|lz4]

Symbol Information

The calculation of the delta between two application versions is significantly improved by having access to symbol information. When given files without symbol information (typically srec or hex files), Simplicity Commander will try to find ELF files with the same name in the same directory, and extract the symbol information from the ELF file. For example, if Commander is given --app release/1.3.0/app.s37 --delta-app release/1.2.0/app.s37, it will try to find app.axf, app.out, or app.elf in both of the release/1.3.0/ and release/1.2.0/ folders. Symbol information for both versions is required.

Secure Boot

If using secure boot, please ensure that both the old and the new application file is signed. The signature is then restored as part of applying the delta patch.

Additionally, delta GBL3 files may be signed and/or encrypted just like regular GBL3 files. See Creating a Signed and Encrypted GBL3 Upgrade Image File from an Application for details.

Version Dependency

Simplicity Commander will automatically extract the version of the old application and add a version dependency tag to the GBL3. See Create a GBL3 File with Version Dependencies for details on version dependencies. If a specific version is provided with the --dep-app option, this is used instead of the version found in the application image.

Compression

Delta GBL3 files can be compressed using LZMA or LZ4 compression. See GBL3 File Creation with Compression for details.

Command Line Input Example

$ commander gbl3 create delta-upgrade.gbl --app app_1.3.0.s37 --delta-app app_1.2.3.s37

Command Line Output Example

Parsing file app_1.3.0.s37...
Initializing GBL file...
Parsing file app_1.2.3.s37...
Filling with 0xFF from 0x0800631c to 0x08006320
Automatically adding dependency to the detected version of "--delta-app"...
Setting version dependency of Application to = 0x00010203
Writing GBL file delta-upgrade.gbl...
DONE