7.2. Update Package

SEMS Lite agent gets an update package from the update manager. The upgrade package contains package meta data header and set of APDUs(MulticastCommands) to be sent to the SE for update. It may optionally also contain host control commands (e.g. Reset the secure element).

Format of the update package:

../../_images/Package.jpg

NXP provides customer package meta data and Multicast commands in JSON file. NXP also provides generator tool to turn the JSON file to binary file and .c/.h files. Customer can decide which one to be used by update manager according to their platform. Update manager should create update package from these files. This chapter has provided examples for the use of generator. It also provides links to the demos which will use the generated files to create update package.

7.2.1. Package Meta Data

Package meta data includes information such as version and memory requirement. These information will help SEMS Lite agent to preprocess package before loading APDU commands to SE.

  • MulticastPackageFormatVersion: Version information of this json Format for MulticastPackages.

  • TargetEntityID: Entity ID, 16bytes long Binary Coded Decimal, of the target device where this MulticastPackage is intended to be executed on. It is an identifier of the key-set of the Multicast Applet Loader.

  • Target12nc: Target 12nc is a 12 digit numerical code identifying the target device where this MulticastPackage is intended to be executed on, as known to customers and used on EdgeLock2Go to identify device types.

  • requiredFreeBytesNonVolatileMemory: Minimum required free Non Volatile memory in bytes that have to be available on the target device before execution of this MulticastPackage.

  • requiredFreeBytesTransientMemory: Minimum required free transient (RAM) memory in bytes that have to be available on the target device before execution of this MulticastPackage.

  • MulticastPackageName: Giving a descriptive name to the complete Multicast Package.

  • MulticastPackageVersion: Version information of this MulticastPackage, describing the sum version over all contained content.

  • SubComponentMetaData: A list of subcomponents of this MulticastPackage, designating all Executable Load Files (ELFs) Contained. It usually contains one entry, but can have multiple in the case multiple dependent ELFs get modified. This list can be empty, e.g. for a KeyRotation or deletion of content.

  • SubComponentMetaData name: A human readable name for this subcomponent.

  • SubComponentMetaData aid: The Application Identifier (AID) of the Executable Load File (ELF) which makes up the content of this subcomponent. This is stored as string to have it formatted in upper-case hexadecimal and therefore recognizable form.

  • SubComponentMetaData version: Version information of this subcomponent.

  • SubComponentMetaData minimumPreviousVersion: Minimum version number of this subcomponent as installed on the secure element before this script is executed. If this field is omitted there is no minimum version requirement, e.g. initial Installation of an applet.

  • SignatureOverCommands: The signature over the multicast commands in an machine readable form. So it does not have to be parsed form the script commands. String encoding (upper-case hexadecimal) is chosen here, as many json parsers can not handle such large integer values.

  • MulticastCommands: The complete Multicast Applet Loader Script (certificate, signature, encrypted and signed commands) in ls-cgt format, encoded in base64.

7.2.2. MulticastCommands In Protocol Buffer Format

Note

Advanced information

The information below is for advanced users and kept here for the sake of completeness of information. This section can be skipped.

