1 U-Boot FIT Signature Verification
2 =================================
6 FIT supports hashing of images so that these hashes can be checked on
7 loading. This protects against corruption of the image. However it does not
8 prevent the substitution of one image for another.
10 The signature feature allows the hash to be signed with a private key such
11 that it can be verified using a public key later. Provided that the private
12 key is kept secret and the public key is stored in a non-volatile place,
13 any image can be verified in this way.
15 See verified-boot.txt for more general information on verified boot.
20 Some familiarity with public key cryptography is assumed in this section.
22 The procedure for signing is as follows:
24 - hash an image in the FIT
25 - sign the hash with a private key to produce a signature
26 - store the resulting signature in the FIT
28 The procedure for verification is:
31 - obtain the public key
32 - extract the signature from the FIT
33 - hash the image from the FIT
34 - verify (with the public key) that the extracted signature matches the
37 The signing is generally performed by mkimage, as part of making a firmware
38 image for the device. The verification is normally done in U-Boot on the
44 In principle any suitable algorithm can be used to sign and verify a hash.
45 At present only one class of algorithms is supported: SHA1 hashing with RSA.
46 This works by hashing the image to produce a 20-byte hash.
48 While it is acceptable to bring in large cryptographic libraries such as
49 openssl on the host side (e.g. mkimage), it is not desirable for U-Boot.
50 For the run-time verification side, it is important to keep code and data
51 size as small as possible.
53 For this reason the RSA image verification uses pre-processed public keys
54 which can be used with a very small amount of code - just some extraction
55 of data from the FDT and exponentiation mod n. Code size impact is a little
56 under 5KB on Tegra Seaboard, for example.
58 It is relatively straightforward to add new algorithms if required. If
59 another RSA variant is needed, then it can be added to the table in
60 image-sig.c. If another algorithm is needed (such as DSA) then it can be
61 placed alongside rsa.c, and its functions added to the table in image-sig.c
65 Creating an RSA key pair and certificate
66 ----------------------------------------
67 To create a new public/private key pair, size 2048 bits:
69 $ openssl genpkey -algorithm RSA -out keys/dev.key \
70 -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537
72 To create a certificate for this containing the public key:
74 $ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
76 If you like you can look at the public key also:
78 $ openssl rsa -in keys/dev.key -pubout
83 The following properties are required in the FIT's signature node(s) to
84 allow the signer to operate. These should be added to the .its file.
85 Signature nodes sit at the same level as hash nodes and are called
86 signature-1, signature-2, etc.
88 - algo: Algorithm name (e.g. "sha1,rsa2048")
90 - key-name-hint: Name of key to use for signing. The keys will normally be in
91 a single directory (parameter -k to mkimage). For a given key <name>, its
92 private key is stored in <name>.key and the certificate is stored in
95 When the image is signed, the following properties are added (mandatory):
97 - value: The signature data (e.g. 256 bytes for 2048-bit RSA)
99 When the image is signed, the following properties are optional:
101 - timestamp: Time when image was signed (standard Unix time_t format)
103 - signer-name: Name of the signer (e.g. "mkimage")
105 - signer-version: Version string of the signer (e.g. "2013.01")
107 - comment: Additional information about the signer or image
109 - padding: The padding algorithm, it may be pkcs-1.5 or pss,
110 if no value is provided we assume pkcs-1.5
112 For config bindings (see Signed Configurations below), the following
113 additional properties are optional:
115 - sign-images: A list of images to sign, each being a property of the conf
116 node that contains then. The default is "kernel,fdt" which means that these
117 two images will be looked up in the config and signed if present.
119 For config bindings, these properties are added by the signer:
121 - hashed-nodes: A list of nodes which were hashed by the signer. Each is
122 a string - the full path to node. A typical value might be:
124 hashed-nodes = "/", "/configurations/conf-1", "/images/kernel",
125 "/images/kernel/hash-1", "/images/fdt-1",
126 "/images/fdt-1/hash-1";
128 - hashed-strings: The start and size of the string region of the FIT that
131 Example: See sign-images.its for an example image tree source file and
132 sign-configs.its for config signing.
137 In order to verify an image that has been signed with a public key we need to
138 have a trusted public key. This cannot be stored in the signed image, since
139 it would be easy to alter. For this implementation we choose to store the
140 public key in U-Boot's control FDT (using CONFIG_OF_CONTROL).
142 Public keys should be stored as sub-nodes in a /signature node. Required
145 - algo: Algorithm name (e.g. "sha1,rsa2048")
147 Optional properties are:
149 - key-name-hint: Name of key used for signing. This is only a hint since it
150 is possible for the name to be changed. Verification can proceed by checking
151 all available signing keys until one matches.
153 - required: If present this indicates that the key must be verified for the
154 image / configuration to be considered valid. Only required keys are
155 normally verified by the FIT image booting algorithm. Valid values are
156 "image" to force verification of all images, and "conf" to force verification
157 of the selected configuration (which then relies on hashes in the images to
160 Each signing algorithm has its own additional properties.
162 For RSA the following are mandatory:
164 - rsa,num-bits: Number of key bits (e.g. 2048)
165 - rsa,modulus: Modulus (N) as a big-endian multi-word integer
166 - rsa,exponent: Public exponent (E) as a 64 bit unsigned integer
167 - rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer
168 - rsa,n0-inverse: -1 / modulus[0] mod 2^32
171 Signed Configurations
172 ---------------------
173 While signing images is useful, it does not provide complete protection
174 against several types of attack. For example, it it possible to create a
175 FIT with the same signed images, but with the configuration changed such
176 that a different one is selected (mix and match attack). It is also possible
177 to substitute a signed image from an older FIT version into a newer FIT
180 As an example, consider this FIT:
185 data = <data for kernel1>
187 algo = "sha1,rsa2048";
188 value = <...kernel signature 1...>
192 data = <data for kernel2>
194 algo = "sha1,rsa2048";
195 value = <...kernel signature 2...>
199 data = <data for fdt1>;
201 algo = "sha1,rsa2048";
202 vaue = <...fdt signature 1...>
206 data = <data for fdt2>;
208 algo = "sha1,rsa2048";
209 vaue = <...fdt signature 2...>
226 Since both kernels are signed it is easy for an attacker to add a new
227 configuration 3 with kernel 1 and fdt 2:
245 With signed images, nothing protects against this. Whether it gains an
246 advantage for the attacker is debatable, but it is not secure.
248 To solve this problem, we support signed configurations. In this case it
249 is the configurations that are signed, not the image. Each image has its
250 own hash, and we include the hash in the configuration signature.
252 So the above example is adjusted to look like this:
257 data = <data for kernel1>
260 value = <...kernel hash 1...>
264 data = <data for kernel2>
267 value = <...kernel hash 2...>
271 data = <data for fdt1>;
274 value = <...fdt hash 1...>
278 data = <data for fdt2>;
281 value = <...fdt hash 2...>
291 algo = "sha1,rsa2048";
292 value = <...conf 1 signature...>;
299 algo = "sha1,rsa2048";
300 value = <...conf 1 signature...>;
307 You can see that we have added hashes for all images (since they are no
308 longer signed), and a signature to each configuration. In the above example,
309 mkimage will sign configurations/conf-1, the kernel and fdt that are
310 pointed to by the configuration (/images/kernel-1, /images/kernel-1/hash-1,
311 /images/fdt-1, /images/fdt-1/hash-1) and the root structure of the image
312 (so that it isn't possible to add or remove root nodes). The signature is
313 written into /configurations/conf-1/signature-1/value. It can easily be
314 verified later even if the FIT has been signed with other keys in the
320 FITs are verified when loaded. After the configuration is selected a list
321 of required images is produced. If there are 'required' public keys, then
322 each image must be verified against those keys. This means that every image
323 that might be used by the target needs to be signed with 'required' keys.
325 This happens automatically as part of a bootm command when FITs are used.
328 Enabling FIT Verification
329 -------------------------
330 In addition to the options to enable FIT itself, the following CONFIGs must
333 CONFIG_FIT_SIGNATURE - enable signing and verification in FITs
334 CONFIG_RSA - enable RSA algorithm for signing
336 WARNING: When relying on signed FIT images with required signature check
337 the legacy image format is default disabled by not defining
338 CONFIG_LEGACY_IMAGE_FORMAT
342 An easy way to test signing and verification is to use the test script
343 provided in test/vboot/vboot_test.sh. This uses sandbox (a special version
344 of U-Boot which runs under Linux) to show the operation of a 'bootm'
345 command loading and verifying images.
347 A sample run is show below:
349 $ make O=sandbox sandbox_config
351 $ O=sandbox ./test/vboot/vboot_test.sh
352 Simple Verified Boot Test
353 =========================
355 Please see doc/uImage.FIT/verified-boot.txt for more information
357 /home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000
360 Build FIT with signed images
361 Test Verified Boot Run: unsigned signatures:: OK
363 Test Verified Boot Run: signed images: OK
364 Build FIT with signed configuration
365 Test Verified Boot Run: unsigned config: OK
367 Test Verified Boot Run: signed config: OK
368 check signed config on the host
371 Test Verified Boot Run: signed config: OK
372 Test Verified Boot Run: signed config with bad hash: OK
374 Build FIT with signed images
375 Test Verified Boot Run: unsigned signatures:: OK
377 Test Verified Boot Run: signed images: OK
378 Build FIT with signed configuration
379 Test Verified Boot Run: unsigned config: OK
381 Test Verified Boot Run: signed config: OK
382 check signed config on the host
385 Test Verified Boot Run: signed config: OK
386 Test Verified Boot Run: signed config with bad hash: OK
391 Hardware Signing with PKCS#11
392 -----------------------------
394 Securely managing private signing keys can challenging, especially when the
395 keys are stored on the file system of a computer that is connected to the
396 Internet. If an attacker is able to steal the key, they can sign malicious FIT
397 images which will appear genuine to your devices.
399 An alternative solution is to keep your signing key securely stored on hardware
400 device like a smartcard, USB token or Hardware Security Module (HSM) and have
401 them perform the signing. PKCS#11 is standard for interfacing with these crypto
405 Smartcard/USB token/HSM which can work with the pkcs11 engine
407 libp11 (provides pkcs11 engine)
408 p11-kit (recommended to simplify setup)
409 opensc (for smartcards and smartcard like USB devices)
410 gnutls (recommended for key generation, p11tool)
412 The following examples use the Nitrokey Pro. Instructions for other devices may vary.
414 Notes on pkcs11 engine setup:
416 Make sure p11-kit, opensc are installed and that p11-kit is setup to use opensc.
417 /usr/share/p11-kit/modules/opensc.module should be present on your system.
420 Generating Keys On the Nitrokey:
424 Reader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00
425 Application ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
426 Version ..........: 2.1
427 Manufacturer .....: ZeitControl
428 Serial number ....: xxxxxxxx
429 Name of cardholder: [not set]
430 Language prefs ...: de
431 Sex ..............: unspecified
432 URL of public key : [not set]
433 Login data .......: [not set]
434 Signature PIN ....: forced
435 Key attributes ...: rsa2048 rsa2048 rsa2048
436 Max. PIN lengths .: 32 32 32
437 PIN retry counter : 3 0 3
438 Signature counter : 0
439 Signature key ....: [none]
440 Encryption key....: [none]
441 Authentication key: [none]
442 General key info..: [none]
445 Make off-card backup of encryption key? (Y/n) n
447 Please note that the factory settings of the PINs are
448 PIN = '123456' Admin PIN = '12345678'
449 You should change them using the command --change-pin
451 What keysize do you want for the Signature key? (2048) 4096
452 The card will now be re-configured to generate a key of 4096 bits
453 Note: There is no guarantee that the card supports the requested size.
454 If the key generation does not succeed, please check the
455 documentation of your card to see what sizes are allowed.
456 What keysize do you want for the Encryption key? (2048) 4096
457 The card will now be re-configured to generate a key of 4096 bits
458 What keysize do you want for the Authentication key? (2048) 4096
459 The card will now be re-configured to generate a key of 4096 bits
460 Please specify how long the key should be valid.
461 0 = key does not expire
462 <n> = key expires in n days
463 <n>w = key expires in n weeks
464 <n>m = key expires in n months
465 <n>y = key expires in n years
466 Key is valid for? (0)
467 Key does not expire at all
468 Is this correct? (y/N) y
470 GnuPG needs to construct a user ID to identify your key.
473 Email address: john.doe@email.com
475 You selected this USER-ID:
476 "John Doe <john.doe@email.com>"
478 Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o
481 Using p11tool to get the token URL:
483 Depending on system configuration, gpg-agent may need to be killed first.
485 $ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens
487 URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29
488 Label: OpenPGP card (User PIN (sig))
490 Manufacturer: ZeitControl
491 Model: PKCS#15 emulated
497 URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29
498 Label: OpenPGP card (User PIN)
500 Manufacturer: ZeitControl
501 Model: PKCS#15 emulated
505 Use the portion of the signature token URL after "pkcs11:" as the keydir argument (-k) to mkimage below.
508 Use the URL of the token to list the private keys:
510 $ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \
511 "pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29"
512 Token 'OpenPGP card (User PIN (sig))' with URL 'pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29' requires user PIN
515 URL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29;id=%01;object=Signature%20key;type=private
518 Flags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE;
521 Use the label, in this case "Signature key" as the key-name-hint in your FIT.
524 $ ./tools/mkimage -f fit-image.its fitImage
527 Sign the fitImage with the hardware key:
529 $ ./tools/mkimage -F -k \
530 "model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \
531 -K u-boot.dtb -N pkcs11 -r fitImage
536 - Roll-back protection using a TPM is done using the tpm command. This can
537 be scripted, but we might consider a default way of doing this, built into
543 - Add support for other RSA/SHA variants, such as rsa4096,sha512.
544 - Other algorithms besides RSA
545 - More sandbox tests for failure modes
546 - Passwords for keys/certificates
547 - Perhaps implement OAEP
548 - Enhance bootm to permit scripted signature verification (so that a script
549 can verify an image but not actually boot it)