MX-Tools

MX-Tools

What is Ensign?

Ensign is a command line tool to build signed Mozilla extensions installation packages (.xpi files). It is suitable both for automated build process and for interactive use. It's a part of MX-Tools package.

Features

Ensign is meant to be used to build a signed installation package based on a set of files to be included in the package. The base directory with the intended contents of the package doesn't have to be "clean", it may contain files to be ignored when generating the signature and building the package.

Usage

The general command line syntax:

ensign [options] source package.xpi signer.crt

The command must be run in the root of the directory hierarchy to be included in the installation package. The names of the subdirectories (if any) will be a part of each file path inside the package. The command line arguments are:

source
The list of the files to be included in the installation package. This should be a text file containing one file name per line with the path relative to the current directory. If the value of this parameter is - (dash) the file list will be read from the standard input. If the value is . (dot) the file list will be constructed internally based on the contents of the current directory, which means that all the files in the current directory and subdirectories will be included.
package.xpi
The file name of the output installation package. If the file exists it will be overwritten.
signer.crt
The certificate to sign the package with. It must be an x509 code signing certificate in PEM format.

Additionally, the following options may be specified:

-k keyfile.pem
The private key for the signer certificate. If this parameter is omitted the key must be contained in the same file as the certificate itself (signer.crt above).
-p passwarg
The password for the private key. This parameter is required when the key is encrypted (which is almost always the case). 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.
-c cacerts.pem
Extra certificates to be included in the signature. Typically these are the intermediate CA certificates. The file must contain one or more concatenated x509 certificates in PEM format.

Description

In the current directory Ensign creates META-INF subdirectory (unless it already exists) and there it creates the files that constitute the signature: manifest.mf, zigbert.sf, and zigbert.rsa. If some of those files already exist they are overwritten.

Subsequently the signature files and the files specified by the source argument are put into a zip file with the signature files first. If the source list is specified (either as a file name or via the standard input stream) it must not contain the signature files (regardless of whether those exist prior to invoking the command).

Examples

Make a signed installation package given a file list:

ensign -k keyfile.pem -p =password filelist.txt package.xpi certfile.crt

Include all the files within the current directory:

ensign -k keyfile.pem -p =password . ../package.xpi ../certfile.crt

Use the private key contained in the certificate file:

ensign -p =password filelist.txt package.xpi certfile.crt

Include an additional intermediate CA certificate:

ensign -p =password -c cacerts.pem filelist.txt package.xpi certfile.crt

Dependencies

Perl, Digest::SHA1 or Digest::SHA, OpenSSL, zip.

License, Download, Feedback

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