PESIGN(1)

NAME
pesign - command line tool for signing UEFI applications

SYNOPSIS
pesign [--in=infile | -i infile]
       [--out=outfile | -o outfile]
       [--certdir=certdir/fR | -n certdir]
       [--nss-token=token | -t token]
       [--certificate=nickname | -c nickname]
       [--force | -f] [--sign | -s] [--hash | -h]
       [--digest_type=digest | -d digest]
       [--show-signature | -S ] [--remove-signature | -r ]
       [--export-pubkey=outkey | -K outkey]
       [--export-cert=outcert | -C outcert]
       [--ascii-armor | -a] [--daemonize | -D] [--nofork | -N]
       [--padding | -P | --nopadding | -p ]
       [--signature-number=signum | -u signum]

DESCRIPTION
pesign is a command line tool for manipulating signatures and cryptographic digests of UEFI applications.

OPTIONS

--in=infile
    Specify input binary.

--out=outfile
    Specify output binary.

--certdir=certdir
    Specify nss certificate database directory.

--nss-token=token
    Use the specified NSS token's certificate database.

--certificate=nickname
    Use the certificate database entry with the specified nickname for signing.

--force
    Overwrite output files. Without this parameter, pesign will refuse to overrite any output files which already exist.

--sign
    Sign the input binary with the key specified by --certificate.

--hash
    Display the cryptographic digest of the input binary on standard output.

--digest_type=digest
    Use the specified digest in hashing and signing operations. By default, this value is "sha256". Use "--digest_type=help" to list the available digests.

--show-signature
    Show information about the signature of the input binary.

--remove-signature
    Remove the signature section from the binary.

--signature-number=signum
    Specify which signature to operate on. This field is zero-indexed.

--export-pubkey=outkey
    Export the public key specified by --certificate to outkey

--export-cert=outcert
    Export the certificate specified by --certificate to outcert

--ascii-armor
    Use ascii armoring on exported certificates.

--daemonize
    Spawn a daemon for use with pesign-client(1)

--nofork
    Do not fork when using --daemonize.

--padding | --nopadding
    Do or do not pad the binary out to the PE 9.3 alignment before signing. Padding is recommended (and in many circumstances required) even for binaries which predate the current PE spec, and is enabled by default as of pesign 113.

EXAMPLES
1.If you have a certificate file and private key file, the following steps may be used to sign a PE image:
    # Create a pkcs12 file from private key and
    # certificate file.
    host:~$ openssl pkcs12 -export -out foo_key.p12 \
    -inkey signing_key.pem \
    -in xyz_cert.x509.pem

    # Import pkcs12 file into pesign db
    host:~$ pk12util -i foo_key.p12 -d /etc/pki/pesign

    # Do the signing
    host:~$ pesign -i <input-file> -o <output-file> \
    -c <cert nickname> -s

Please note that this is just an example, and that recommended best practice is to always store private keys in a FIPS 140-2 hardware security module, level 2 or higher.

2.If you have a key pair in your HSM and your HSM supports PKCS #11 and the OpenSSL Engine, the following steps may be used to sign a PE image using OpenSSL:

    # Install your vendor's engine into OpenSSL. (Contact your vendor for OpenSSL engine support)
    host:~$ cp <vendor_engine>.so /usr/lib64/openssl/engines/
    host:~$ openssl engine -v <engine_id>
    [Verify vendor engine. engine_id is set by your vendor while producing .so file]

    # Add PKCS #11 module
    host:~$ sudo su - pesign -s /bin/bash
    host:~$ modutil -dbdir /etc/pki/pesign -add <module_name> -libfile /usr/lib64/<vendor_engine>.so

    # List the added module
    host:~$ modutil -dbdir /etc/pki/pesign -list
    Example, listing of PKCS #11 modules
     -------------------------------------
    <module_name>
    library name: /usr/lib64/<vendor-engine>.so
    slots: N slots attached
    status: loaded
    slot: PCI Card
    token: Test-CA

    # List certs in tokens
    host:~$ certutil -d /etc/pki/pesign -L -h "Test-CA" [token name from listing above]

    # Sign with private key in HSM
    host:~$ pesign --sign --in=<input_file> --out=<output_file> --nss-token="Test-CA" --certficate="PUB_CRT"
    Where "Test-CA" is the name of the HSM token as listed by "modutil -list" and "PUB_CRT" is the certificate name/label in the HSM whose private key will be used to sign the PE binary.

SEE ALSO
pesign-client(1)

FIPS 140-2 http://csrc.nist.gov/publications/PubsFIPS.html

AUTHORS
Peter Jones, Vikas Charak