EFIKEYGEN(1) General Commands Manual EFIKEYGEN(1) NAME efikeygen - tool for generating keys for PE image signing for UEFI Secure Boot SYNOPSIS efikeygen <-C | -k | -m> <-S | --signer nickname> -n nickname -c common_name [-u url] [-s serial] [-d directory] [-t token] DESCRIPTION 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. OPTIONS -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 --signer nickname Use the NSS certificate referred to by nickname as the issuing certificate -n nickname | -nickname nickname Set the new certificate nickname in the NSS database to nickname -c common_name | --common-name common_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" -u url | --url url URL for information regarding this certificate and objects signed with it. -s serial | --serial serial 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. -d directory | --dbdir directory The directory for the NSS key database (default: /etc/pki/pesign) -t token | --token token The NSS token name to use (default: pkcs11:token=NSS%20Certificate%20DB) EXAMPLES 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 -n my-ca -S \ -c "CN=CA Person,OU=My Org's CA,O=My Org" \ -u https://myorg.example.com/ca/ # Create a kernel signing key host:~$ efikeygen -n my-signer --signer my-ca -k \ -c "CN=Secure Boot Signer,OU=My Org's CA,O=My Org" \ -u https://myorg.example.com/ca/ Save the CA to a yubikey: # Save it in a PKCS-12 bundle host:~$ pk12util -d /etc/pki/pesign -o myca.pk12 -n my-ca Enter password for PKCS12 file: Re-enter password: pk12util: PKCS12 EXPORT SUCCESSFUL # Import the key into the yubikey host:~$ yubico-piv-tool -s 9c -a import-key -K PKCS12 \ -c -i myca.pk12 Enter PEM pass phrase: Successfully imported a new private key. # Import the certificate into the yubikey host:~$ yubico-piv-tool -s 9c -a import-certificate \ -K PKCS12 -i myca.pk12 Enter PEM pass phrase: Successfully imported a new certificate. # Remove the CA cert from the NSS database host:~$ certutil -d /etc/pki/pesign -D -n my-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 -o mysigner.pk12 -n my-signer Enter password for PKCS12 file: Re-enter password: pk12util: PKCS12 EXPORT SUCCESSFUL # Import the key into the yubikey host:~$ yubico-piv-tool -s 9c -a import-key -K PKCS12 \ -i mysigner.pk12 Enter PEM pass phrase: Successfully imported a new private key. # Import the certificate into the yubikey host:~$ yubico-piv-tool -s 9c -a import-certificate \ -K PKCS12 -i mysigner.pk12 Enter PEM pass phrase: Successfully imported a new certificate. # Remove the kernel signer from the NSS database host:~$ certutil -d /etc/pki/pesign -D -n my-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 'Secure Boot Signer' \ -c "Certificate for Digital Signature" \ -i shimx64.efi -o shimx64.signed.efi Enter Password or Pin for "Secure Boot Signer": Enter passphrase for private key: Enter passphrase for private key: Now verify that it worked: host:~$ pesign -i shimx64.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 (smart card) 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 -a 1 --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 -n my-ca -S \ -c "CN=My Org's Secure Boot CA,OU=My Org's CA,O=My Org" \ -u https://myorg.example.com/ca/ # Create a kernel signing key and cert host:~$ efikeygen -n my-signer --signer my-ca -k \ -c "CN=My Org's SB Signer,OU=My Org's CA,O=My Org"\ -u https://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 -o my-ca.p12 -n my-ca Enter password for PKCS12 file: Re-enter password: pk12util: PKCS12 EXPORT SUCCESSFUL # Import the PKCS-12 bundle onto the card host:~$ pkcs15-init --store-private-key my-ca.p12 \ --format pkcs12 --auth-id 01 \ --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 --module opensc-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 "OpenSC Card (myorg-sb-ca)" Certificate Nickname Trust Attributes SSL,S/MIME,JAR/XPI Enter Password or Pin for "OpenSC Card (myorg-sb-ca)": 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 -n my-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 "OpenSC Card(myorg-sb-signer)" \ -c "OpenSC Card (myorg-sb-signer):/CN=My Org's SB Signer"\ -i shimx64.efi -o shimx64.signed.efi Enter Password or Pin for "My Org's SB Signer": Enter passphrase for private key: Enter passphrase for private key: # Verify that it worked: host:~$ pesign -i shimx64.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! STANDARDS B. Kaliski, PKCS #7: Cryptographic Message Syntax v1.5, Internet Engineering Task Force, RFC 2315, https://tools.ietf.org/html/rfc2315 , March 1998. K. Moriarty, M. Nystrom, S. Parkinson, A. Rusch, and M. Scott, PKCS #12: Personal Information Exchange Syntax v1.1, Internet Engineering Task Force, RFC 7292, https://tools.ietf.org/html/rfc7292 , July 2014. PKCS11 Technical Committee, PKCS#11: Cryptographic Token Interface Standard, OASIS, https://www.cryptsoft.com/pkcs11doc/. SEE ALSO certutil(1), modutil(1), opensc-tool(1), pesign(1), pk12util(1), pkcs15-init(1), yubico-piv-tool(1), AUTHORS Peter Jones Linux June 3, 2020 Linux