GBL4 Commands#

Creates and parses Gecko Bootloader (GBL) version 4 files for devices that support GBL4. GBL4 files are used to upgrade the bootloader, application, and/or SE firmware of supported devices.

GBL4 File Creation With Config File#

There are two ways to create a GBL4 file.

Note: When the --config option is used in the create command, all other command line options defining the output file are ignored.

A template configuration file can be created using the gbl4 createconfig command.

GBL4 Config File Format#

The configuration file is structured into several sections - manifest, se_upgrade, and updates. All sections are optional, but at least either one update file or an SE upgrade must be provided.

Manifest#

The manifest section sets parameters which apply to the GBL file as a whole.

Product ID#

The product ID is a 16 byte long identifier. It is extracted from the application image, if available. If the product ID is present in both the application and the configuration file, the entry in the configuration file is used. If not provided, the default is zero.

Bundle Version#

The bundle version is the version of the upgrade bundle. Lower versions will be rejected by the bootloader. If not provided, the default is zero.

Minimum Version#

The minimum version is the minimum acceptable previous bundle version to which this update can be applied. This may be needed if DFU is only a partial update.

Certificate and Signature#

The GBL file can be signed with a private key, optionally using a delegate certificate authorizing this key pair. See Generate Certificate and Generating a Signing Key for details.

SE Upgrade#

The se_upgrade section is used to include a Secure Engine (SE) upgrade file in seuv2 format.

Updates#

The updates section provides a list of one or more updates to be included. For example, an update can be a bootloader or an application image.

Data#

Each update must specify an update file in one of the supported formats: s37, hex, or elf.

Type, Capabilities, Version#

The application type, capabilities, and version are by default extracted from the ApplicationProperties_t struct. These values can be overridden by the config file. If not provided at all, they are set to zero by default.

Compression#

Each update can optionally be compressed. Supported algorithms are lz4 and lzma.

Encryption#

Each update can be encrypted with a symmetric key using the aes-ctr-128 algorithm. Keys can be generated using the util keygen command.

Block Size#

A list of hashes of the update data can be added to the GBL file. This can be useful for streaming updates, to allow authenticating the update on the fly. To use this feature, a block size must be set. The block size sets the size of a block of data for which a hash will be generated.

Command Line Usage#

Command Line Syntax

$ commander gbl4 create <gblfile> --config <configfile> --device <device>

Command Line Input Example

$ commander gbl4 create example.gbl --config gbl_config.yaml

Command Line Output Example

Initializing GBLV4 file...
Reading SE upgrade file se_upgrade.seu
Parsing file example.s37...
Writing example.gbl...
Image SHA256: cd74050714df55752d8612474239c12941b19eaa67baa245342c80373abf144b
R = 7A3C8E2FF71DB6AE5351DB565967A16821BF5AC40483432E6630BCCCBC62E17C
S = 517ED3971A49A52E673446D11A187DD1B0A0331235CC52AE6E8393CAF711D313
DONE

GBL4 File Creation with Command Line Options#

GBL4 files can also be created using command line options. The command line options largely correspond to the options available in GBL4 Config File Format, with the following limitations/simplifications:

  • The --compress and --encrypt options apply to all updates.

  • Application type, capabilities, and version cannot be set manually.

  • Block hashes are not supported.

Command Line Syntax

