Docs › Updating device firmware › Preparing manifests › External signing tools

External signing tools

You should use a hardware security module (HSM) to perform signing operations in production. To use an HSM for signing, the manifest tool can call an external signing tool:

<tool> <digest algorithm> <key identifier> <input file> <output file>

The manifest tool writes the data to sign to <input file> before the script is called. The manifest tool reads <output file> to find the signature after the script finishes. Both files should be in raw, binary form.

This guide gives two tool examples of the signing tool process:

OpenSSL as an external signing tool.
OpenSC's pkcs11-tool as a digest calculator and pkcs15-crypt as a signing tool.

We present both of these examples as bash scripts.

Signing with OpenSSL

Note: We provide OpenSSL signing tool instructions only as an example. The security of the OpenSSL solution is identical to that of using the manifest tool's internal signing feature. This is an example of how to integrate the manifest tool with an external signing tool.

Note: Unless the version of OpenSSL your platform provides is at least 1.0.1, we do not recommend you use OpenSSL.

Please adapt these instructions for use with your external signing tool, for example, an HSM or a secure token.

The following script is a wrapper for OpenSSL:

openssl-sign.sh:

#!/usr/bin/env bash
$ openssl dgst -binary -$1 -keyform PEM -sign "$2" -out "$4" "$3"

Parameters:

$1: Digest algorithm.
$2: Key identifier.
$3: Input file.
$4: Output file.

Prepare OpenSSL

You must prepare the signing tool before you can use it with the manifest tool. This includes tool-specific setup tasks, such as configuring an HSM, configuring PINs, generating keys and generating certificates.

For the OpenSSL example, generate an ECDSA keypair and a self-signed certificate:

$ openssl ecparam -genkey -name prime256v1 -out key.pem
$ openssl req -new -sha256 -key key.pem -out csr.csr
$ openssl req -x509 -sha256 -days 365 -key key.pem -in csr.csr -outform der -out certificate.der

Register OpenSSL as a signing tool

After you have configured the signing tool, register it with the manifest tool:

$ manifest-tool init -d "<company domain name>" -m "<product model identifier>" -c "<certificate file>" -s "<external signing tool script>" --signing-key-id "<signing key identifier>" -a "<Device Management access key>"

The external signing tool is the absolute path of the signing script, and the signing key identifier is the file name of the key created in the previous step.

After you do this, the manifest tool uses the signing tool by default. To disable the signing tool, rerun manifest-tool init or delete the signing-tool entry from .manifest_tool.json.

Signing with a secure token

Please adapt these instructions for your external signing tool, such as an HSM or secure token.

The following script is a wrapper for PKCS11/PKCS15:

#!/usr/bin/env bash
if [ "$1" = "sha256" ]; then
    DGST15="sha-256"
    DGST11="SHA256"
fi
SHA=`pkcs11-tool --hash -m "$DGST11" -i "$3" | xxd -ps -c 64`
pkcs15-crypt -s -i <(echo "$SHA" | xxd -r -ps) --$DGST15 -k "$2" -f openssl -o "$4"

Prepare the secure token

Generate a new ECDSA secp256r1 keypair with signature permissions (optional if key already exists).
Generate a certificate for the selected keypair (optional if certificate already exists).
Export the certificate from the token.

Convert the certificate to DER. You can do this with OpenSSL:

$ openssl x509 -inform PEM -in <PEM certificate> -outform DER -out <DER certificate>

If you don't have OpenSSL, you can use any base64 decoder to decode the text between the guard blocks in the PEM certificate.

Register the secure token signing tool