PESIGN(1)

NAME
pesign - tool for signing UEFI applications

SYNOPSIS
pesign -i file [-o file] [-f] [-n directory] [-t token] [-c nickname] [-u number] [-m file] [-e file] [-I file] [-E file] [-R file] [-K file] [-C file] [-a] [-l] [-S] [-v] < -s | -D [-N] | -r | -h [-d digest] [-P | -p] >

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

OPTIONS

-i file | - -in file
    Input PE file for signing

-o file | - -out file
    Output PE file for signing

-f | - -force
    Overwrite existing file specified with - -out

-n directory | - -certdir directory
    Use the NSS Database in directory ( default: /etc/pki/pesign)

-t token | - -token token
    Use the NSS token named token

-c nickname | - -certificate nickname
    Use the certificate called nickname in the NSS Database

-u number | - -signature-number number
    Signature number, indexed from 0, for use with - -remove-signature, - -export-signature, or - -show-signature ( default: 0)

-m file | - -import-signature file
    Import Authenticode signature from file

-e file | - -export-signature file
    Export Authenticode signature to file

-I file | - -import-signed-attributes file
    Import PKCS-7 SignedAttributes (with no signature) from file

-E file | - -export-signed-attributes file
    Export PKCS-7 SignedAttributes (with no signature) to file

-R file | - -import-raw-signature file
    Import signature digest from file

-K file | - -export-pubkey file
    Export public key from the NSS Database specified by - -token and - -certificate to file

-C file | - -export-cert file
    Export certificate from the NSS Database specified by - -token and - -certificate to file

-a | - -ascii-armor
    When exporting certificates, encode them in ascii-armor

-l | - -list-signatures
    List signatures

-S | - -show-signature
    Show information about signatures

-v | - -verbose
    Be more verbose

-s | - -sign
    Create a new signature

-D | - -daemonize
    Run as a daemon

-N | - -nofork
    Do not fork when daemonizing ( daemon runs in foreground)

-r | - -remove-signature
    Remove signature

-h | - -hash
    Display the Authenticode hash of the binary

-d digest | - -digest-type digest
    Use the cryptorgaphic digest with - -hash ( use help to list options) ( default: sha256)

-P | - -padding | -p | - -nopadding
    Do or do not pad the binary according to PE 9.3 rules before signing or hashing ( default: - -padding)

    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

  Signing with the certificate and private key in individual files

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 -c my-signing-cert -s \
            -i foo.unsigned.efi -o foo.signed.efi

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 (HSM), level 2 or higher.

  Signing using an HSM

