efikeygen — tool for generating keys for PE image signing for UEFI Secure Boot

       Peter Jones

Linux                                             Jun 3, 2020$                                      EFIKEYGEN(1)

efikeygen is a command line tool for generating keys and certificates to be used with pesign.  These  are
       standard  X.509  certificates,  and  can  potentially  be  generated  with any certificate creation tool.
       efikeygen generates certificates with sensible options set for a key to be used for PE image signing  for
       UEFI Secure Boot.

YubiKey
       Here's how you create both a CA certificate and keypair and a kernel signing certificate and keypair, and
       import them into yubikey PIV devices:

       Generate some keys:

       # Create a new CA key
       host:~$ efikeygen-C-nmy-ca-S\-c"CN=CAPerson,OU=MyOrg'sCA,O=MyOrg"\-uhttps://myorg.example.com/ca/

       # Create a kernel signing key
       host:~$ efikeygen-nmy-signer--signermy-ca-k\-c"CN=SecureBootSigner,OU=MyOrg'sCA,O=MyOrg"\-uhttps://myorg.example.com/ca/

       Save the CA to a yubikey:

       # Save it in a PKCS-12 bundle
       host:~$ pk12util-d/etc/pki/pesign-omyca.pk12-nmy-ca
       Enter password for PKCS12 file: <typeapasswordhere>
       Re-enter password: <typeitagainhere>
       pk12util: PKCS12 EXPORT SUCCESSFUL

       # Import the key into the yubikey
       host:~$ yubico-piv-tool-s9c-aimport-key-KPKCS12\-c-imyca.pk12
       Enter PEM pass phrase: <typethesamepasswordhere>
       Successfully imported a new private key.

       # Import the certificate into the yubikey
       host:~$ yubico-piv-tool-s9c-aimport-certificate\-KPKCS12-imyca.pk12
       Enter PEM pass phrase: <typethesamepasswordhere>
       Successfully imported a new certificate.

       # Remove the CA cert from the NSS database
       host:~$ certutil-d/etc/pki/pesign-D-nmy-ca

       Now
       switch yubikeys and import the kernel signer onto another one

       # Save it in a PKCS-12 bundle
       host:~$ pk12util-d/etc/pki/pesign-omysigner.pk12-nmy-signer
       Enter password for PKCS12 file: <typeapasswordhere>
       Re-enter password: <typeitagainhere>
       pk12util: PKCS12 EXPORT SUCCESSFUL

       # Import the key into the yubikey
       host:~$ yubico-piv-tool-s9c-aimport-key-KPKCS12\-imysigner.pk12
       Enter PEM pass phrase: <typethesamepasswordhere>
       Successfully imported a new private key.

       # Import the certificate into the yubikey
       host:~$ yubico-piv-tool-s9c-aimport-certificate\-KPKCS12-imysigner.pk12
       Enter PEM pass phrase: <typeitagainhere>
       Successfully imported a new certificate.

       # Remove the kernel signer from the NSS database
       host:~$ certutil-d/etc/pki/pesign-D-nmy-signer

       Once you have done this, you are prepared to sign binaries:

       # On each of these prompts, you have to enter the PIN for
       # the Yubikey.  This and the strange choice of names are
       # because PKCS-11 is horrible.  I'm sorry.
       host:~$ pesign-s-t'SecureBootSigner'\-c"CertificateforDigitalSignature"\-ishimx64.efi-oshimx64.signed.efi
       Enter Password or Pin for "Secure Boot Signer": <typethePINhere>
       Enter passphrase for private key: <typeitagainhere>
       Enter passphrase for private key: <typeitagainhere>

       Now
       verify that it worked:

       host:~$ pesign-ishimx64.signed.efi-l
       ---------------------------------------------
       certificate address is 0x7fbbae061468
       Content was not encrypted.
       Content is detached; signature cannot be verified.
       The signer's common name is Secure Boot Signer
       No signer email address.
       Signing time: Wed May 15, 2019
       There were certs or crls included.
       ---------------------------------------------

       Yay!

   OpenSC(smartcard)
       Here's how you create both a CA certificate and keypair and a kernel signing certificate and keypair, and
       import them into CardOS Smart Card devices supported by OpenSC:

       Optionally, format the card and initialize its PKCS15 data:

       # Format the card
       host:~$ cardos-tool-f
       Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
       card in administrative state, ok

       # Initialize the card's PKCS15 data, set the Security Officer PIN and unlock
       # code.
       host:~$ pkcs15-init-CT--so-pin$SOPIN--so-puk$SOPUK
       Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00

       # Initialize the user PIN and unlock code, and label the token
       host:~$ pkcs15-init-P-a1--pin$PIN--puk$PUK\--so-pin$SOPIN--so-puk$SOPUK\--label"myorg-sb-ca"
       Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00

       Generate
       keys and certificates:

       # Create a new CA key and certificate
       host:~$ efikeygen-C-nmy-ca-S\-c"CN=MyOrg'sSecureBootCA,OU=MyOrg'sCA,O=MyOrg"\-uhttps://myorg.example.com/ca/

       # Create a kernel signing key and cert
       host:~$ efikeygen-nmy-signer--signermy-ca-k\-c"CN=MyOrg'sSBSigner,OU=MyOrg'sCA,O=MyOrg"\-uhttps://myorg.example.com/ca/

       Get them onto the Smart Card

       # Save the CA key and certificate in a PKCS-12 bundle
       host:~$ pk12util-d/etc/pki/pesign-omy-ca.p12-nmy-caEnterpasswordforPKCS12file:<enterapasswordhere>
       Re-enter password: <typeitagainhere>
       pk12util: PKCS12 EXPORT SUCCESSFUL

       # Import the PKCS-12 bundle onto the card
       host:~$ pkcs15-init--store-private-keymy-ca.p12\--formatpkcs12--auth-id01\--pin$PIN--so-pin$SOPIN--so-puk$SOPUK
       Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
       Importing 1 certificates:
          0: /CN=My Org's Secure Boot CA

       # List the contents:
       host:~$ pkcs11-tool--moduleopensc-pkcs11.so-l--pin$PIN-O
       Using slot 1 with a present token (0x1)
       Private Key Object; RSA
         label:      Private Key
         ID:         de61fac87e0315352e7b9a487377ace2f6354d9b
         Usage:      sign
       Certificate Object, type = X.509 cert
         label:      /CN=My Org's Secure Boot CA
         ID:         de61fac87e0315352e7b9a487377ace2f6354d9b
       Public Key Object; RSA 2048 bits
         label:      /CN=My Org's Secure Boot CA
         ID:         de61fac87e0315352e7b9a487377ace2f6354d9b
         Usage:      encrypt, verify

       # Check and make sure nss can see the card
       host:~$ modutil-dbdir/etc/pki/pesign/-list
       Listing of PKCS #11 Modules
       -----------------------------------------------------------
         1. NSS Internal PKCS #11 Module
            slots: 2 slots attached
           status: loaded

            slot: NSS Internal Cryptographic Services
           token: NSS Generic Crypto Services

            slot: NSS User Private Key and Certificate Services
           token: NSS Certificate DB

         2. opensc-pkcs11
           library name: /usr/lib64/pkcs11/opensc-pkcs11.so
            slots: 2 slots attached
           status: loaded

            slot: Virtual hotplug slot
           token:

            slot: Generic Smart Card Reader Interface [Smart Card Read...
           token: OpenSC Card (myorg-sb-ca)
       -----------------------------------------------------------

       # Check and make sure NSS can see the certificate:
       host:~$ certutil-d/etc/pki/pesign-L\-h"OpenSCCard(myorg-sb-ca)"
       Certificate Nickname                             Trust Attributes
                                                        SSL,S/MIME,JAR/XPI

       Enter Password or Pin for "OpenSC Card (myorg-sb-ca)": <typethePINhere>
       OpenSC Card (myorg-sb-ca):/CN=My Org's Secure Boot CA    u,u,u

       # Remove the CA from the NSS database
       host:~$ certutil-d/etc/pki/pesign-D-nmy-ca

       Remember
       to switch cards and do the same thing with the signer, just as in the YubiKey example, then sign a binary
       with the signing key on a Smart Card and verify that it worked:

       # Sign the binary.  On each of these prompts, you have to enter
       # the PIN for the Smart Card.  This and the strange choice of
       # names are because PKCS-11 is horrible.  I'm sorry.
       host:~$ pesign-s-t"OpenSCCard(myorg-sb-signer)"\-c"OpenSCCard(myorg-sb-signer):/CN=MyOrg'sSBSigner"\-ishimx64.efi-oshimx64.signed.efi
       Enter Password or Pin for "My Org's SB Signer": <typethePINhere>
       Enter passphrase for private key: <typethePINhere>
       Enter passphrase for private key: <typethePINhere>

       # Verify that it worked:
       host:~$ pesign-ishimx64.signed.efi-l
       ---------------------------------------------
       certificate address is 0x7fbbae061468
       Content was not encrypted.
       Content is detached; signature cannot be verified.
       The signer's common name is My Org's SB Signer
       No signer email address.
       Signing time: Wed Jun 2, 2020
       There were certs or crls included.
       ---------------------------------------------

       Yay!

       efikeygen — tool for generating keys for PE image signing for UEFI Secure Boot

-C | --ca
               Create a CA certificate

       -k | --kernel
               Create a kernel signing certificate

               Not to be used for CA certificates

       -m | --module
               Create a module signing certificate

               Not to be used for CA certificates

       -S | --self-sign
               Create a self-signed certificate

       --signernickname
               Use the NSS certificate referred to by nickname as the issuing certificate

       -nnickname | -nicknamenickname
               Set the new certificate nickname in the NSS database to nickname-ccommon_name | --common-namecommon_name
               The  X.509  Common  Name  for the generated certificate.  This should be in rfc2253 syntax, i.e.:
               "CN=John Doe,OU=editing,O=New York Times,L=New York,ST=NY,C=US"

       -uurl | --urlurl
               URL for information regarding this certificate and objects signed with it.

       -sserial | --serialserial
               Serial number for use with this key.  A certificate is identified by its signer  and  its  serial
               number,  so it's best not to ever re-use this value with the same signer.  By default, this value
               will be generated at random.  It is not recommended to use this option to override that.

       -ddirectory | --dbdirdirectory
               The          directory           for           the           NSS           key           database
               (default: /etc/pki/pesign)

       -ttoken | --tokentoken
               The                NSS                token               name               to               use
               (default: pkcs11:token=NSS%20Certificate%20DB)

certutil(1), modutil(1), opensc-tool(1), pesign(1), pk12util(1), pkcs15-init(1), yubico-piv-tool(1),

       B. Kaliski, PKCS#7:CryptographicMessageSyntaxv1.5,  InternetEngineeringTaskForce,  RFC  2315,
       https://tools.ietf.org/html/rfc2315 , March 1998.

       K.  Moriarty,  M.  Nyström, S. Parkinson, A. Rusch, and M. Scott, PKCS#12:PersonalInformationExchangeSyntaxv1.1, InternetEngineeringTaskForce, RFC 7292, https://tools.ietf.org/html/rfc7292 , July 2014.

       PKCS11   Technical   Committee,    PKCS#11:CryptographicTokenInterfaceStandard,    OASIS,
       https://www.cryptsoft.com/pkcs11doc/.

efikeygen  ⟨-C |  -k |  -m⟩  ⟨-S |  --signernickname⟩  -nnickname-ccommon_name [-uurl] [-sserial]
                 [-ddirectory] [-ttoken]