$ commander gbl4 create <gblfile> [--data <filename>] [--seupgrade <filename>] [--compress <compression algorithm>] [--encrypt <keyfile>] [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create app.gbl --data example.s37 --compress lz4 --encrypt encryption_key.pem --sign signing_key.pem

Command Line Output Example

Initializing GBLV4 file...
Parsing file example.s37...
Writing GBL file app.gbl...
Image SHA256: 5ba67b656103a3539f0f3802a4398f0babb3ff182fe9890962e578052571d4ea
R = 6845219257E660918B7BAE26FFF3DC7BBE8150DA3281CE8881B7088E9E973CE6
S = B8C5B58987FA3C7E44444B7C43096A41F48D245ED148C4E0863F0F91013381E1
DONE

Preparing a GBL4 File for Use with a Hardware Security Module#

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

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

  2. If external encryption is used:

    a. Encrypt the relevant data blobs using the external HSM tool.

    b. Use Simplicity Commander to assemble the encrypted data into an encrypted GBL4 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 GBL4 file using the signature from the HSM, completing the GBL4 file.

Step 1 is described in Preparing a GBL4 File for External Encryption and Preparing a GBL4 File for External Signing. Steps 2a and 3a are specific to the HSM you are using. Step 2b is described in Completing an Externally Encrypted GBL4 File, and step 3b is described in Completing an Externally Signed GBL4 File. A walkthrough of the process of both externally encrypting and externally signing is provided in Creating a Signed and Encrypted GBL4 File Using a Hardware Security Module.

Preparing a GBL4 File for External Encryption#

To prepare a GBL4 file for external encryption, use the gbl4 create command with the --extencrypt option. This command creates several intermediate files, depending on the number of updates provided. The base GBL4 file is written to <gblfile>.unencrypted. The GBL4 data to be encrypted is written to files named <gblfile>.blob_*.data, while the intermediate files are written to files named <gblfile>.blob_*.info.

Name the encrypted data blobs <gblfile>.blob_*.data.encrypted, preserving the index for each memory section. Encrypt each data blob by using the external HSM tool.

Note: Do not modify or delete the intermediate files. These files are required to construct the final encrypted GBL file when you use the gbl4 encrypt command.

Command Line Syntax

$ commander gbl4 create <gblfile> --data <data file> --extencrypt

Command Line Input Example

$ commander gbl4 create example.gbl --data example.s37 --extencrypt

Command Line Output Example

Initializing GBLV4 file...
Parsing file example.s37...
Wrote GBL root and manifest data to example.gbl.unencrypted
NOTE: This file should be passed to the 'gbl4 encrypt' command after encryption is completed.

Wrote 1 memory section info to:
  example.gbl.blob_0.info
NOTE: The filenames for the memory section info files must not be changed;
      these files will be used when assembling the final, encrypted GBL file.

Wrote 1 unencrypted memory section blob to:
  example.gbl.blob_0.data
NOTE: Each of these data blobs are to be encrypted using the external tool.
      The resulting encrypted data blobs must be named '<appFilename>.gbl.blob_<index>.data.encrypted',
      maintaining the indices of each memory section.

DONE

Preparing a GBL4 File for External Signing#

To prepare a GBL4 file for external signing, use the gbl4 create command with the --extsign option. This command creates a partial GBL4 file that an external party can sign. The base GBL4 file is written to a file named <gblfile>.unsigned, while the data to be signed is written to a file named <gblfile>.manifest. Append The generated signature to the partial GBL4 file by using the gbl4 sign command.

Command Line Syntax

$ commander gbl4 create <gblfile> --data <data file> --extsign

Command Line Input Example

$ commander gbl4 create example.gbl --data example.s37 --extsign

Command Line Output Example

Initializing GBLV4 file...
Parsing file example.s37...
Writing manifest data (for external signing) to example.gbl.manifest
Writing unsigned GBL file (for later use in 'gbl4 sign') to example.gbl.unsigned...
After computing the signature of example.gbl.manifest, assemble the GBL4 using:
commander gbl4 sign example.gbl.unsigned --outfile example.gbl --signature <signature.der>
DONE

Completing an Externally Encrypted GBL4 File#

To finalize an externally encrypted GBL4 file, use the gbl4 encrypt command. Provide a nonce file that contains one nonce per memory section. The nonce file must be a text file, with each nonce on a separate line, using the format 02<12-byte random number>000001, where the random number is generated by the HSM. Each line must correspond to the index of the associated memory section, and the number of nonces must match the number of encrypted memory sections.

Command Line Syntax

$ commander gbl4 encrypt <gblfile>.unencrypted --outfile <gblfile> --nonce <nonces file>

Command Line Input Example

$ commander gbl4 encrypt example.gbl.unencrypted --outfile example.gbl --nonce nonces.txt

Command Line Output Example

Writing encrypted GBL file example.gbl...
DONE

Completing an Externally Signed GBL4 File#

To finalize an externally signed GBL4 file, use the gbl4 sign command. The signature file must contain a DER-formatted ECDSA signature generated by the HSM.

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 GBL4 file.

Command Line Syntax

$ commander gbl4 sign <gblfile>.unsigned --outfile <gblfile> --signature <signature file> [--verify <public key file>]

Command Line Input Example

$ commander gbl4 sign example.gbl.unsigned --outfile example.gbl --signature signature.der --verify public_key.pem

Command Line Output Example

Parsing signature file signature.der...
R = 8C5AE7958205C9EBB4252D8CE5CE8F8132CC1B7E48F24F2494276A955D916C35
S = 2974CA4743D29BB36B0819098EE16FDBD8475F12960DBF6256D89F35D9F8D5FA
Verifying GBL...
Successfully verified GBL signature
Writing GBL file example.gbl...
DONE

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

To create a GBL4 file that is both signed and encrypted using a Hardware Security Module (HSM), split the process into multiple steps, as described in the following sections.

Preparing the GBL4 File for External Encryption and Signing#

To prepare a GBL4 file for both external encryption and external signing, use the --extencryptand --extsign options with the 'gbl4 create' command. Doing so creates a partial GBL4 file that is ready to be encrypted and then signed by an external party.

Command Line Syntax

$ commander gbl4 create <gblfile> --data <data file> --extencrypt --extsign

Command Line Input Example

$ commander gbl4 create example.gbl --data example.s37 --extencrypt --extsign

Command Line Output Example

Initializing GBLV4 file...
Parsing file example.s37...
Wrote GBL root and manifest data to example.gbl.unencrypted
NOTE: This file should be passed to the 'gbl4 encrypt' command after encryption is completed.

Wrote 1 memory section info to:
  example.gbl.blob_0.info
NOTE: The filenames for the memory section info files must not be changed;
      these files will be used when assembling the final, encrypted GBL file.

Wrote 1 unencrypted memory section blob to:
  example.gbl.blob_0.data
NOTE: Each of these data blobs are to be encrypted using the external tool.
      The resulting encrypted data blobs must be named '<appFilename>.gbl.blob_<index>.data.encrypted',
      maintaining the indices of each memory section.

DONE

Encrypting the GBL4 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 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. Each encrypted data blob can use a different nonce. Write the nonces to a file, which is used in the next step.

The encrypted data blobs must be named <gblfile>.blob_*.data.encrypted, maintaining the original indices of each data blob.

Applying the external encryption to the partial GBL4 file#

To apply the external encryption to the partial GBL4 file, use the gbl4 encrypt command. After this step, the GBL4 file is still not a valid GBL file. The file becomes complete only after you calculate the signature and append it to the GBL file. See Completing an Externally Encrypted GBL4 File for more information.

Command Line Syntax

$ commander gbl4 encrypt <partial GBL4 file for external encryption> --nonce <nonce file> --outfile <output encrypted partial GBL4 file>

Command Line Input Example

$ commander gbl4 encrypt example.gbl.unencrypted --nonce nonces.txt --outfile example.gbl

Command Line Output Example

Writing manifest data (for external signing) to example.gbl.manifest
After computing the signature of example.gbl.manifest, assemble the GBL4 using:
commander gbl4 sign example.gbl.unsigned --outfile example.gbl --signature <signature.der>
DONE

Signing the GBL4 File Using a Hardware Security Module#

Sign the encrypted GBL4 file by using the external HSM tool. The <filename>.manifest file contains the data that should be signed. Write the resulting signature to a file that will be used in the next step.

Applying the external signature to the encrypted GBL4 file#

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

See Completing an Externally Signed GBL4 File for more information.

Command Line Syntax

$ commander gbl4 sign <encrypted GBL4 file> --signature <signature from HSM> --outfile <output signed GBL4 file> [--verify <public key file>]

Command Line Input Example

$ commander gbl4 sign example.gbl --signature signature.der --outfile example.gbl --verify public_key.pem

Command Line Output Example

Parsing signature file signature.der...
R = 6A0F82592EA11BA96DCFE0890C079924AE5EEAB1FB4B9C2F051AAF7F623CA7B1
S = 70C467A9C9DD232301112EB143541DE5FCA2223844A6325CA33D3194F0601985
Verifying GBL...
Successfully verified GBL signature
Writing GBL file example.gbl...
DONE

Create a GBL4 File for Bootloader Upgrade#

Creates a Gecko Bootloader (GBL) file from a bootloader image and writes the output to the specified bootloader image filename.

Command Line Syntax

$ commander gbl4 create <gblfile> --data <bootloader image file> [--compress <compression algorithm>] [--encrypt <keyfile>] [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create bootloader.gbl --data bootloader.s37 --productid 45879184758294571094581908385139 --compress lz4 --bundleversion 0x00000002 --minversion 0x0000001

Command Line Output Example

Initializing GBLV4 file...
Parsing file bootloader.s37...
Writing GBL file bootloader.gbl...
DONE

Creating a GBL File for Secure Engine Upgrade#

The Secure Engine can be upgraded using a Secure Engine upgrade binary provided by Silicon Labs. This command creates a GBL file containing a Secure Engine upgrade file and writes the output to the specified GBL filename.

Command Line Syntax

$ commander gbl4 create <gblfile> --seupgrade <SE upgrade file> [--bundleversion <version>] [--productid <product id>] [--minversion <version>] [--sign <keyfile>] [--certificate <certificate file>] [--device <device>]

Command Line Input Example

$ commander gbl4 create se-upgrade.gbl --seupgrade se_fw.seuv2

Command Line Output Example

Initializing GBLV4 file...
Reading SE upgrade file from se_fw.seuv2
Writing GBL file se-upgrade.gbl...
DONE

GBL4 Create Configuration File#

This command creates a default template configuration file for creating a GBL file. The configuration file is a YAML file that describes the GBL file to be created. See GBL4 Config File Format for details on the fields of the config file.

Command Line Syntax

$ commander gbl4 createconfig --outfile <configfile>

Command Line Input Example

$ commander gbl4 createconfig --outfile gbl_config.yaml

Command Line Output Example

Writing template configuration file gbl_config.yaml...
Please modify to your needs.
DONE

Below is an example of the default configuration file:

manifest:
  product_id: "[16 B ID] (default from app or 00000000000000000000000000000000)"
  bundle_version: "[version] (default 0x00000000)"
  min_version: "[version] (default 0x00000000)"
  certificate: "[path to file] (optional)"
  signing_key: "[path to file] (optional)"
se_upgrade:
  se_file: "[path to file] (optional)"
updates:
  - data: <path to file>
    app_type: "[uint32] (default from app or 0x00000000)"
    app_capabilities: "[uint32] (default from app or 0x00000000)"
    version: "[uint32] (default from app or 0x00000000)"
    compression_scheme: "[none | lz4 | lzma] (default none)"
    encryption_scheme: "[none | aes-ctr-128] (default none)"
    encryption_key: "[path to file] (optional)"
    block_size: "[size in bytes] (default 0/disabled)"

GBL4 File Information#

Parse a Gecko Bootloader (GBL) file and shows information about the file.

Command Line Syntax

$ commander gbl4 info <gbl filename>

Command Line Input Example

$ commander gbl4 info example.gbl

Command Line Output Example

GBL manifest info:
  GBL version:          4.0.0
  Encryption:           Enabled
  Compression:          Disabled
  Certificate:          Not used
  Signature type:       ECDSA-P256
  Product version:      00000000000000000000000000000000
  Bundle version:       0x00000000
  Min previous version: 0x00000000

Update info:
  Target address:            0x01008000
  Version:                   0x00000001
  Binary size:               43916 B
  Compression scheme:        None
  Encryption scheme:         AES-CTR-128
  Secure boot scheme:        Appinfo
  Signature block size:      0
  Number of blocks:          0

DONE