If you have a key pair in your HSM and your HSM vendor provides a PKCS-11 library, you can use it with NSS directly:

    # Add the HSM PKCS-11 library to the NSS database
    host:~$ modutil -dbdir /etc/pki/pesign -add vendor-engine \
            -libfile /usr/lib64/pkcs11/vendor-engine.so
    WARNING: Performing this operation while the browser is running
    could cause corruption of your security databases. If the browser
    is currently running, you should exit browser before continuing
    this operation. Type
    'q <enter>' to abort, or <enter> to continue: <type enter here>

    Module "vendor-engine" added to database.

    # List the added module
    host:~$ modutil -dbdir /etc/pki/pesign -list
    -----------------------------------------------------------
      1. NSS Internal PKCS #11 Module
    	   uri: pkcs11:library-manufacturer=Mozilla%20Foundation;library-description=NSS%20Internal%20Crypto%20Services;library-version=3.52
    	 slots: 2 slots attached
    	status: loaded

    	 slot: NSS Internal Cryptographic Services
    	token: NSS Generic Crypto Services
    	  uri: pkcs11:token=NSS%20Generic%20Crypto%20Services;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203

    	 slot: NSS User Private Key and Certificate Services
    	token: NSS Certificate DB
    	  uri: pkcs11:token=NSS%20Certificate%20DB;manufacturer=Mozilla%20Foundation;serial=0000000000000000;model=NSS%203

      2. opensc-pkcs11.so
    	library name: /usr/lib64/pkcs11/opensc-pkcs11.so
    	   uri: pkcs11:library-manufacturer=OpenSC%20Project;library-description=OpenSC%20smartcard%20framework;library-version=0.20
    	 slots: 1 slot attached
    	status: loaded

    	 slot: Generic Smart Card Reader Interface [Smart Card Reader Interf...
    	token: OpenSC Card (myorg-sb-signer)
    	  uri: pkcs11:token=OpenSC%20Card%20(myorg-sb-signer);manufacturer=OpenSC%20Project;serial=56516a130f35;model=PKCS%2315
    -----------------------------------------------------------

    # List certs in tokens
    host:~$ certutil -d /etc/pki/pesign \
            -h "OpenSC Card (myorg-sb-signer)" -L
    Certificate Nickname                             Trust Attributes
                                                     SSL,S/MIME,JAR/XPI

    Enter Password or Pin for "OpenSC Card (myorg-sb-signer)": <type the PIN here>
    OpenSC Card (myorg-sb-signer):/CN=My Org's SB Signer    u,u,u

    # Sign with private key in HSM
    host:~$ pesign -t "OpenSC Card (myorg-sb-signer)" \
            -c "OpenSC Card (myorg-sb-signer):/CN=My Org's SB Signer" \
            -s -i foo.unsigned.efi -o foo.efi

  Signing using an HSM with an OpenSSL Engine

If you have a key pair in your HSM but can't access it directly, but do have access to the openssl command line tool configured with your vendor's libraries, you can still use pesign to sign your PE binaries:

    # Import the public certificate into the NSS Database
    host:~$ certutil -d /etc/pki/pesign -A -n myorg-sb-signer \
            -t ,,u -i myorg-sb-signer.cer

    # Export the PKCS-7 SignedAttributes section pesign generates
    host:~$ pesign -i foo.unsigned.efi -E foo.sattrs.bin

    # Generate a signature using OpenSSL
    host:~$ openssl dgst -sha256 -sign $KEY \
            --keyform ENGINE --engine $ENGINEID \
            -out foo.sattrs.sig foo.sattrs.bin

    # Import the signature with the original SignedAttributes into
    # the PE binary
    host:~$ pesign -c myorg-sb-signer \
            -R foo.sattrs.sig -I foo.sattrs.bin \
            -i foo.unsigned.efi -o foo.efi

STANDARDS
B. Kaliski, RFC 2315, PKCS #7: Cryptographic Message Syntax v1.5, Internet Engineering Task Force, March 1998, https://tools.ietf.org/html/rfc2315 .

K. Moriarty, M. Nyström, S. Parkinson, A. Rusch, M. Scott, RFC 7292, PKCS #12: Personal Information Exchange Syntax v1.1, Internet Engineering Task Force, July 2014, https://tools.ietf.org/html/rfc7292 .

PKCS11 Technical Committee, PKCS#11: Cryptographic Token Interface Standard, OASIS, https://www.cryptsoft.com/pkcs11doc/.

M. Nyström, PKCS #15—A Cryptographic-Token Information Format Standard, RSA Laboratories, 1999, https://www.usenix.org/legacy/events/smartcard99/full_papers/nystrom/nystrom.pdf .

Portable Executable, Microsoft, August 26, 2019, https://docs.microsoft.com/en-us/windows/win32/debug/pe-format .

Windows Authenticode Portable Executable Signature Format, Microsoft, March 21, 2008, https://web.archive.org/web/20130518222430/http://download.microsoft.com/download/9/c/5/9c5b2167-8017-4bae-9fde-d599bac8184a/Authenticode_PE.docx .

FIPS 140-2, Federal Information Processing Standard 140-2, National Institute of Standards and Technology, United States Department of Commerce, http://csrc.nist.gov/publications/PubsFIPS.html .

SEE ALSO
certutil(1), efikeygen(1), modutil(1), opensc-tool(1), openssl(1ssl), openssl-dgst(1ssl), pesign-client(1), pk12util(1), pkcs15-init(1),

AUTHORS
Peter Jones Vikas Charak (examples)