1U-Boot FIT Signature Verification 2================================= 3 4Introduction 5------------ 6FIT supports hashing of images so that these hashes can be checked on 7loading. This protects against corruption of the image. However it does not 8prevent the substitution of one image for another. 9 10The signature feature allows the hash to be signed with a private key such 11that it can be verified using a public key later. Provided that the private 12key is kept secret and the public key is stored in a non-volatile place, 13any image can be verified in this way. 14 15See verified-boot.txt for more general information on verified boot. 16 17 18Concepts 19-------- 20Some familiarity with public key cryptography is assumed in this section. 21 22The procedure for signing is as follows: 23 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 27 28The procedure for verification is: 29 30 - read the FIT 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 35 hash 36 37The signing is generally performed by mkimage, as part of making a firmware 38image for the device. The verification is normally done in U-Boot on the 39device. 40 41 42Algorithms 43---------- 44In principle any suitable algorithm can be used to sign and verify a hash. 45At present only one class of algorithms is supported: SHA1 hashing with RSA. 46This works by hashing the image to produce a 20-byte hash. 47 48While it is acceptable to bring in large cryptographic libraries such as 49openssl on the host side (e.g. mkimage), it is not desirable for U-Boot. 50For the run-time verification side, it is important to keep code and data 51size as small as possible. 52 53For this reason the RSA image verification uses pre-processed public keys 54which can be used with a very small amount of code - just some extraction 55of data from the FDT and exponentiation mod n. Code size impact is a little 56under 5KB on Tegra Seaboard, for example. 57 58It is relatively straightforward to add new algorithms if required. If 59another RSA variant is needed, then it can be added to the table in 60image-sig.c. If another algorithm is needed (such as DSA) then it can be 61placed alongside rsa.c, and its functions added to the table in image-sig.c 62also. 63 64 65Creating an RSA key and certificate 66----------------------------------- 67To create a new public key, size 2048 bits: 68 69$ openssl genrsa -F4 -out keys/dev.key 2048 70 71To create a certificate for this: 72 73$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt 74 75If you like you can look at the public key also: 76 77$ openssl rsa -in keys/dev.key -pubout 78 79 80Device Tree Bindings 81-------------------- 82The following properties are required in the FIT's signature node(s) to 83allow thes signer to operate. These should be added to the .its file. 84Signature nodes sit at the same level as hash nodes and are called 85signature@1, signature@2, etc. 86 87- algo: Algorithm name (e.g. "sha1,rs2048") 88 89- key-name-hint: Name of key to use for signing. The keys will normally be in 90a single directory (parameter -k to mkimage). For a given key <name>, its 91private key is stored in <name>.key and the certificate is stored in 92<name>.crt. 93 94When the image is signed, the following properties are added (mandatory): 95 96- value: The signature data (e.g. 256 bytes for 2048-bit RSA) 97 98When the image is signed, the following properties are optional: 99 100- timestamp: Time when image was signed (standard Unix time_t format) 101 102- signer-name: Name of the signer (e.g. "mkimage") 103 104- signer-version: Version string of the signer (e.g. "2013.01") 105 106- comment: Additional information about the signer or image 107 108 109Example: See sign-images.its for an example image tree source file. 110 111 112Public Key Storage 113------------------ 114In order to verify an image that has been signed with a public key we need to 115have a trusted public key. This cannot be stored in the signed image, since 116it would be easy to alter. For this implementation we choose to store the 117public key in U-Boot's control FDT (using CONFIG_OF_CONTROL). 118 119Public keys should be stored as sub-nodes in a /signature node. Required 120properties are: 121 122- algo: Algorithm name (e.g. "sha1,rs2048") 123 124Optional properties are: 125 126- key-name-hint: Name of key used for signing. This is only a hint since it 127is possible for the name to be changed. Verification can proceed by checking 128all available signing keys until one matches. 129 130- required: If present this indicates that the key must be verified for the 131image / configuration to be considered valid. Only required keys are 132normally verified by the FIT image booting algorithm. Valid values are 133"image" to force verification of all images, and "conf" to force verfication 134of the selected configuration (which then relies on hashes in the images to 135verify those). 136 137Each signing algorithm has its own additional properties. 138 139For RSA the following are mandatory: 140 141- rsa,num-bits: Number of key bits (e.g. 2048) 142- rsa,modulus: Modulus (N) as a big-endian multi-word integer 143- rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer 144- rsa,n0-inverse: -1 / modulus[0] mod 2^32 145 146 147Verification 148------------ 149FITs are verified when loaded. After the configuration is selected a list 150of required images is produced. If there are 'required' public keys, then 151each image must be verified against those keys. This means that every image 152that might be used by the target needs to be signed with 'required' keys. 153 154This happens automatically as part of a bootm command when FITs are used. 155 156 157Enabling FIT Verification 158------------------------- 159In addition to the options to enable FIT itself, the following CONFIGs must 160be enabled: 161 162CONFIG_FIT_SIGNATURE - enable signing and verfication in FITs 163CONFIG_RSA - enable RSA algorithm for signing 164 165 166Testing 167------- 168An easy way to test signing and verfication is to use the test script 169provided in test/vboot/vboot_test.sh. This uses sandbox (a special version 170of U-Boot which runs under Linux) to show the operation of a 'bootm' 171command loading and verifying images. 172 173A sample run is show below: 174 175$ make O=sandbox sandbox_config 176$ make O=sandbox 177$ O=sandbox ./test/vboot/vboot_test.sh 178Simple Verified Boot Test 179========================= 180 181Please see doc/uImage.FIT/verified-boot.txt for more information 182 183Build keys 184Build FIT with signed images 185Test Verified Boot Run: unsigned signatures:: OK 186Sign images 187Test Verified Boot Run: signed images: OK 188Build FIT with signed configuration 189Test Verified Boot Run: unsigned config: OK 190Sign images 191Test Verified Boot Run: signed config: OK 192 193Test passed 194 195 196Future Work 197----------- 198- Roll-back protection using a TPM is done using the tpm command. This can 199be scripted, but we might consider a default way of doing this, built into 200bootm. 201 202 203Possible Future Work 204-------------------- 205- Add support for other RSA/SHA variants, such as rsa4096,sha512. 206- Other algorithms besides RSA 207- More sandbox tests for failure modes 208- Passwords for keys/certificates 209- Perhaps implement OAEP 210- Enhance bootm to permit scripted signature verification (so that a script 211can verify an image but not actually boot it) 212 213 214Simon Glass 215sjg@chromium.org 2161-1-13 217