Technically, the APDUS(MulticastCommands) in update package is encoded in Protocol Buffers format (https://developers.google.com/protocol-buffers/) as defined below

/* Full request from cloud/host to the agent */
message Requests {
  /* An array of RequestPayload */
  repeated RequestPayload payload = 1;
}

/* Consolidated response from the agent to the cloud/host */
message Responses {
  /* An array of ResponsePayload */
  repeated ResponsePayload responses = 1;
}
/* The request payload would be either of these */
message RequestPayload {
  oneof payload {
    /* Hello from EdgeLock 2GO cloud service to the EdgeLock 2GO agent.
     *
     * Used only by EdgeLock 2GO agent. */
    AgentHelloRequest hello = 1;
    /** Good Bye from EdgeLock 2GO cloud service to the EdgeLock 2GO agent.
     *
     * Used only by EdgeLock 2GO agent. */
    AgentGoodbyeRequest goodbye = 2;
    AgentCrlRequest crl = 3;
    /* An APDU to a SE.
     *
     * Used both by EdgeLock 2GO agent and SEMS Lite agent. */
    ApduRequest apdu = 20;
    /* Message to read and write configuration data.
     *
     * Used only by EdgeLock 2GO agent. */
    DatastoreRequest datastore = 30;
    /* Message to contol the host software on the device.
     *
     * Not implemented. */
    RpcRequest rpc = 40;
    /*
     *
     * Used only by SEMS Lite Agent */
    HostControlCmdRequest hostCmd = 50;
  }
}
message ApduRequest {

    /* Array of bytes to be sent to the SE */
    optional bytes message = 100;

    /* What response is expected from the SE for this APDU?
     *
     * If this field is skipped from protobuf, then,
     * only 0x9000 is expected from the SE
     *
     * There are potentially multiple distinct values
     * are expected the from the SE, then this
     * can be an array of those values.
     *
     *      e.g.    expectation: [ 0x9000, 0x6A82 ]
     *
     * For complex schems where a every big range/mask
     * is expected, e.g. 6AXX, 6DXX then the upper
     * 16 bits are treated as mask.
     *
     *      e.g.    expectation: [ 0x00FF6A00, 0x00FF6D00 ]
     *
     * This field is unused by EdgeLock 2GO cloud service.
     */
    repeated uint32 expectation = 101;
}


/* Response from the SE to host */
message ApduResponse {
    /* Byte array */
    optional bytes message = 100;
}

7.2.3. Generator Tools

NXP provides 2 generator tools in semslit/tools/sems-lite-generator directory:

  • JSON Generator: A tool to convert the output of CGT tool to a JSON format output

  • SEMS Lite generator: A tool to convert JSON output to binary file and .c/.h files which will be used by update manager

../../_images/Package_generator.jpg

7.2.3.1. JSON Generator

Usage: MulticastPackageCli.py [-h] –config_file [CONFIG_FILE] –script_file [SCRIPT_FILE] –out [OUT]

Arguments:

  • –config_file [CONFIG_FILE]

    Config File for MulticastPackage generation. It should follow the format defined in semslit/tools/sems-lite-generator/schema/MulticastPackage.jsonschema. NXP provides an example in semslit/tools/sems-lite-generator/config/ExampleConfig.json

  • –script_file [SCRIPT_FILE]

    Encrypted and Signed script as output by the ls-cgt tool.

  • –out [OUT]

    Output MulticastPackage json file.

Example:

python ./MulticastPackageCli.py –config_file .config.json –script_file .encrypted.txt –out .Upgrade_IoTApplet.json

7.2.3.2. SEMS Lite Generator

Usage: generate.py [-h] [-i INPUT_JSON] [-o OUTPUT_PATH] [-n NAME] [-p PROTOC_PATH]

Process sems-lite-generator arguments

Arguments:
-h, --help

show this help message and exit

-i, --input_json INPUT_JSON

input json file

-o, --output_path OUTPUT_PATH

output folder path

-n, --name NAME

stem name of output files. By default, it would use the same name as input json file.

-p, --protoc_path PROTOC_PATH

protoc file path. Use tools/mw_onverter/protoc.exe by default

Example:

python ./generate.py -i ./Upgrade_NXP-IoTApplet-6.0.json -o ./

The generated files:

  • Upgrade_NXP-IoTApplet-6.0.bin: Binary file. It can be used for platforms that have a file system (Windows, Linux, etc). It is encoded in TLV as following:

0x21  Len                             multicastPackage
  |-  0x22  Len  Major Minor          MulticastPackageFormatVersion
  |-  0x23  Len  Binary               TargetEntityID
  |-  0x2f  Len  Binary               Target12nc
  |-  0x24  Len  u32/u16              requiredFreeBytesNonVolatileMemory
  |-  0x25  Len  u32/u16              requiredFreeBytesTransientMemory
  |-  0x26  Len  String               MulticastPackageName
  |-  0x27  Len  Major Minor          MulticastPackageVersion
  |-  0x28  Len  SubComponentMetaData
  |-    |-  0x2B  Len  String         SubComponentMetaData1.name
  |-    |-  0x2C  Len  Binary         SubComponentMetaData1.aid
  |-    |-  0x2D  Len  Major Minor    SubComponentMetaData1.version
  |-    |-  0x2E  Len  Major Minor    SubComponentMetaData1.minimumPreviousVersion
  |-    |-  0x2B  Len  String         SubComponentMetaData2.name
  |-    |-  0x2C  Len  Binary         SubComponentMetaData2.aid
  |-    |-  0x2D  Len  Major Minor    SubComponentMetaData2.version
  |-    |-  0x2E  Len  Major Minor    SubComponentMetaData2.minimumPreviousVersion
  ...
  |-    |-  0x2B  Len  String         SubComponentMetaDataN.name
  |-    |-  0x2C  Len  Binary         SubComponentMetaDataN.aid
  |-    |-  0x2D  Len  Major Minor    SubComponentMetaDataN.version
  |-    |-  0x2E  Len  Major Minor    SubComponentMetaDataN.minimumPreviousVersion
  |-  0x29  Len  Binary               SignatureOverCommands
  |-  0x2A  Len  Binary               MulticastCommands
  • Upgrade_NXP-IoTApplet-6.0.c and .h: These 2 files instantiate update package. They can be integrated into customer tools and can be used for all platforms.

We provide examples for how to use the generated files: Section 5.1.1.12 SEMS Demos

7.2.3.3. Generator Tool Version Compatibility

NXP provides both SEMS Lite generate tool and JSON format in semslite\tools folder. Generate tool should only work with the JSON schema in the same release. For example, in SEMS Lite 2.0.0 (Refer to semslite\version_info.txt) the JSON package format version is 1.2. Generate tool should only use this JSON schema.

JSON package format 1.1

JSON package format 1.2

SEMS Lite 1.0.0

Supported

Not supported

SEMS Lite 2.0.0

Not supported

Supported