1EFIKEYGEN(1) BSD General Commands Manual EFIKEYGEN(1)
2
4 efikeygen — tool for generating keys for PE image signing for UEFI Secure
5 Boot
6
8 efikeygen ⟨-C | -k | -m⟩ ⟨-S | --signer nickname⟩ -n nickname -c
9 common_name [-u url] [-s serial] [-d directory] [-t token]
10
12 efikeygen is a command line tool for generating keys and certificates to
13 be used with pesign. These are standard X.509 certificates, and can po‐
14 tentially be generated with any certificate creation tool. efikeygen
15 generates certificates with sensible options set for a key to be used for
16 PE image signing for UEFI Secure Boot.
17
20 -C | --ca
21 Create a CA certificate
22 -k | --kernel
24 Create a kernel signing certificate
25 Not to be used for CA certificates
27 -m | --module
29 Create a module signing certificate
30 Not to be used for CA certificates
32 -S | --self-sign
34 Create a self-signed certificate
35 --signer nickname
37 Use the NSS certificate referred to by nickname as the issuing
38 certificate
39 -n nickname | -nickname nickname
41 Set the new certificate nickname in the NSS database to nickname
42 -c common_name | --common-name common_name
44 The X.509 Common Name for the generated certificate. This should
45 be in rfc2253 syntax, i.e.:
46 "CN=John Doe,OU=editing,O=New York Times,L=New York,ST=NY,C=US"
47 -u url | --url url
49 URL for information regarding this certificate and objects signed
50 with it.
51 -s serial | --serial serial
53 Serial number for use with this key. A certificate is identified
54 by its signer and its serial number, so it's best not to ever re-
55 use this value with the same signer. By default, this value will
56 be generated at random. It is not recommended to use this option
57 to override that.
58 -d directory | --dbdir directory
60 The directory for the NSS key database
61 (default: /etc/pki/pesign)
62 -t token | --token token
64 The NSS token name to use
65 (default: pkcs11:token=NSS%20Certificate%20DB)
66
68 YubiKey
69 Here's how you create both a CA certificate and keypair and a kernel
70 signing certificate and keypair, and import them into yubikey PIV de‐
71 vices:
72 Generate some keys:
74 # Create a new CA key
76 host:~$ efikeygen -C -n my-ca -S \
77 -c "CN=CA Person,OU=My Org's CA,O=My Org" \
78 -u https://myorg.example.com/ca/
79 # Create a kernel signing key
81 host:~$ efikeygen -n my-signer --signer my-ca -k \
82 -c "CN=Secure Boot Signer,OU=My Org's CA,O=My Org" \
83 -u https://myorg.example.com/ca/
84 Save the CA to a yubikey:
86 # Save it in a PKCS-12 bundle
88 host:~$ pk12util -d /etc/pki/pesign -o myca.pk12 -n my-ca
89 Enter password for PKCS12 file: <type a password here>
90 Re-enter password: <type it again here>
91 pk12util: PKCS12 EXPORT SUCCESSFUL
92 # Import the key into the yubikey
94 host:~$ yubico-piv-tool -s 9c -a import-key -K PKCS12 \
95 -c -i myca.pk12
96 Enter PEM pass phrase: <type the same password here>
97 Successfully imported a new private key.
98 # Import the certificate into the yubikey
100 host:~$ yubico-piv-tool -s 9c -a import-certificate \
101 -K PKCS12 -i myca.pk12
102 Enter PEM pass phrase: <type the same password here>
103 Successfully imported a new certificate.
104 # Remove the CA cert from the NSS database
106 host:~$ certutil -d /etc/pki/pesign -D -n my-ca
107 Now
109 switch yubikeys and import the kernel signer onto another one
110 # Save it in a PKCS-12 bundle
112 host:~$ pk12util -d /etc/pki/pesign -o mysigner.pk12 -n my-signer
113 Enter password for PKCS12 file: <type a password here>
114 Re-enter password: <type it again here>
115 pk12util: PKCS12 EXPORT SUCCESSFUL
116 # Import the key into the yubikey
118 host:~$ yubico-piv-tool -s 9c -a import-key -K PKCS12 \
119 -i mysigner.pk12
120 Enter PEM pass phrase: <type the same password here>
121 Successfully imported a new private key.
122 # Import the certificate into the yubikey
124 host:~$ yubico-piv-tool -s 9c -a import-certificate \
125 -K PKCS12 -i mysigner.pk12
126 Enter PEM pass phrase: <type it again here>
127 Successfully imported a new certificate.
128 # Remove the kernel signer from the NSS database
130 host:~$ certutil -d /etc/pki/pesign -D -n my-signer
131 Once you have done this, you are prepared to sign binaries:
133 # On each of these prompts, you have to enter the PIN for
135 # the Yubikey. This and the strange choice of names are
136 # because PKCS-11 is horrible. I'm sorry.
137 host:~$ pesign -s -t 'Secure Boot Signer' \
138 -c "Certificate for Digital Signature" \
139 -i shimx64.efi -o shimx64.signed.efi
140 Enter Password or Pin for "Secure Boot Signer": <type the PIN here>
141 Enter passphrase for private key: <type it again here>
142 Enter passphrase for private key: <type it again here>
143 Now
145 verify that it worked:
146 host:~$ pesign -i shimx64.signed.efi -l
148 ---------------------------------------------
149 certificate address is 0x7fbbae061468
150 Content was not encrypted.
151 Content is detached; signature cannot be verified.
152 The signer's common name is Secure Boot Signer
153 No signer email address.
154 Signing time: Wed May 15, 2019
155 There were certs or crls included.
156 ---------------------------------------------
157 Yay!
159 OpenSC (smart card)
161 Here's how you create both a CA certificate and keypair and a kernel
162 signing certificate and keypair, and import them into CardOS Smart Card
163 devices supported by OpenSC:
164 Optionally, format the card and initialize its PKCS15 data:
166 # Format the card
168 host:~$ cardos-tool -f
169 Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
170 card in administrative state, ok
171 # Initialize the card's PKCS15 data, set the Security Officer PIN and unlock
173 # code.
174 host:~$ pkcs15-init -CT --so-pin $SOPIN --so-puk $SOPUK
175 Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
176 # Initialize the user PIN and unlock code, and label the token
178 host:~$ pkcs15-init -P -a 1 --pin $PIN --puk $PUK \
179 --so-pin $SOPIN --so-puk $SOPUK \
180 --label "myorg-sb-ca"
181 Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
182 Generate
184 keys and certificates:
185 # Create a new CA key and certificate
187 host:~$ efikeygen -C -n my-ca -S \
188 -c "CN=My Org's Secure Boot CA,OU=My Org's CA,O=My Org" \
189 -u https://myorg.example.com/ca/
190 # Create a kernel signing key and cert
192 host:~$ efikeygen -n my-signer --signer my-ca -k \
193 -c "CN=My Org's SB Signer,OU=My Org's CA,O=My Org"\
194 -u https://myorg.example.com/ca/
195 Get them onto the Smart Card
197 # Save the CA key and certificate in a PKCS-12 bundle
199 host:~$ pk12util -d /etc/pki/pesign -o my-ca.p12 -n my-ca
200 Enter password for PKCS12 file: <enter a password here>
201 Re-enter password: <type it again here>
202 pk12util: PKCS12 EXPORT SUCCESSFUL
203 # Import the PKCS-12 bundle onto the card
205 host:~$ pkcs15-init --store-private-key my-ca.p12 \
206 --format pkcs12 --auth-id 01 \
207 --pin $PIN --so-pin $SOPIN --so-puk $SOPUK
208 Using reader with a card: Generic Smart Card Reader Interface [Smart Card Reader Interface] (20070818000000000) 00 00
209 Importing 1 certificates:
210 0: /CN=My Org's Secure Boot CA
211 # List the contents:
213 host:~$ pkcs11-tool --module opensc-pkcs11.so -l --pin $PIN -O
214 Using slot 1 with a present token (0x1)
215 Private Key Object; RSA
216 label: Private Key
217 ID: de61fac87e0315352e7b9a487377ace2f6354d9b
218 Usage: sign
219 Certificate Object, type = X.509 cert
220 label: /CN=My Org's Secure Boot CA
221 ID: de61fac87e0315352e7b9a487377ace2f6354d9b
222 Public Key Object; RSA 2048 bits
223 label: /CN=My Org's Secure Boot CA
224 ID: de61fac87e0315352e7b9a487377ace2f6354d9b
225 Usage: encrypt, verify
226 # Check and make sure nss can see the card
228 host:~$ modutil -dbdir /etc/pki/pesign/ -list
229 Listing of PKCS #11 Modules
230 -----------------------------------------------------------
231 1. NSS Internal PKCS #11 Module
232 slots: 2 slots attached
233 status: loaded
234 slot: NSS Internal Cryptographic Services
236 token: NSS Generic Crypto Services
237 slot: NSS User Private Key and Certificate Services
239 token: NSS Certificate DB
240 2. opensc-pkcs11
242 library name: /usr/lib64/pkcs11/opensc-pkcs11.so
243 slots: 2 slots attached
244 status: loaded
245 slot: Virtual hotplug slot
247 token:
248 slot: Generic Smart Card Reader Interface [Smart Card Read...
250 token: OpenSC Card (myorg-sb-ca)
251 -----------------------------------------------------------
252 # Check and make sure NSS can see the certificate:
254 host:~$ certutil -d /etc/pki/pesign -L \
255 -h "OpenSC Card (myorg-sb-ca)"
256 Certificate Nickname Trust Attributes
257 SSL,S/MIME,JAR/XPI
258 Enter Password or Pin for "OpenSC Card (myorg-sb-ca)": <type the PIN here>
260 OpenSC Card (myorg-sb-ca):/CN=My Org's Secure Boot CA u,u,u
261 # Remove the CA from the NSS database
263 host:~$ certutil -d /etc/pki/pesign -D -n my-ca
264 Remember
266 to switch cards and do the same thing with the signer, just as in the Yu‐
267 biKey example, then sign a binary with the signing key on a Smart Card
268 and verify that it worked:
269 # Sign the binary. On each of these prompts, you have to enter
271 # the PIN for the Smart Card. This and the strange choice of
272 # names are because PKCS-11 is horrible. I'm sorry.
273 host:~$ pesign -s -t "OpenSC Card(myorg-sb-signer)" \
274 -c "OpenSC Card (myorg-sb-signer):/CN=My Org's SB Signer"\
275 -i shimx64.efi -o shimx64.signed.efi
276 Enter Password or Pin for "My Org's SB Signer": <type the PIN here>
277 Enter passphrase for private key: <type the PIN here>
278 Enter passphrase for private key: <type the PIN here>
279 # Verify that it worked:
281 host:~$ pesign -i shimx64.signed.efi -l
282 ---------------------------------------------
283 certificate address is 0x7fbbae061468
284 Content was not encrypted.
285 Content is detached; signature cannot be verified.
286 The signer's common name is My Org's SB Signer
287 No signer email address.
288 Signing time: Wed Jun 2, 2020
289 There were certs or crls included.
290 ---------------------------------------------
291 Yay!
293
295 B. Kaliski, PKCS #7: Cryptographic Message Syntax v1.5, Internet
296 Engineering Task Force, RFC 2315, https://tools.ietf.org/html/rfc2315 ,
297 March 1998.
298 K. Moriarty, M. Nyström, S. Parkinson, A. Rusch, and M. Scott, PKCS #12:
300 Personal Information Exchange Syntax v1.1, Internet Engineering Task
301 Force, RFC 7292, https://tools.ietf.org/html/rfc7292 , July 2014.
302 PKCS11 Technical Committee, PKCS#11: Cryptographic Token Interface
304 Standard, OASIS, https://www.cryptsoft.com/pkcs11doc/.
305
307 certutil(1), modutil(1), opensc-tool(1), pesign(1), pk12util(1),
308 pkcs15-init(1), yubico-piv-tool(1),
309
311 Peter Jones
312Linux Jun 3, 2020$ Linux