13e569a6bSSimon GlassU-Boot FIT Signature Verification 23e569a6bSSimon Glass================================= 33e569a6bSSimon Glass 43e569a6bSSimon GlassIntroduction 53e569a6bSSimon Glass------------ 63e569a6bSSimon GlassFIT supports hashing of images so that these hashes can be checked on 73e569a6bSSimon Glassloading. This protects against corruption of the image. However it does not 83e569a6bSSimon Glassprevent the substitution of one image for another. 93e569a6bSSimon Glass 103e569a6bSSimon GlassThe signature feature allows the hash to be signed with a private key such 113e569a6bSSimon Glassthat it can be verified using a public key later. Provided that the private 123e569a6bSSimon Glasskey is kept secret and the public key is stored in a non-volatile place, 133e569a6bSSimon Glassany image can be verified in this way. 143e569a6bSSimon Glass 153e569a6bSSimon GlassSee verified-boot.txt for more general information on verified boot. 163e569a6bSSimon Glass 173e569a6bSSimon Glass 183e569a6bSSimon GlassConcepts 193e569a6bSSimon Glass-------- 203e569a6bSSimon GlassSome familiarity with public key cryptography is assumed in this section. 213e569a6bSSimon Glass 223e569a6bSSimon GlassThe procedure for signing is as follows: 233e569a6bSSimon Glass 243e569a6bSSimon Glass - hash an image in the FIT 253e569a6bSSimon Glass - sign the hash with a private key to produce a signature 263e569a6bSSimon Glass - store the resulting signature in the FIT 273e569a6bSSimon Glass 283e569a6bSSimon GlassThe procedure for verification is: 293e569a6bSSimon Glass 303e569a6bSSimon Glass - read the FIT 313e569a6bSSimon Glass - obtain the public key 323e569a6bSSimon Glass - extract the signature from the FIT 333e569a6bSSimon Glass - hash the image from the FIT 343e569a6bSSimon Glass - verify (with the public key) that the extracted signature matches the 353e569a6bSSimon Glass hash 363e569a6bSSimon Glass 373e569a6bSSimon GlassThe signing is generally performed by mkimage, as part of making a firmware 383e569a6bSSimon Glassimage for the device. The verification is normally done in U-Boot on the 393e569a6bSSimon Glassdevice. 403e569a6bSSimon Glass 413e569a6bSSimon Glass 423e569a6bSSimon GlassAlgorithms 433e569a6bSSimon Glass---------- 443e569a6bSSimon GlassIn principle any suitable algorithm can be used to sign and verify a hash. 453e569a6bSSimon GlassAt present only one class of algorithms is supported: SHA1 hashing with RSA. 463e569a6bSSimon GlassThis works by hashing the image to produce a 20-byte hash. 473e569a6bSSimon Glass 483e569a6bSSimon GlassWhile it is acceptable to bring in large cryptographic libraries such as 493e569a6bSSimon Glassopenssl on the host side (e.g. mkimage), it is not desirable for U-Boot. 503e569a6bSSimon GlassFor the run-time verification side, it is important to keep code and data 513e569a6bSSimon Glasssize as small as possible. 523e569a6bSSimon Glass 533e569a6bSSimon GlassFor this reason the RSA image verification uses pre-processed public keys 543e569a6bSSimon Glasswhich can be used with a very small amount of code - just some extraction 553e569a6bSSimon Glassof data from the FDT and exponentiation mod n. Code size impact is a little 563e569a6bSSimon Glassunder 5KB on Tegra Seaboard, for example. 573e569a6bSSimon Glass 583e569a6bSSimon GlassIt is relatively straightforward to add new algorithms if required. If 593e569a6bSSimon Glassanother RSA variant is needed, then it can be added to the table in 603e569a6bSSimon Glassimage-sig.c. If another algorithm is needed (such as DSA) then it can be 613e569a6bSSimon Glassplaced alongside rsa.c, and its functions added to the table in image-sig.c 623e569a6bSSimon Glassalso. 633e569a6bSSimon Glass 643e569a6bSSimon Glass 654c1d5c29SAndreas DannenbergCreating an RSA key pair and certificate 664c1d5c29SAndreas Dannenberg---------------------------------------- 674c1d5c29SAndreas DannenbergTo create a new public/private key pair, size 2048 bits: 683e569a6bSSimon Glass 69e0f2f155SMichael van der Westhuizen$ openssl genpkey -algorithm RSA -out keys/dev.key \ 70e0f2f155SMichael van der Westhuizen -pkeyopt rsa_keygen_bits:2048 -pkeyopt rsa_keygen_pubexp:65537 713e569a6bSSimon Glass 724c1d5c29SAndreas DannenbergTo create a certificate for this containing the public key: 733e569a6bSSimon Glass 743e569a6bSSimon Glass$ openssl req -batch -new -x509 -key keys/dev.key -out keys/dev.crt 753e569a6bSSimon Glass 763e569a6bSSimon GlassIf you like you can look at the public key also: 773e569a6bSSimon Glass 783e569a6bSSimon Glass$ openssl rsa -in keys/dev.key -pubout 793e569a6bSSimon Glass 803e569a6bSSimon Glass 813e569a6bSSimon GlassDevice Tree Bindings 823e569a6bSSimon Glass-------------------- 833e569a6bSSimon GlassThe following properties are required in the FIT's signature node(s) to 84e43f74acSMasahiro Yamadaallow the signer to operate. These should be added to the .its file. 853e569a6bSSimon GlassSignature nodes sit at the same level as hash nodes and are called 8683840405SAndre Przywarasignature-1, signature-2, etc. 873e569a6bSSimon Glass 886af5520fSMasahiro Yamada- algo: Algorithm name (e.g. "sha1,rsa2048") 893e569a6bSSimon Glass 903e569a6bSSimon Glass- key-name-hint: Name of key to use for signing. The keys will normally be in 913e569a6bSSimon Glassa single directory (parameter -k to mkimage). For a given key <name>, its 923e569a6bSSimon Glassprivate key is stored in <name>.key and the certificate is stored in 933e569a6bSSimon Glass<name>.crt. 943e569a6bSSimon Glass 953e569a6bSSimon GlassWhen the image is signed, the following properties are added (mandatory): 963e569a6bSSimon Glass 973e569a6bSSimon Glass- value: The signature data (e.g. 256 bytes for 2048-bit RSA) 983e569a6bSSimon Glass 993e569a6bSSimon GlassWhen the image is signed, the following properties are optional: 1003e569a6bSSimon Glass 1013e569a6bSSimon Glass- timestamp: Time when image was signed (standard Unix time_t format) 1023e569a6bSSimon Glass 1033e569a6bSSimon Glass- signer-name: Name of the signer (e.g. "mkimage") 1043e569a6bSSimon Glass 1053e569a6bSSimon Glass- signer-version: Version string of the signer (e.g. "2013.01") 1063e569a6bSSimon Glass 1073e569a6bSSimon Glass- comment: Additional information about the signer or image 1083e569a6bSSimon Glass 109*e83cf2fbSPhilippe Reynes- padding: The padding algorithm, it may be pkcs-1.5 or pss, 110*e83cf2fbSPhilippe Reynes if no value is provided we assume pkcs-1.5 111*e83cf2fbSPhilippe Reynes 1124d098529SSimon GlassFor config bindings (see Signed Configurations below), the following 1134d098529SSimon Glassadditional properties are optional: 1143e569a6bSSimon Glass 1154d098529SSimon Glass- sign-images: A list of images to sign, each being a property of the conf 1164d098529SSimon Glassnode that contains then. The default is "kernel,fdt" which means that these 1174d098529SSimon Glasstwo images will be looked up in the config and signed if present. 1184d098529SSimon Glass 1194d098529SSimon GlassFor config bindings, these properties are added by the signer: 1204d098529SSimon Glass 1214d098529SSimon Glass- hashed-nodes: A list of nodes which were hashed by the signer. Each is 1224d098529SSimon Glass a string - the full path to node. A typical value might be: 1234d098529SSimon Glass 12483840405SAndre Przywara hashed-nodes = "/", "/configurations/conf-1", "/images/kernel", 12583840405SAndre Przywara "/images/kernel/hash-1", "/images/fdt-1", 12683840405SAndre Przywara "/images/fdt-1/hash-1"; 1274d098529SSimon Glass 1284d098529SSimon Glass- hashed-strings: The start and size of the string region of the FIT that 1294d098529SSimon Glass was hashed 1304d098529SSimon Glass 1314d098529SSimon GlassExample: See sign-images.its for an example image tree source file and 1324d098529SSimon Glasssign-configs.its for config signing. 1333e569a6bSSimon Glass 1343e569a6bSSimon Glass 1353e569a6bSSimon GlassPublic Key Storage 1363e569a6bSSimon Glass------------------ 1373e569a6bSSimon GlassIn order to verify an image that has been signed with a public key we need to 1383e569a6bSSimon Glasshave a trusted public key. This cannot be stored in the signed image, since 1393e569a6bSSimon Glassit would be easy to alter. For this implementation we choose to store the 1403e569a6bSSimon Glasspublic key in U-Boot's control FDT (using CONFIG_OF_CONTROL). 1413e569a6bSSimon Glass 1423e569a6bSSimon GlassPublic keys should be stored as sub-nodes in a /signature node. Required 1433e569a6bSSimon Glassproperties are: 1443e569a6bSSimon Glass 1456af5520fSMasahiro Yamada- algo: Algorithm name (e.g. "sha1,rsa2048") 1463e569a6bSSimon Glass 1473e569a6bSSimon GlassOptional properties are: 1483e569a6bSSimon Glass 1493e569a6bSSimon Glass- key-name-hint: Name of key used for signing. This is only a hint since it 1503e569a6bSSimon Glassis possible for the name to be changed. Verification can proceed by checking 1513e569a6bSSimon Glassall available signing keys until one matches. 1523e569a6bSSimon Glass 1533e569a6bSSimon Glass- required: If present this indicates that the key must be verified for the 1543e569a6bSSimon Glassimage / configuration to be considered valid. Only required keys are 1553e569a6bSSimon Glassnormally verified by the FIT image booting algorithm. Valid values are 156e43f74acSMasahiro Yamada"image" to force verification of all images, and "conf" to force verification 1573e569a6bSSimon Glassof the selected configuration (which then relies on hashes in the images to 1583e569a6bSSimon Glassverify those). 1593e569a6bSSimon Glass 1603e569a6bSSimon GlassEach signing algorithm has its own additional properties. 1613e569a6bSSimon Glass 1623e569a6bSSimon GlassFor RSA the following are mandatory: 1633e569a6bSSimon Glass 1643e569a6bSSimon Glass- rsa,num-bits: Number of key bits (e.g. 2048) 1653e569a6bSSimon Glass- rsa,modulus: Modulus (N) as a big-endian multi-word integer 166e0f2f155SMichael van der Westhuizen- rsa,exponent: Public exponent (E) as a 64 bit unsigned integer 1673e569a6bSSimon Glass- rsa,r-squared: (2^num-bits)^2 as a big-endian multi-word integer 1683e569a6bSSimon Glass- rsa,n0-inverse: -1 / modulus[0] mod 2^32 1693e569a6bSSimon Glass 1703e569a6bSSimon Glass 1714d098529SSimon GlassSigned Configurations 1724d098529SSimon Glass--------------------- 1734d098529SSimon GlassWhile signing images is useful, it does not provide complete protection 1744d098529SSimon Glassagainst several types of attack. For example, it it possible to create a 1754d098529SSimon GlassFIT with the same signed images, but with the configuration changed such 1764d098529SSimon Glassthat a different one is selected (mix and match attack). It is also possible 1774d098529SSimon Glassto substitute a signed image from an older FIT version into a newer FIT 1784d098529SSimon Glass(roll-back attack). 1794d098529SSimon Glass 1804d098529SSimon GlassAs an example, consider this FIT: 1814d098529SSimon Glass 1824d098529SSimon Glass/ { 1834d098529SSimon Glass images { 18483840405SAndre Przywara kernel-1 { 1854d098529SSimon Glass data = <data for kernel1> 18683840405SAndre Przywara signature-1 { 1874d098529SSimon Glass algo = "sha1,rsa2048"; 1884d098529SSimon Glass value = <...kernel signature 1...> 1894d098529SSimon Glass }; 1904d098529SSimon Glass }; 19183840405SAndre Przywara kernel-2 { 1924d098529SSimon Glass data = <data for kernel2> 19383840405SAndre Przywara signature-1 { 1944d098529SSimon Glass algo = "sha1,rsa2048"; 1954d098529SSimon Glass value = <...kernel signature 2...> 1964d098529SSimon Glass }; 1974d098529SSimon Glass }; 19883840405SAndre Przywara fdt-1 { 1994d098529SSimon Glass data = <data for fdt1>; 20083840405SAndre Przywara signature-1 { 2014d098529SSimon Glass algo = "sha1,rsa2048"; 2024d098529SSimon Glass vaue = <...fdt signature 1...> 2034d098529SSimon Glass }; 2044d098529SSimon Glass }; 20583840405SAndre Przywara fdt-2 { 2064d098529SSimon Glass data = <data for fdt2>; 20783840405SAndre Przywara signature-1 { 2084d098529SSimon Glass algo = "sha1,rsa2048"; 2094d098529SSimon Glass vaue = <...fdt signature 2...> 2104d098529SSimon Glass }; 2114d098529SSimon Glass }; 2124d098529SSimon Glass }; 2134d098529SSimon Glass configurations { 21483840405SAndre Przywara default = "conf-1"; 21583840405SAndre Przywara conf-1 { 21683840405SAndre Przywara kernel = "kernel-1"; 21783840405SAndre Przywara fdt = "fdt-1"; 2184d098529SSimon Glass }; 21983840405SAndre Przywara conf-1 { 22083840405SAndre Przywara kernel = "kernel-2"; 22183840405SAndre Przywara fdt = "fdt-2"; 2224d098529SSimon Glass }; 2234d098529SSimon Glass }; 2244d098529SSimon Glass}; 2254d098529SSimon Glass 2264d098529SSimon GlassSince both kernels are signed it is easy for an attacker to add a new 2274d098529SSimon Glassconfiguration 3 with kernel 1 and fdt 2: 2284d098529SSimon Glass 2294d098529SSimon Glass configurations { 23083840405SAndre Przywara default = "conf-1"; 23183840405SAndre Przywara conf-1 { 23283840405SAndre Przywara kernel = "kernel-1"; 23383840405SAndre Przywara fdt = "fdt-1"; 2344d098529SSimon Glass }; 23583840405SAndre Przywara conf-1 { 23683840405SAndre Przywara kernel = "kernel-2"; 23783840405SAndre Przywara fdt = "fdt-2"; 2384d098529SSimon Glass }; 23983840405SAndre Przywara conf-3 { 24083840405SAndre Przywara kernel = "kernel-1"; 24183840405SAndre Przywara fdt = "fdt-2"; 2424d098529SSimon Glass }; 2434d098529SSimon Glass }; 2444d098529SSimon Glass 2454d098529SSimon GlassWith signed images, nothing protects against this. Whether it gains an 2464d098529SSimon Glassadvantage for the attacker is debatable, but it is not secure. 2474d098529SSimon Glass 248e43f74acSMasahiro YamadaTo solve this problem, we support signed configurations. In this case it 2494d098529SSimon Glassis the configurations that are signed, not the image. Each image has its 2504d098529SSimon Glassown hash, and we include the hash in the configuration signature. 2514d098529SSimon Glass 2524d098529SSimon GlassSo the above example is adjusted to look like this: 2534d098529SSimon Glass 2544d098529SSimon Glass/ { 2554d098529SSimon Glass images { 25683840405SAndre Przywara kernel-1 { 2574d098529SSimon Glass data = <data for kernel1> 25883840405SAndre Przywara hash-1 { 2594d098529SSimon Glass algo = "sha1"; 2604d098529SSimon Glass value = <...kernel hash 1...> 2614d098529SSimon Glass }; 2624d098529SSimon Glass }; 26383840405SAndre Przywara kernel-2 { 2644d098529SSimon Glass data = <data for kernel2> 26583840405SAndre Przywara hash-1 { 2664d098529SSimon Glass algo = "sha1"; 2674d098529SSimon Glass value = <...kernel hash 2...> 2684d098529SSimon Glass }; 2694d098529SSimon Glass }; 27083840405SAndre Przywara fdt-1 { 2714d098529SSimon Glass data = <data for fdt1>; 27283840405SAndre Przywara hash-1 { 2734d098529SSimon Glass algo = "sha1"; 2744d098529SSimon Glass value = <...fdt hash 1...> 2754d098529SSimon Glass }; 2764d098529SSimon Glass }; 27783840405SAndre Przywara fdt-2 { 2784d098529SSimon Glass data = <data for fdt2>; 27983840405SAndre Przywara hash-1 { 2804d098529SSimon Glass algo = "sha1"; 2814d098529SSimon Glass value = <...fdt hash 2...> 2824d098529SSimon Glass }; 2834d098529SSimon Glass }; 2844d098529SSimon Glass }; 2854d098529SSimon Glass configurations { 28683840405SAndre Przywara default = "conf-1"; 28783840405SAndre Przywara conf-1 { 28883840405SAndre Przywara kernel = "kernel-1"; 28983840405SAndre Przywara fdt = "fdt-1"; 29083840405SAndre Przywara signature-1 { 2914d098529SSimon Glass algo = "sha1,rsa2048"; 2924d098529SSimon Glass value = <...conf 1 signature...>; 2934d098529SSimon Glass }; 2944d098529SSimon Glass }; 29583840405SAndre Przywara conf-2 { 29683840405SAndre Przywara kernel = "kernel-2"; 29783840405SAndre Przywara fdt = "fdt-2"; 29883840405SAndre Przywara signature-1 { 2994d098529SSimon Glass algo = "sha1,rsa2048"; 3004d098529SSimon Glass value = <...conf 1 signature...>; 3014d098529SSimon Glass }; 3024d098529SSimon Glass }; 3034d098529SSimon Glass }; 3044d098529SSimon Glass}; 3054d098529SSimon Glass 3064d098529SSimon Glass 3074d098529SSimon GlassYou can see that we have added hashes for all images (since they are no 3084d098529SSimon Glasslonger signed), and a signature to each configuration. In the above example, 30983840405SAndre Przywaramkimage will sign configurations/conf-1, the kernel and fdt that are 31083840405SAndre Przywarapointed to by the configuration (/images/kernel-1, /images/kernel-1/hash-1, 31183840405SAndre Przywara/images/fdt-1, /images/fdt-1/hash-1) and the root structure of the image 3124d098529SSimon Glass(so that it isn't possible to add or remove root nodes). The signature is 31383840405SAndre Przywarawritten into /configurations/conf-1/signature-1/value. It can easily be 3144d098529SSimon Glassverified later even if the FIT has been signed with other keys in the 3154d098529SSimon Glassmeantime. 3164d098529SSimon Glass 3174d098529SSimon Glass 3183e569a6bSSimon GlassVerification 3193e569a6bSSimon Glass------------ 3203e569a6bSSimon GlassFITs are verified when loaded. After the configuration is selected a list 3213e569a6bSSimon Glassof required images is produced. If there are 'required' public keys, then 3223e569a6bSSimon Glasseach image must be verified against those keys. This means that every image 3233e569a6bSSimon Glassthat might be used by the target needs to be signed with 'required' keys. 3243e569a6bSSimon Glass 3253e569a6bSSimon GlassThis happens automatically as part of a bootm command when FITs are used. 3263e569a6bSSimon Glass 3273e569a6bSSimon Glass 3283e569a6bSSimon GlassEnabling FIT Verification 3293e569a6bSSimon Glass------------------------- 3303e569a6bSSimon GlassIn addition to the options to enable FIT itself, the following CONFIGs must 3313e569a6bSSimon Glassbe enabled: 3323e569a6bSSimon Glass 333e43f74acSMasahiro YamadaCONFIG_FIT_SIGNATURE - enable signing and verification in FITs 3343e569a6bSSimon GlassCONFIG_RSA - enable RSA algorithm for signing 3353e569a6bSSimon Glass 33621d29f7fSHeiko SchocherWARNING: When relying on signed FIT images with required signature check 33721d29f7fSHeiko Schocherthe legacy image format is default disabled by not defining 33821d29f7fSHeiko SchocherCONFIG_IMAGE_FORMAT_LEGACY 3393e569a6bSSimon Glass 3403e569a6bSSimon GlassTesting 3413e569a6bSSimon Glass------- 342e43f74acSMasahiro YamadaAn easy way to test signing and verification is to use the test script 3433e569a6bSSimon Glassprovided in test/vboot/vboot_test.sh. This uses sandbox (a special version 3443e569a6bSSimon Glassof U-Boot which runs under Linux) to show the operation of a 'bootm' 3453e569a6bSSimon Glasscommand loading and verifying images. 3463e569a6bSSimon Glass 3473e569a6bSSimon GlassA sample run is show below: 3483e569a6bSSimon Glass 3493e569a6bSSimon Glass$ make O=sandbox sandbox_config 3503e569a6bSSimon Glass$ make O=sandbox 3513e569a6bSSimon Glass$ O=sandbox ./test/vboot/vboot_test.sh 3523e569a6bSSimon GlassSimple Verified Boot Test 3533e569a6bSSimon Glass========================= 3543e569a6bSSimon Glass 3553e569a6bSSimon GlassPlease see doc/uImage.FIT/verified-boot.txt for more information 3563e569a6bSSimon Glass 357646257d1SHeiko Schocher/home/hs/ids/u-boot/sandbox/tools/mkimage -D -I dts -O dtb -p 2000 3583e569a6bSSimon GlassBuild keys 359646257d1SHeiko Schocherdo sha1 test 3603e569a6bSSimon GlassBuild FIT with signed images 3613e569a6bSSimon GlassTest Verified Boot Run: unsigned signatures:: OK 3623e569a6bSSimon GlassSign images 3633e569a6bSSimon GlassTest Verified Boot Run: signed images: OK 3643e569a6bSSimon GlassBuild FIT with signed configuration 3653e569a6bSSimon GlassTest Verified Boot Run: unsigned config: OK 3663e569a6bSSimon GlassSign images 3673e569a6bSSimon GlassTest Verified Boot Run: signed config: OK 36829a23f9dSHeiko Schochercheck signed config on the host 369ce1400f6SSimon GlassSignature check OK 37029a23f9dSHeiko SchocherOK 37129a23f9dSHeiko SchocherTest Verified Boot Run: signed config: OK 372646257d1SHeiko SchocherTest Verified Boot Run: signed config with bad hash: OK 373646257d1SHeiko Schocherdo sha256 test 374646257d1SHeiko SchocherBuild FIT with signed images 375646257d1SHeiko SchocherTest Verified Boot Run: unsigned signatures:: OK 376646257d1SHeiko SchocherSign images 377646257d1SHeiko SchocherTest Verified Boot Run: signed images: OK 378646257d1SHeiko SchocherBuild FIT with signed configuration 379646257d1SHeiko SchocherTest Verified Boot Run: unsigned config: OK 380646257d1SHeiko SchocherSign images 381646257d1SHeiko SchocherTest Verified Boot Run: signed config: OK 38229a23f9dSHeiko Schochercheck signed config on the host 383ce1400f6SSimon GlassSignature check OK 38429a23f9dSHeiko SchocherOK 38529a23f9dSHeiko SchocherTest Verified Boot Run: signed config: OK 386646257d1SHeiko SchocherTest Verified Boot Run: signed config with bad hash: OK 3873e569a6bSSimon Glass 3883e569a6bSSimon GlassTest passed 3893e569a6bSSimon Glass 390ce1400f6SSimon Glass 391f1ca1fdeSGeorge McCollisterHardware Signing with PKCS#11 392f1ca1fdeSGeorge McCollister----------------------------- 393f1ca1fdeSGeorge McCollister 394f1ca1fdeSGeorge McCollisterSecurely managing private signing keys can challenging, especially when the 395f1ca1fdeSGeorge McCollisterkeys are stored on the file system of a computer that is connected to the 396f1ca1fdeSGeorge McCollisterInternet. If an attacker is able to steal the key, they can sign malicious FIT 397f1ca1fdeSGeorge McCollisterimages which will appear genuine to your devices. 398f1ca1fdeSGeorge McCollister 399f1ca1fdeSGeorge McCollisterAn alternative solution is to keep your signing key securely stored on hardware 400f1ca1fdeSGeorge McCollisterdevice like a smartcard, USB token or Hardware Security Module (HSM) and have 401f1ca1fdeSGeorge McCollisterthem perform the signing. PKCS#11 is standard for interfacing with these crypto 402f1ca1fdeSGeorge McCollisterdevice. 403f1ca1fdeSGeorge McCollister 404f1ca1fdeSGeorge McCollisterRequirements: 405f1ca1fdeSGeorge McCollisterSmartcard/USB token/HSM which can work with the pkcs11 engine 406f1ca1fdeSGeorge McCollisteropenssl 407f1ca1fdeSGeorge McCollisterlibp11 (provides pkcs11 engine) 408f1ca1fdeSGeorge McCollisterp11-kit (recommended to simplify setup) 409f1ca1fdeSGeorge McCollisteropensc (for smartcards and smartcard like USB devices) 410f1ca1fdeSGeorge McCollistergnutls (recommended for key generation, p11tool) 411f1ca1fdeSGeorge McCollister 412f1ca1fdeSGeorge McCollisterThe following examples use the Nitrokey Pro. Instructions for other devices may vary. 413f1ca1fdeSGeorge McCollister 414f1ca1fdeSGeorge McCollisterNotes on pkcs11 engine setup: 415f1ca1fdeSGeorge McCollister 416f1ca1fdeSGeorge McCollisterMake sure p11-kit, opensc are installed and that p11-kit is setup to use opensc. 417f1ca1fdeSGeorge McCollister/usr/share/p11-kit/modules/opensc.module should be present on your system. 418f1ca1fdeSGeorge McCollister 419f1ca1fdeSGeorge McCollister 420f1ca1fdeSGeorge McCollisterGenerating Keys On the Nitrokey: 421f1ca1fdeSGeorge McCollister 422f1ca1fdeSGeorge McCollister$ gpg --card-edit 423f1ca1fdeSGeorge McCollister 424f1ca1fdeSGeorge McCollisterReader ...........: Nitrokey Nitrokey Pro (xxxxxxxx0000000000000000) 00 00 425f1ca1fdeSGeorge McCollisterApplication ID ...: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 426f1ca1fdeSGeorge McCollisterVersion ..........: 2.1 427f1ca1fdeSGeorge McCollisterManufacturer .....: ZeitControl 428f1ca1fdeSGeorge McCollisterSerial number ....: xxxxxxxx 429f1ca1fdeSGeorge McCollisterName of cardholder: [not set] 430f1ca1fdeSGeorge McCollisterLanguage prefs ...: de 431f1ca1fdeSGeorge McCollisterSex ..............: unspecified 432f1ca1fdeSGeorge McCollisterURL of public key : [not set] 433f1ca1fdeSGeorge McCollisterLogin data .......: [not set] 434f1ca1fdeSGeorge McCollisterSignature PIN ....: forced 435f1ca1fdeSGeorge McCollisterKey attributes ...: rsa2048 rsa2048 rsa2048 436f1ca1fdeSGeorge McCollisterMax. PIN lengths .: 32 32 32 437f1ca1fdeSGeorge McCollisterPIN retry counter : 3 0 3 438f1ca1fdeSGeorge McCollisterSignature counter : 0 439f1ca1fdeSGeorge McCollisterSignature key ....: [none] 440f1ca1fdeSGeorge McCollisterEncryption key....: [none] 441f1ca1fdeSGeorge McCollisterAuthentication key: [none] 442f1ca1fdeSGeorge McCollisterGeneral key info..: [none] 443f1ca1fdeSGeorge McCollister 444f1ca1fdeSGeorge McCollistergpg/card> generate 445f1ca1fdeSGeorge McCollisterMake off-card backup of encryption key? (Y/n) n 446f1ca1fdeSGeorge McCollister 447f1ca1fdeSGeorge McCollisterPlease note that the factory settings of the PINs are 448f1ca1fdeSGeorge McCollister PIN = '123456' Admin PIN = '12345678' 449f1ca1fdeSGeorge McCollisterYou should change them using the command --change-pin 450f1ca1fdeSGeorge McCollister 451f1ca1fdeSGeorge McCollisterWhat keysize do you want for the Signature key? (2048) 4096 452f1ca1fdeSGeorge McCollisterThe card will now be re-configured to generate a key of 4096 bits 453f1ca1fdeSGeorge McCollisterNote: There is no guarantee that the card supports the requested size. 454f1ca1fdeSGeorge McCollister If the key generation does not succeed, please check the 455f1ca1fdeSGeorge McCollister documentation of your card to see what sizes are allowed. 456f1ca1fdeSGeorge McCollisterWhat keysize do you want for the Encryption key? (2048) 4096 457f1ca1fdeSGeorge McCollisterThe card will now be re-configured to generate a key of 4096 bits 458f1ca1fdeSGeorge McCollisterWhat keysize do you want for the Authentication key? (2048) 4096 459f1ca1fdeSGeorge McCollisterThe card will now be re-configured to generate a key of 4096 bits 460f1ca1fdeSGeorge McCollisterPlease specify how long the key should be valid. 461f1ca1fdeSGeorge McCollister 0 = key does not expire 462f1ca1fdeSGeorge McCollister <n> = key expires in n days 463f1ca1fdeSGeorge McCollister <n>w = key expires in n weeks 464f1ca1fdeSGeorge McCollister <n>m = key expires in n months 465f1ca1fdeSGeorge McCollister <n>y = key expires in n years 466f1ca1fdeSGeorge McCollisterKey is valid for? (0) 467f1ca1fdeSGeorge McCollisterKey does not expire at all 468f1ca1fdeSGeorge McCollisterIs this correct? (y/N) y 469f1ca1fdeSGeorge McCollister 470f1ca1fdeSGeorge McCollisterGnuPG needs to construct a user ID to identify your key. 471f1ca1fdeSGeorge McCollister 472f1ca1fdeSGeorge McCollisterReal name: John Doe 473f1ca1fdeSGeorge McCollisterEmail address: john.doe@email.com 474f1ca1fdeSGeorge McCollisterComment: 475f1ca1fdeSGeorge McCollisterYou selected this USER-ID: 476f1ca1fdeSGeorge McCollister "John Doe <john.doe@email.com>" 477f1ca1fdeSGeorge McCollister 478f1ca1fdeSGeorge McCollisterChange (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? o 479f1ca1fdeSGeorge McCollister 480f1ca1fdeSGeorge McCollister 481f1ca1fdeSGeorge McCollisterUsing p11tool to get the token URL: 482f1ca1fdeSGeorge McCollister 483f1ca1fdeSGeorge McCollisterDepending on system configuration, gpg-agent may need to be killed first. 484f1ca1fdeSGeorge McCollister 485f1ca1fdeSGeorge McCollister$ p11tool --provider /usr/lib/opensc-pkcs11.so --list-tokens 486f1ca1fdeSGeorge McCollisterToken 0: 487f1ca1fdeSGeorge McCollisterURL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29 488f1ca1fdeSGeorge McCollisterLabel: OpenPGP card (User PIN (sig)) 489f1ca1fdeSGeorge McCollisterType: Hardware token 490f1ca1fdeSGeorge McCollisterManufacturer: ZeitControl 491f1ca1fdeSGeorge McCollisterModel: PKCS#15 emulated 492f1ca1fdeSGeorge McCollisterSerial: 000xxxxxxxxx 493f1ca1fdeSGeorge McCollisterModule: (null) 494f1ca1fdeSGeorge McCollister 495f1ca1fdeSGeorge McCollister 496f1ca1fdeSGeorge McCollisterToken 1: 497f1ca1fdeSGeorge McCollisterURL: pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%29 498f1ca1fdeSGeorge McCollisterLabel: OpenPGP card (User PIN) 499f1ca1fdeSGeorge McCollisterType: Hardware token 500f1ca1fdeSGeorge McCollisterManufacturer: ZeitControl 501f1ca1fdeSGeorge McCollisterModel: PKCS#15 emulated 502f1ca1fdeSGeorge McCollisterSerial: 000xxxxxxxxx 503f1ca1fdeSGeorge McCollisterModule: (null) 504f1ca1fdeSGeorge McCollister 505f1ca1fdeSGeorge McCollisterUse the portion of the signature token URL after "pkcs11:" as the keydir argument (-k) to mkimage below. 506f1ca1fdeSGeorge McCollister 507f1ca1fdeSGeorge McCollister 508f1ca1fdeSGeorge McCollisterUse the URL of the token to list the private keys: 509f1ca1fdeSGeorge McCollister 510f1ca1fdeSGeorge McCollister$ p11tool --login --provider /usr/lib/opensc-pkcs11.so --list-privkeys \ 511f1ca1fdeSGeorge McCollister"pkcs11:model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" 512f1ca1fdeSGeorge McCollisterToken '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 513f1ca1fdeSGeorge McCollisterEnter PIN: 514f1ca1fdeSGeorge McCollisterObject 0: 515f1ca1fdeSGeorge McCollisterURL: 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 516f1ca1fdeSGeorge McCollisterType: Private key 517f1ca1fdeSGeorge McCollisterLabel: Signature key 518f1ca1fdeSGeorge McCollisterFlags: CKA_PRIVATE; CKA_NEVER_EXTRACTABLE; CKA_SENSITIVE; 519f1ca1fdeSGeorge McCollisterID: 01 520f1ca1fdeSGeorge McCollister 521f1ca1fdeSGeorge McCollisterUse the label, in this case "Signature key" as the key-name-hint in your FIT. 522f1ca1fdeSGeorge McCollister 523f1ca1fdeSGeorge McCollisterCreate the fitImage: 524f1ca1fdeSGeorge McCollister$ ./tools/mkimage -f fit-image.its fitImage 525f1ca1fdeSGeorge McCollister 526f1ca1fdeSGeorge McCollister 527f1ca1fdeSGeorge McCollisterSign the fitImage with the hardware key: 528f1ca1fdeSGeorge McCollister 529f1ca1fdeSGeorge McCollister$ ./tools/mkimage -F -k \ 530f1ca1fdeSGeorge McCollister"model=PKCS%2315%20emulated;manufacturer=ZeitControl;serial=000xxxxxxxxx;token=OpenPGP%20card%20%28User%20PIN%20%28sig%29%29" \ 531f1ca1fdeSGeorge McCollister-K u-boot.dtb -N pkcs11 -r fitImage 532f1ca1fdeSGeorge McCollister 533f1ca1fdeSGeorge McCollister 5343e569a6bSSimon GlassFuture Work 5353e569a6bSSimon Glass----------- 5363e569a6bSSimon Glass- Roll-back protection using a TPM is done using the tpm command. This can 5373e569a6bSSimon Glassbe scripted, but we might consider a default way of doing this, built into 5383e569a6bSSimon Glassbootm. 5393e569a6bSSimon Glass 5403e569a6bSSimon Glass 5413e569a6bSSimon GlassPossible Future Work 5423e569a6bSSimon Glass-------------------- 5433e569a6bSSimon Glass- Add support for other RSA/SHA variants, such as rsa4096,sha512. 5443e569a6bSSimon Glass- Other algorithms besides RSA 5453e569a6bSSimon Glass- More sandbox tests for failure modes 5463e569a6bSSimon Glass- Passwords for keys/certificates 5473e569a6bSSimon Glass- Perhaps implement OAEP 5483e569a6bSSimon Glass- Enhance bootm to permit scripted signature verification (so that a script 5493e569a6bSSimon Glasscan verify an image but not actually boot it) 5503e569a6bSSimon Glass 5513e569a6bSSimon Glass 5523e569a6bSSimon GlassSimon Glass 5533e569a6bSSimon Glasssjg@chromium.org 5543e569a6bSSimon Glass1-1-13 555