MX-Tools

MX-Tools

McCoy: Busy?

Spock: Uhura is busy. I am monitoring.

Star Trek IV: The Voyage Home.

What is Uhura?

Uhura is a command line tool to generate and/or sign Mozilla extensions update manifests (a.k.a. update.rdf). It is suitable for automated build process as well as for interactive use. It's a part of MX-Tools package.

Features

Uhura is capable of performing a number of common tasks with update manifests:

  • Generate an update manifest based solely on a set of installation packages and (optionally) sign it with a given RSA key.
  • Extract extension and target application version information from one or more installation packages and use it to update the corresponding fields in an existing update manifest.
  • Calculate SHA1 hash of one or more installation packages and insert the value(s) into an existing update manifest.
  • Sign an existing update manifest with a given RSA key.

Usage

The general command line syntax:

uhura [options] [file1.xpi [URL1 [URL1′]] [file1.txt]] [file2.xpi ...] [...]

The options are followed by an arbitrary number of groups of 1, 2, 3 or 4 arguments, depending on the specified options. The arguments in each group have the following meaning:

fileN.xpi
The path to the installation package in the local file system (used to extract information about the extension and to calculate SHA1 hash if necessary).
URLN
The public URL where the installation package is going to be available for download (the package does not have to be available at that URL at the time of running the command).
URLN
The public URL of the "What's new" page (updateInfoURL) to be included when generating a new update manifest.
fileN.txt
The path to the text file that specifies overriding maxVersion specified in the installation package (used with -m option described below).

The options are used to provide extra input information and to specify what actions are to be performed. The following options are supported:

-i input.rdf
The input update manifest file to be signed. If this option is omitted a new update manifest will be generated based on the contents of the installation packages.
-h
Calculate SHA1 hash of the installation packages and set the corresponding updateHash fields in the update manifest to the computed values. This option is implied if the update manifest is to be signed (i.e. when -k option is present).
-v
Set the target application version fields (minVersion and maxVersion) in the update manifest to the values extracted from the corresponding installation packages. This option has no effect in generating mode (without an input update manifest specified with -i option), because all the fields must always be filled in to produce a valid update manifest.
-m
If specified, each input installation package is accompanied with a text file that allows to override maxVersion field for target applications. Each line in such a file should contain a pair of tokens separated with whitespace. The first token is the target application id and the second one is the value to be used as the corresponding maxVersion. The name of the file is specified as an additional element in each parameter group, as described below.
-k keyfile.pem
The private key to sign the update manifest with. Typically it is an RSA key in PEM format. If this parameter is omitted the update manifest will not be signed. The presence of this option also implies -h option described above.
-p passwarg
The password for the private key. Only has a meaning if a key file is specified with -k option. If this option is omitted or if the value of passwarg is an empty string the key must be unencrypted. The passwarg parameter can have one of the following forms (where the first character indicates which form is used):
=password The password is specified literally. This is the easiest way, but in many cases it may be insecure on a multi-user system, since any user can see the password using ps utility or alike.
@filename The password is read from the specified file. The first line of the file is assumed to contain the password.
$ENV_VAR The password is fetched from the specified environment variable. This is not the same as having the environment variable expanded by the shell when invoking the command. The syntax is very similar to most UNIX shells, but here the $ character is passed literally (thus must be escaped properly when using a UNIX-like shell).
&fd The password is read from the specified file descriptor. Depending on the OS this may or may not be supported (usually supported on UNIX-like OS). The first line read from the file descriptor is assumed to contain the password.
- The password is read from the standard input. The first line of the input stream is assumed to contain the password.
The password argument is converted to one of the forms accepted by OpenSSL -passin argument, as described in the OpenSSL manual. So the security considerations applicable to OpenSSL invocation also apply here.
-u
This option indicates that an extra URL parameter is present in each parameter group for each input installation package. The exact meaning of this option depends on the operation mode as described below.
-o update.rdf
The output update manifest file. This can be the same file as specified with -i option (in that case the file will be overwritten). If this parameter is omitted the resulting update manifest will be written to the standard output.
-e
Although the output XML always specifies UTF-8 encoding in the XML declaration, with this option present, all non-ASCII characters are converted to the corresponding XML character entities, which makes it compatible with US-ASCII character encoding. Note: in signing mode this option only affect parts generated or modified in the process, leaving the rest of the update manifest unchanged.

