This is an old revision of the document!


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$500 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.

Aladdin eToken PRO 72k (Java)

An Aladdin eToken

At the time of writing, DigiCert provides EV Code Signing Certificates in the form of an Aladdin eToken PRO 72k (Java) 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:         3342cb0ff9b8e672bdcecbff80ebf89f9c785ce5

The certificate can then be extracted using the command

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

(replacing “3342cb0ff9b8e672bdcecbff80ebf89f9c785ce5” 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.

You will need to configure NSS to use libeToken.so for pesign using

  sudo modutil -dbdir /etc/pki/pesign -add eToken -libfile /usr/lib64/libeToken.so

You can list the certificates available for use by pesign using

  certutil -d /etc/pki/pesign -h eToken -L

Microsoft Hardware Dev Center

You will need to sign up for an account at the Microsoft Hardware Dev Center. The sign-up process will require you to sign a copy of winqual.exe: you can do this using

  pesign -s -i winqual.exe -o winqual-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).

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 -pkcs11engine /usr/lib64/openssl/engines/pkcs11.so \
               -pkcs11module /usr/lib64/libeToken.so -certs codesigning.crt \
               -h sha256 -askpass -t http://timestamp.digicert.com \
               -key 3342cb0ff9b8e672bdcecbff80ebf89f9c785ce5 \
               -in submission.cab -out submission-signed.cab

(replacing “3342cb0ff9b8e672bdcecbff80ebf89f9c785ce5” with the ID of your certificate as before).

Submitting to Microsoft

Log in to the Microsoft Hardware Dev Center and choose “Create UEFI submission”. You will unfortunately need to use Windows to upload the submission-signed.cab file, since the submission page uses Silverlight instead of a standard HTML form.1)

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)
Microsoft is special.
appnote/etoken.1494445555.txt.gz · Last modified: 2017/05/10 19:45 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.