===== 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 [[:start|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 [[https://www.digicert.com/friends/sysdev/|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 ====

{{ :clipart:etoken.jpeg?160x120|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 [[https://www.digicert.com/StaticFiles/SAC_10_0_Linux_Post_GA.zip|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 ''[[https://github.com/OpenSC/OpenSC/wiki|opensc]]'' and ''[[https://www.openssl.org|openssl]]'' to use the hardware token.

The easiest way to test that your hardware token is working is to install ''[[https://github.com/OpenSC/OpenSC/wiki|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 ====

{{ :clipart:chain.jpeg?300x180|A (tool)chain}}

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

  * ''[[http://ftp.gnome.org/pub/GNOME/sources/gcab|gcab]]''
  * ''[[https://www.openssl.org|openssl]]''
  * ''[[https://github.com/OpenSC/OpenSC/wiki/Engine-pkcs11-quickstart|engine_pkcs11]]''
  * ''[[http://sourceforge.net/projects/osslsigncode/|osslsigncode]]''((Do not try to use ''pesign'' for code signing, since it is [[https://github.com/rhboot/pesign/issues/105|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).
))


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 [[https://partner.microsoft.com|Microsoft Partner Center]] and [[https://partner.microsoft.com/en-us/dashboard/account/managecertificates|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 ''[[http://boot.ipxe.org/ipxe.efi|ipxe.efi]]'' and ''[[http://boot.ipxe.org/snponly.efi|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 [[https://github.com/mtrojnar/osslsigncode/issues/289|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 [[https://partner.microsoft.com/en-us/dashboard/hardware/filesign|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!

{{ :clipart:dragon.png?268x264 |Abandon all hope ye who submit here}}