The remaining command line arguments form one or more groups specifying the installation packages to be used and the corresponding URLs. The number of parameters in each group depends on the presence of -i and -u options:

neither
Generating mode. Each group consists of two parameters: the installation package file name and the corresponding update URL to be put in the update manifest.
-u only
Generating mode. Each group consists of three parameters: the installation package file name, the corresponding update URL, and the corresponding "What's new" URL (updateInfoURL) to be put in the update manifest.
-i only
Signing mode. Each group consists of a single parameter specifying the installation package file name. The order of the file names in the command line must be the same as the order of corresponding sections in the input update manifest (with duplicate occurrences skipped).
both
Signing mode. Each group consists of two parameters: the installation package file name and the corresponding update URL. The latter is used to match the installation packages specified on the command line with the corresponding sections of the input update manifest (so that the order of the file names in the command line does not matter).

In addition to that, if -m option is present then each parameter group contains one more element specifying the path to the maxVersion override file. If some of the input installation packages do not need such a file the corresponding path can be an empty string.

Description

The install.rdf file found in each installation package specified in the command line is parsed to retrieve the information about the extension (id, version) and about the target application(s) (id, minVersion, maxVersion). Also, if the update manifest is to be signed or if -h command line option is present, the SHA1 hash of each installation package (xpi file) is calculated. That information is used to construct a new update manifest or, if an input update manifest is specified with -i option, to update the corresponding fields of the existing update manifest.

When processing an existing update manifest only the fields that already exist are updated. It means that the input update manifest should contain placeholders for all fields to be filled in. The values are not important, as they will be replaced with the actual ones.

Creating a Key

A key file can be generated with the following command:

openssl genrsa -out keyfile.pem 1024

This produces a new unencrypted private key that can be used to sign update manifests. To generate an encrypted (i.e. protected with password) private key one of the encryption command line options described in the OpenSSL manual should be used.

In order to have the signature successfully verified the corresponding public key must be specified as the updateKey in the installation manifest of the of the extension(s) to be updated. To obtain the public key the following command can be used:

openssl rsa -in keyfile.pem -pubout -out keyfile.pub

The content of keyfile.pub (excluding the lines designating begin/end of the public key) can be copied to the installation manifests of all extensions the key is going to be used with. Obviously, this has to be done before creating the installation packages and attempting to generate an update manifest.

Examples

Generate an update manifest for a single installation package:

uhura -o update.rdf extension.xpi https://www.example.com/extension.xpi

Generate an update manifest with "What's new" link for a single installation package:

uhura -o update.rdf -u extension.xpi https://www.example.com/extension.xpi https://www.example.com/update.xhtml

Generate and sign an update manifest for a single installation package:

uhura -o update.rdf -k keyfile.pem -p =password extension.xpi http://www.example.com/extension.xpi

Generate and sign an update manifest for a single installation package with overriding the target application maxVersion:

uhura -o update.rdf -m -k keyfile.pem -p =password extension.xpi http://www.example.com/extension.xpi appvers.txt

Generate an update manifest for two installation packages:

uhura -o update.rdf extension1.xpi https://www.example.com/extension1.xpi extension2.xpi https://www.example.com/extension2.xpi

Update an existing update manifest with the version information and SHA1 hash value from a single installation package:

uhura -i input.rdf -o output.rdf -v -h extension.xpi

Sign an existing update manifest:

uhura -i input.rdf -o output.rdf -k keyfile.pem -p =password

Dependencies

Perl, XML::Parser, RDF::Core, Convert::ASN1, OpenSSL, unzip.

License, Download, Feedback

As mentioned in the beginning of this page, Uhura is a part of MX-Tools, so see there.