UEFI Secure Boot signing using a DigiCert eToken

UEFI Secure Boot requires UEFI binaries to be signed by Microsoft. This page documents the work in progress to obtain signed versions of iPXE and wimboot.

EV Code Signing Certificate

Microsoft requires submitted UEFI binaries to be signed using an EV Code Signing certificate. These can be obtained from providers such as DigiCert at a cost of around US$2000 for a three-year certificate. Note that you must purchase the more expensive EV Code Signing Certificate for signing UEFI submissions; the regular Code Signing Certificate will not be accepted by Microsoft.

SafeNet eToken 5110+ FIPS

An Aladdin eToken

At the time of writing, DigiCert provides EV Code Signing Certificates in the form of an Aladdin/SafeNet eToken 5110+ FIPS USB hardware token. The token contains the certificate and the corresponding private key.

The token is almost (but not quite) supported by the various open source hardware token drivers available for Linux. As an interim measure, you can download and install the proprietary Safenet Authentication Client. The Safenet Authentication Client includes many features which you don't need or want (such as GUI tools and RPM post-installation scripts which cause Firefox to automatically attempt to use your certificate to identify you to every website that you visit): you probably want to disable or delete most of these after installation.

The only required portion of the Safenet Authentication Client software is the library /usr/lib64/libeToken.so. This library provides a standardised PKCS#11 API which allows tools such as opensc and openssl to use the hardware token.

The easiest way to test that your hardware token is working is to install opensc and run the command

  pkcs11-tool --module libeToken.so --list-objects

Changing the password

To change the password on the hardware token, run the command

  pkcs11-tool --module libeToken.so --change-pin

Extracting the certificate

To extract the certificate from your hardware token, first run

  pkcs11-tool --module libeToken.so --list-objects

and note the ID associated with your certificate. For example:

  Certificate Object, type = X.509 cert
    label:      Fen Systems Ltd.
    ID:         842ea4f497f6defa75e786015c2cdbfd12a18891

The certificate can then be extracted using the command

  pkcs11-tool --module libeToken.so --read-object --type cert --id 842ea4f497f6defa75e786015c2cdbfd12a18891 \
      | openssl x509 -inform DER -out codesigning.crt

(replacing “842ea4f497f6defa75e786015c2cdbfd12a18891” with the ID of your certificate). This will give you a file codesigning.crt containing your code signing certificate (but not the private key, which remains on the token). You can examine the contents of codesigning.crt using

  openssl x509 -in codesigning.crt -noout -text

Toolchain

A (tool)chain

To sign UEFI .cab files for submission to Microsoft you will need to also install

All of these are available prepackaged for Red Hat and SuSE derivatives (Fedora, CentOS, OpenSuSE, etc). You should not need to build any of these from source.

Microsoft Hardware Dev Center

You will need to sign up for an account at the Microsoft Partner Center and add your code signing certificate. This process will require you to sign a downloaded file SignableFile.bin: you can do this using

  osslsigncode -pkcs11module /usr/lib64/libeToken.so -h sha256 -askpass \
               -t http://timestamp.digicert.com -certs codesigning.crt \
               -key 842ea4f497f6defa75e786015c2cdbfd12a18891 \
               -in SignableFile.bin -out SignedFile.bin

(replacing “842ea4f497f6defa75e786015c2cdbfd12a18891” with the ID of your certificate as before).

Creating a UEFI signing submission

To create a UEFI signing submission, you must create a .cab file containing your (unsigned) .efi files. For example, you can create a submission.cab file containing ipxe.efi and snponly.efi using

  gcab -n -c submission.cab ipxe.efi snponly.efi

You can sign the submission.cab file using

  osslsigncode -pkcs11module /usr/lib64/libeToken.so -h sha256 -askpass \
               -t http://timestamp.digicert.com -certs codesigning.crt \
               -key 842ea4f497f6defa75e786015c2cdbfd12a18891 \
               -in submission.cab -out submission-signed.cab

(replacing “842ea4f497f6defa75e786015c2cdbfd12a18891” with the ID of your certificate as before).

Please note that version 2.6 of osslsigncode has a bug that causes it to generate invalid .cab files. You will need to use osslsigncode version 2.7 or later (or version 2.5 or earlier).

Submitting to Microsoft

Log in to the Microsoft Partner Center and choose “Submit New UEFI”.

Waiting

You may have to wait up to six months to get a response from Microsoft, during which time you may receive the occasional e-mail asking irrelevant questions. When the response finally arrives, it is likely to be an automated message stating

Thank you for your submission. We were unable to sign your EFI binaries. Common reasons for failure are:

  Including any files that are not EFI binaries (e.g. README)
  Invalid directory structure - packages should include only EFI files at the root-level of the package
  EFI Bytecode (EBC) drivers must pass the /ALIGN:32 flag to the Intel EBC linker

Observant readers will notice that this message does not give any information about why the signing process failed. If you attempt to follow up with Microsoft, you will discover that no-one at Microsoft knows how the signing process actually works.

Good luck!

Abandon all hope ye who submit here

1)
Do not try to use pesign for code signing, since it is broken and unable to perform signing using a hardware token. Use osslsigncode instead. In case pesign is ever fixed in future: you can configure NSS to use libeToken.so for pesign using
  sudo modutil -dbdir /etc/pki/pesign -add eToken -libfile /usr/lib64/libeToken.so
You can then list the certificates available for use by pesign using
  certutil -d /etc/pki/pesign -h eToken -L
  
and attempt signing using e.g.
  pesign -s -i unsigned.exe -o signed.exe -t "Fen Systems Ltd." -c "Fen Systems Ltd."
  
(replacing “Fen Systems Ltd.” with the name of your token as shown by certutil above).
appnote/etoken.txt · Last modified: 2023/08/31 10:58 by mcb30
Recent changes RSS feed CC Attribution-Share Alike 4.0 International Driven by DokuWiki
All uses of this content must include an attribution to the iPXE project and the URL https://ipxe.org
References to "iPXE" may not be altered or removed.