Provided by: pesign_116-7_amd64 
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: <type a password here>
Re-enter password: <type it again here>
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: <type the same password here>
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: <type the same password here>
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: <type a password here>
Re-enter password: <type it again here>
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: <type the same password here>
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: <type it again here>
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": <type the PIN here>
Enter passphrase for private key: <type it again here>
Enter passphrase for private key: <type it again here>
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: <enter a password here>
Re-enter password: <type it again here>
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)": <type the PIN here>
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": <type the PIN here>
Enter passphrase for private key: <type the PIN here>
Enter passphrase for private key: <type the PIN here>
# 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. Nyström, 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