doc/uImage.FIT/signature.txt

   1 U-Boot FIT Signature Verification
   2 =================================
   3
   4 Introduction
   5 ------------
   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.
   9
  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.
  14
  15 See verified-boot.txt for more general information on verified boot.
  16
  17
  18 Concepts
  19 --------
  20 Some familiarity with public key cryptography is assumed in this section.
  21
  22 The 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
  28 The 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
  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
  39 device.
  40
  41
  42 Algorithms
  43 ----------
  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.
  47
  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.
  52
  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.
  57
  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
  62 also.
  63
  64
  65 Creating an RSA key and certificate
  66 -----------------------------------
  67 To create a new public key, size 2048 bits:
  68
  69 $ openssl genrsa -F4 -out keys/dev.key 2048
  70
  71 To create a certificate for this:
  72
  73 $ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt
  74
  75 If you like you can look at the public key also:
  76
  77 $ openssl rsa -in keys/dev.key -pubout
  78
  79
  80 Device Tree Bindings
  81 --------------------
  82 The following properties are required in the FIT's signature node(s) to
  83 allow thes signer to operate. These should be added to the .its file.
  84 Signature nodes sit at the same level as hash nodes and are called
  85 signature@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
  90 a single directory (parameter -k to mkimage). For a given key <name>, its
  91 private key is stored in <name>.key and the certificate is stored in
  92 <name>.crt.
  93
  94 When 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
  98 When 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
 109 Example: See sign-images.its for an example image tree source file.
 110
 111
 112 Public Key Storage
 113 ------------------
 114 In order to verify an image that has been signed with a public key we need to
 115 have a trusted public key. This cannot be stored in the signed image, since
 116 it would be easy to alter. For this implementation we choose to store the
 117 public key in U-Boot's control FDT (using CONFIG_OF_CONTROL).
 118
 119 Public keys should be stored as sub-nodes in a /signature node. Required
 120 properties are:
 121
 122 - algo: Algorithm name (e.g. "sha1,rs2048")
 123
 124 Optional properties are:
 125
 126 - key-name-hint: Name of key used for signing. This is only a hint since it
 127 is possible for the name to be changed. Verification can proceed by checking
 128 all available signing keys until one matches.
 129
 130 - required: If present this indicates that the key must be verified for the
 131 image / configuration to be considered valid. Only required keys are
 132 normally verified by the FIT image booting algorithm. Valid values are
 133 "image" to force verification of all images, and "conf" to force verfication
 134 of the selected configuration (which then relies on hashes in the images to
 135 verify those).
 136
 137 Each signing algorithm has its own additional properties.
 138
 139 For 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
 147 Verification
 148 ------------
 149 FITs are verified when loaded. After the configuration is selected a list
 150 of required images is produced. If there are 'required' public keys, then
 151 each image must be verified against those keys. This means that every image
 152 that might be used by the target needs to be signed with 'required' keys.
 153
 154 This happens automatically as part of a bootm command when FITs are used.
 155
 156
 157 Enabling FIT Verification
 158 -------------------------
 159 In addition to the options to enable FIT itself, the following CONFIGs must
 160 be enabled:
 161
 162 CONFIG_FIT_SIGNATURE - enable signing and verfication in FITs
 163 CONFIG_RSA - enable RSA algorithm for signing
 164
 165
 166 Testing
 167 -------
 168 An easy way to test signing and verfication is to use the test script
 169 provided in test/vboot/vboot_test.sh. This uses sandbox (a special version
 170 of U-Boot which runs under Linux) to show the operation of a 'bootm'
 171 command loading and verifying images.
 172
 173 A sample run is show below:
 174
 175 $ make O=sandbox sandbox_config
 176 $ make O=sandbox
 177 $ O=sandbox ./test/vboot/vboot_test.sh
 178 Simple Verified Boot Test
 179 =========================
 180
 181 Please see doc/uImage.FIT/verified-boot.txt for more information
 182
 183 Build keys
 184 Build FIT with signed images
 185 Test Verified Boot Run: unsigned signatures:: OK
 186 Sign images
 187 Test Verified Boot Run: signed images: OK
 188 Build FIT with signed configuration
 189 Test Verified Boot Run: unsigned config: OK
 190 Sign images
 191 Test Verified Boot Run: signed config: OK
 192
 193 Test passed
 194
 195
 196 Future Work
 197 -----------
 198 - Roll-back protection using a TPM is done using the tpm command. This can
 199 be scripted, but we might consider a default way of doing this, built into
 200 bootm.
 201
 202
 203 Possible 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
 211 can verify an image but not actually boot it)
 212
 213
 214 Simon Glass
 215 sjg@chromium.org
 216 1-1-13