Developer Guide

  • 2021.1
  • 11/03/2021
  • Public
Contents

Create an Environment File

The environment file contains information about the tool environment. This file must be a well-formatted JSON* document containing all required information. This page covers:

JSON Description

The file defines two main types of information:
  • Information that allows the host to connect to the target system via SSH, such as hostname, username, password, and port.
  • Information that allows the tool to create and apply the capsule image. For more information, see Capsule.
It is important to escape JSON-specific characters such as double-quotes and backslash:
Character
Escape symbol
"
\"
\
\\
Example environment file:
{ "targets": { "target_name_1": { "target_info": "...", "platform_name": "AUTO", "reboot_command": "reboot", "connections_settings": { "hostname": "...", "username": "...", "password": "...", "port": 22, "connection_timeout":5, "reconnection_timeout":10, "reconnection_attempts":10 }, "capsule_settings": { "capsule_paths": { "capsule_host_path": "./tmp/", "capsule_target_path": "/home/root/", "tcc_json_path": "./demo/environment/", "tcc_tuning_binary_path": "./tmp/", "tcc_tuning_signed_binary_path": "./tmp/" }, "streams": { "capsule_generate_command": "python3 ./capsule/siiptool/scripts/subregion_capsule.py -o $capsule_host_path --signer-private-cert=./cert/TestCert.pem --other-public-cert=./cert/TestSub.pub.pem --trusted-public-cert=./cert/TestRoot.pub.pem $tcc_json_path", "capsule_apply_command": "fwupdate --apply bf2ae378-01e0-4605-9e3b-2ee2fc7339de $capsule_target_path", "tuning_binary_sign_command": "python3 ./capsule/siiptool/scripts/subregion_sign.py ---name tcc --signer ../keys/Signing.key --signer_type rsa --vendor-guid 7F6AD829-15E9-4FDE-9DD3-0548BB7F56F3 $tcc_tuning_binary_path --output $tcc_tuning_signed_binary_path" } } } } }
The following table describes each field:
Field
Description
“targets”
List of target systems in the following format: “target_name”: {TARGET_SECTION}
“target_name”
Unique identifier for the target system.
“target_info”
Additional information about the target system. The tool does not use this field in the tuning flow.
“platform_name”
Platform name of the target system. For automated detection of the platform, type “AUTO”. Or specify the platform name: For Intel Atom® x6000E Series processors, type “EHL”. For 11th Gen Intel® Core™ processors, type “TGL”.
“reboot_command”
Valid values are
reboot
or an empty line if no reboot is required. You can also create your own script (for example, to check something before rebooting) and input the command here.
“connection_settings”
Section that stores all connection-related data: hostname, username, password, and so on.
“hostname”
IP address or hostname of the target system.
“username”
Username to connect to the target system by SSH. An Authenticated User must have read/write permissions for the capsule location and be able to execute the workload validation script.
“password”
Password to connect to the target system by SSH. If the SSH connection to the target system is expected to be passwordless or you have created an SSH key and installed the SSH key on a target system, you can leave the password field empty. The tool also accepts environment files that do not contain a password field.
“port”
Port to connect to the target system by SSH.
“connection_timeout”
Wait time before the SSH connection between the host and target system is considered failed, in seconds
“reconnection_timeout”
Delay between the next attempt to reconnect the host and target system via SSH, in seconds
“reconnection_attempts”
Optional field. The maximum number of SSH reconnection attempts. Possible value is an integer from 1–255 (default: 10).
“capsule_settings”
Capsule-related information, such as capsule paths, capsule generate commands.
“capsule_paths”
This is a special field. Here common paths can be defined and reused later in the “capsule_generate_command”, “tuning_binary_sign_command” and “capsule_apply_command” fields.
Items are required to be directory paths:
  • “capsule_host_path”
  • “capsule_target_path”
  • “tcc_json_path”
  • “tcc_tuning_binary_path”
  • “tcc_tuning_signed_binary_path”
To reuse the paths, add the path field name prepended with $ to “capsule_generate_command” or “capsule_apply_command”. Each of the four directory paths will be extended with default filenames based on which section it was reused in.
For example: See the example environment file above. The “capsule_host_path” is defined as “./tmp/”, and “$capsule_host_path” appears in the “capsule_generate_command”. The “$capsule_host_path” will be replaced with the following path: “./tmp/streams_capsule.out.bin”.
“streams”
Data streams optimizer tool capsule section. The “streams_” prefix will be applied for default capsule paths.
“capsule_generate_command”
Command-line executable with all required console arguments / flags. The tool uses it to generate the capsule image on the host system.
“capsule_apply_command”
Command-line executable with all required console arguments / flags. The tool uses it to apply the capsule image on the target system.

Tool Flow

