pw_software_update: CLI reference#

Pigweed AI summary: The pw_software_update CLI is a tool for quickly prototyping a software update system on a development PC before productionizing one. It includes various commands for generating keys, creating and signing root metadata, creating and adding files to update bundles, and verifying bundles. The CLI is designed for secure software delivery and can be used to update a reference target in the future.

Overview#

Pigweed AI summary: The pw_software_update CLI can be used to prototype a software update system on a development PC before implementing it in production. The CLI can also be used to update a reference target in the future. The CLI offers various commands such as generating a local signing key, creating a TUF root metadata file, adding a target file to an existing bundle, and verifying an update bundle.

Use the pw_software_update CLI to quickly learn and prototype a software update system on your development PC before productionizing one. In the future you will be able to use the CLI to update a reference target.

~$ cd pigweed
~/pigweed$ source ./activate.sh
~/pigweed$ pw update [-h] <command>

Command	Description
`generate-key`	generates a local signing key
`create-root-metadata`	creates a TUF root metadata file
`sign-root-metadata`	signs a TUF root metadata
`inspect-root-metadata`	prints a TUF root metadata
`create-empty-bundle`	creates an empty update bundle
`add-root-metadata-to-bundle`	adds a root metadata to an existing bundle
`add-file-to-bundle`	adds a target file to an existing bundle
`sign-bundle`	signs an update bundle
`inspect-bundle`	prints an update bundle
`verify-bundle`	verifies an update bundle

generate-key#

Pigweed AI summary: This section describes a command that generates an ECDSA SHA-256 public and private keypair. The command can be accessed through the "pw update generate-key" command and requires a pathname to be specified for the output of the new key pair. The argument table provides a description of the "pathname" argument.

Generates an ECDSA SHA-256 public + private keypair.

$ pw update generate-key [-h] pathname

Argument	Description
`pathname`	output pathname for the new key pair

create-root-metadata#

Pigweed AI summary: This section describes how to create a root metadata using the "pw update create-root-metadata" command. The command requires the path to the root key and targets key, and an output path for the newly created root metadata. An anti-rollback version number can also be specified. The options for the command are listed in a table.

Creates a root metadata.

$ pw update create-root-metadata [-h]
    [--version VERSION] \
    --append-root-key ROOT_KEY \
    --append-targets-key TARGETS_KEY \
    -o/--out OUT

Option	Description
`--append-root-key`	path to root key (public)
`--append-targets-key`	path to targets key (public)
`--out`	output path of newly created root metadata
`--version`	anti-rollback version number of the root metadata (defaults to 1)

sign-root-metadata#

Pigweed AI summary: This section describes a command called "pw update sign-root-metadata" which signs a given root metadata. The command requires two arguments: the path of the root metadata to be signed and the path to the root signing key (private). These arguments are specified using the options "--root-metadata" and "--root-key" respectively. The section also includes a table that summarizes the options and their descriptions.

Signs a given root metadata.

$ pw update sign-root-metadata [-h] \
    --root-metadata ROOT_METADATA \
    --root-key ROOT_KEY

Option	Description
`--root-metadata`	Path of root metadata to be signed
`--root-key`	Path to root signing key (private)

inspect-root-metadata#

Pigweed AI summary: The "inspect-root-metadata" function prints the contents of a given root metadata. It can be accessed through the command "pw update inspect-root-metadata" and requires a pathname argument that specifies the path to the root metadata.

Prints the contents of a given root metadata.

$ pw update inspect-root-metadata [-h] pathname

Argument	Description
`pathname`	Path to root metadata

create-empty-bundle#

Pigweed AI summary: The "create-empty-bundle" section provides information on how to create an empty update bundle using the "pw update create-empty-bundle" command. The command requires a pathname argument for the location of the empty bundle and has an optional "--target-metadata-version" option for specifying the version number for targets metadata. The default version number is 1.

Creates an empty update bundle.

$ pw update create-empty-bundle [-h] \
    [--target-metadata-version VERSION] \
    pathname

Argument	Description
`pathname`	Path to newly created empty bundle

Option	Description
`--target-metadata-version`	Version number for targets metadata, defaults to 1

add-root-metadata-to-bundle#

Pigweed AI summary: This section describes a command that adds a root metadata to a bundle. The command is executed using the "pw update add-root-metadata-to-bundle" command with options for the path to the root metadata and the pathname of the bundle. The options are "--append-root-metadata" and "--bundle" respectively. These options are described in a table.

Adds a root metadata to a bundle.

$ pw update add-root-metadata-to-bundle [-h] \
    --append-root-metadata ROOT_METADATA \
    --bundle BUNDLE

Option	Description
`--append-root-metadata`	Path to root metadata
`--bundle`	Pathname of the bundle

add-file-to-bundle#

Pigweed AI summary: This section describes the "add-file-to-bundle" function, which allows users to add a target file to an existing bundle. The command syntax is provided in a literal block, and the available options are listed in a table, including the path to the target file, the pathname of the bundle, and an optional new name for the target.

Adds a target file to an existing bundle.

$ pw update add-file-to-bundle [-h] \
    [--new-name NEW_NAME] \
    --bundle BUNDLE \
    --file FILE_PATH

Option	Description
`--file`	Path to a target file
`--bundle`	Pathname of the bundle
`--new-name`	Optional new name for target

sign-bundle#

Pigweed AI summary: This section describes how to sign an existing bundle with a dev key using the "pw update sign-bundle" command. The command requires the bundle pathname and the private key for signing as arguments. These arguments are specified using the "--bundle" and "--key" options respectively. The options and their descriptions are listed in a table.

Signs an existing bundle with a dev key.

$ pw update sign-bundle [-h] --bundle BUNDLE --key KEY

Option	Description
`--key`	The targets signing key (private)
`--bundle`	Pathname of the bundle

inspect-bundle#

Pigweed AI summary: The "inspect-bundle" section provides a command to print the contents of a given bundle. The command is "pw update inspect-bundle" and requires the pathname of the bundle as an argument.

Prints the contents of a given bundle.

$ pw update inspect-bundle [-h] pathname

Argument	Description
`pathname`	Pathname of the bundle

verify-bundle#

Pigweed AI summary: The "verify-bundle" section performs verification of an existing bundle. The command to execute this is "pw update verify-bundle" with options for trusted root metadata and the pathname of the bundle to be verified.

Performs verification of an existing bundle.

$ pw update verify-bundle [-h] \
    --bundle BUNDLE
    --trusted-root-metadata ROOT_METADATA

Option	Description
`--trusted-root-metadata`	Trusted root metadata(anchor)
`--bundle`	Pathname of the bundle to be verified

pw_software_update#

Secure software delivery