In the context of the Host-Target Reference Implementation, the environment file affects the following steps:
  • Capsule-related fields are used to create, move, and apply the capsule image.
  • SSH-related fields are used to SSH from the host to the target system.
  • The
    "reboot_command"
    is used to reboot the target system.

Capsule

The data streams optimizer changes the configuration of the target system by updating the firmware. In the case of the reference implementation, the tool uses a capsule image (binary file) to update certain areas of the BIOS, known as “subregions.”
The sample environment file defines all capsule-related fields for the reference BIOS. If you are using the reference BIOS, you do not need to update those fields.
In the context of the Host-Target Reference Implementation, the capsule-related fields affect the following steps:
  1. When it’s time to create the capsule image, the tool runs the command specified in the
    "capsule_generate_command"
    field, and the tool expects to find the capsule image in the location identified in the
    "capsule_host_path"
    field. It is important to ensure that the output location (-o option) in
    "capsule_generate_command"
    is the same as the location in
    "capsule_host_path"
    .
  2. The tool moves the capsule image to the location identified in the
    "capsule_target_path"
    field.
  3. The tool applies the image via the command specified in the
    "capsule_apply_command"
    field.
Subregion Capsule Tool
As specified in the
"capsule_generate_command"
field, the data streams optimizer uses the subregion capsule tool (
subregion_capsule.py
) to create the capsule image.
The default keys for signing the capsule are for test ONLY on Intel CRB. In a production environment, the user will need to generate their own keys and work with their BIOS vendor to provision them into the BIOS.
usage: subregion_capsule [-h] -o OUTPUTCAPSULEFILE [-s OPENSSLSIGNERPRIVATECERTFILE] [-p OPENSSLOTHERPUBLICCERTFILE][-t OPENSSLTRUSTEDPUBLICCERTFILE] [--signing-tool-path SIGNINGTOOLPATH] InputFile
Argument
Description
-o OUTPUTCAPSULEFILE
Output file name of new generated capsule (for example, capsule.out.bin).
-s | --signer-private-cert OPENSSLSIGNERPRIVATECERTFILE
OpenSSL signer private certificate file name (for example, TestCert.pem).
-p | --other-public-cert OPENSSLOTHERPUBLICCERTFILE
OpenSSL other public certificate file name (for example, TestSub.pub.pem).
-t | --trusted-public-cert OPENSSLTRUSTEDPUBLICCERTFILE
OpenSSL trusted public certificate file name (for example, TestRoot.pub.pem).
--signing-tool-path SIGNINGTOOLPATH
Path to signtool or OpenSSL tool. Optional if path to tools is already in PATH.
InputFile
Input JSON subregion descriptor file name (for example, tcc.json).
-h
Print command-line help.
Subregion Sign Tool
As specified in the
"tuning_binary_sign_command"
field, the data streams optimizer uses the subregion sign tool (
subregion_sign.py
) to create and sign a BIOS subregion for UEFI.
usage: subregion_sign [-h] [-o Filename] -n subregion -vg v_guid -t sign_type -s SIGNERFILE [--toolpath TOOL_PATH] [--show] [-v] subregion_file
Argument
Description
-o | --output Filename
Output capsule filename.
-n | --name subregion
The name of the subregion being signed. Maximum size is 16 bytes. The name is stored in the signed file.
-vg | --vendor-guid v_guid
Vendor GUID is one specific value given by the vendor for the subregion being signed. This is required. The format is ‘00000000-0000-0000-0000-000000000000’.
-t | --signer_type sign_type
Type of Signing pkcs7 or rsa.
-s | --signer signerfile
OpenSSL signer private certificate filename.
--toolpath TOOL_PATH
Path to signtool or OpenSSL tool. Optional if path to tools are already in PATH.
--show
Shows information about the subregion_authentication structure. Optional but requires all information in order to process.
-v | --version
Shows the current version of the BIOS Stitching Tool.
-h | --help
Print command-line help.
subregion_file
Subregion data that needs to be signed.

Using Your Own Bootloader

You can use your own bootloader with the data streams optimizer.
If you are using a UEFI BIOS other than the reference BIOS binary, you can use the subregion capsule tool to sign the capsule and subregion. In this case, you will need to generate and enroll your certificate or public key into the BIOS. The flow requires working with your BIOS vendor to enroll the certificates/keys. The subregion data and the capsule must always be signed when generated to ensure the integrity of the generated capsule. The signature of the signed capsule and its payload (signed subregion data) will be authenticated by the BIOS before it is consumed.
When using an Intel provided BIOS binary with Intel CRB/RVP, the authentication can be turned off, since users may not have the ability to provision their keys.
If you are using a different bootloader, such as Coreboot, replace the subregion capsule tool with your own tool.

Samples

The tool provides a sample in the following directory:
${TCC_TOOLS_PATH}/demo/environment/sample_environment.json
When you are ready to create your own file, you can make a copy of the example and modify it as needed.

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.