Eric Lee / smarc-uboot

1
Download as
Browse Code ยป

Commit 570267bf173304655674bfa6f1640f310900f8f7

Authored by Clement Le Marquis
Committed by Ye Li
1 parent 267ed0a245
Exists in smarc_8mq_lf_v2020.04 and in 4 other branches pitx_8mp_lf_v2020.04, smarc-8m-android-11.0.0_2.0.0, smarc-8mp-android-11.0.0_2.0.0, smarc_8mp_lf_v2020.04

MLK-20061-1: doc: imx: habv4: Add Encrypted Boot documentation for i.MX 6 and i.MX 7 family devices 

Add useful documentation for encrypted boot:
- Add 2 CSF examples for encrypt and sign
- How to encrypt and sign a U-Boot binary on closed device
- Why and how increase the PRIBLOB bitfield from CAAM SCFGR

Signed-off-by: Clement Le Marquis <clement.lemarquis@nxp.com>
(cherry picked from commit 3732dddfeddd989ca1fb930972f19303e3b67756)
(cherry picked from commit 9e7ccdd51a0754e728f2e27d282aaa3dbc8eec38)

Showing 3 changed files with 381 additions and 0 deletions Side-by-side Diff

doc/imx/habv4/csf_examples/mx6_mx7/csf_u-boot_enc.txt
Diff comments   View file @ 570267b
  1 +[Header]
  2 + Version = 4.2
  3 + Hash Algorithm = sha256
  4 + Engine Configuration = 0
  5 + Certificate Format = X509
  6 + Signature Format = CMS
  7 + Engine = CAAM
  8 +
  9 +[Install SRK]
  10 + # Index of the key location in the SRK table to be installed
  11 + File = "../crts/SRK_1_2_3_4_table.bin"
  12 + Source index = 0
  13 +
  14 +[Install CSFK]
  15 + # Key used to authenticate the CSF data
  16 + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
  17 +
  18 +[Authenticate CSF]
  19 +
  20 +[Install Key]
  21 + # Key slot index used to authenticate the key to be installed
  22 + Verification index = 0
  23 + # Target key slot in HAB key store where key will be installed
  24 + Target Index = 2
  25 + # Key to install
  26 + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
  27 +
  28 +[Authenticate Data]
  29 + # Key slot index used to authenticate the image data
  30 + Verification index = 2
  31 + # This Authenticate Data command covers the IVT and DCD Data
  32 + # The image file referenced will remain unmodified by CST
  33 + Blocks = 0x877ff400 0x000 0xc00 "u-boot-dtb.imx"
  34 +
  35 +[Install Secret Key]
  36 + # Install the blob
  37 + Verification Index = 0
  38 + Target Index = 0
  39 + Key = "dek.bin"
  40 + Key Length = 128
  41 + # Start address + padding 0x2000 + length
  42 + Blob Address = 0x878a0000
  43 +
  44 +[Decrypt Data]
  45 + # The decrypt data command below causes CST to modify the input
  46 + # file and encrypt the specified block of data. This image file
  47 + # is a copy of the file used for the authentication command above
  48 + Verification Index = 0
  49 + Mac Bytes = 16
  50 + Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-enc"
doc/imx/habv4/csf_examples/mx6_mx7/csf_u-boot_sign_enc.txt
Diff comments   View file @ 570267b
  1 +[Header]
  2 + Version = 4.2
  3 + Hash Algorithm = sha256
  4 + Engine Configuration = 0
  5 + Certificate Format = X509
  6 + Signature Format = CMS
  7 + Engine = CAAM
  8 +
  9 +[Install SRK]
  10 + # Index of the key location in the SRK table to be installed
  11 + File = "../crts/SRK_1_2_3_4_table.bin"
  12 + Source index = 0
  13 +
  14 +[Install CSFK]
  15 + # Key used to authenticate the CSF data
  16 + File = "../crts/CSF1_1_sha256_2048_65537_v3_usr_crt.pem"
  17 +
  18 +[Authenticate CSF]
  19 +
  20 +[Install Key]
  21 + # Key slot index used to authenticate the key to be installed
  22 + Verification index = 0
  23 + # Target key slot in HAB key store where key will be installed
  24 + Target Index = 2
  25 + # Key to install
  26 + File= "../crts/IMG1_1_sha256_2048_65537_v3_usr_crt.pem"
  27 +
  28 +[Authenticate Data]
  29 + # This Authenticate Data commandcovers both clear and encrypted data.
  30 + # The image file referenced will remain unmodified by CST.
  31 + # Key slot index used to authenticate the image data
  32 + Verification index = 2
  33 + # Authenticate Start Address, Offset, Length and file
  34 + Blocks = 0x877ff400 0x000 0x0009ec00 "u-boot-dtb.imx-enc"
  35 +
  36 +[Install Secret Key]
  37 + # Install the blob - This will manage a new key that will not be used in
  38 + # the final image, so the file name has to be different
  39 + Verification Index = 0
  40 + Target Index = 0
  41 + Key = "dek-dummy.bin"
  42 + Key Length = 128
  43 + # Start address + padding 0x2000 + length
  44 + Blob Address = 0x878a000
  45 +
  46 +[Decrypt Data]
  47 + # The decrypt Data command is a place holder to ensure the
  48 + # CSF includes the decrypt data command from the first pass.
  49 + # The file that CST will encrypt will not be used, so the file
  50 + # name has to be different.
  51 + Verification Index = 0
  52 + Mac Bytes = 16
  53 + Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-dummy"
doc/imx/habv4/guides/mx6_mx7_encrypted_boot.txt
Diff comments   View file @ 570267b
  1 ++==========================================================+
  2 ++ i.MX6, i.MX7 U-Boot Encrypted Boot guide using HABv4 +
  3 ++==========================================================+
  4 +
  5 +1. HABv4 Encrypted Boot process
  6 +-------------------------------
  7 +
  8 +This document describes a step-by-step procedure on how to encrypt and
  9 +sign an U-Boot image. It is assumed that the reader is familiar
  10 +with basic HAB concepts and has already followed the mx6_mx7_secure_boot.txt
  11 +guide and got a working closed device.
  12 +
  13 +Details about HAB and encrypted boot process can be found in application
  14 +notes AN4581[1] and AN12056[2] and in the introduction_habv4.txt document.
  15 +
  16 +Before continuing, be sure to have fatwrite and dek_blob commands
  17 +available in U-Boot. If not, enable them in Kconfig and rebuild
  18 +U-Boot:
  19 +
  20 +- Defconfig
  21 +
  22 + CONFIG_FAT_WRITE=y
  23 + CONFIG_CMD_DEKBLOB=y
  24 + CONFIG_CDM_PRIBLOB=y
  25 +
  26 +- Kconfig
  27 +
  28 + File systems -> Enable FAT filesystem support-> Enable FAT filesystem
  29 + write support
  30 + ARM architecture -> Support the 'dek_blob' command
  31 + ARM architecture -> Support the set_priblob_bitfield command
  32 +
  33 +1.1 Building an encrypted U-Boot image
  34 +--------------------------------------
  35 +
  36 +This U-Boot is built the same way the one from the secure document is,
  37 +so it provides the same access the the HAB APIs, extra functions
  38 +for HAB, etc...
  39 +
  40 +However, the layout of the new image is different, as a part of it is
  41 +encrypted, and a DEK blob is appended at the end. The diagram below
  42 +illustrates an encrypted u-boot-dtb.imx image layout:
  43 +
  44 + ----------------------- +-----------------------------+ <--- *start
  45 + ^ ^ | Image Vector Table |
  46 + | | +-----------------------------+ <--- *boot_data
  47 + | | | Boot Data |
  48 + | Plain | +-----------------------------+ <--- *dcd
  49 + | text | | DCD Table |
  50 + | | +-----------------------------+
  51 + Signed | v | Padding |
  52 + data | ------- +-----------------------------+ <--- *entry
  53 + | ^ | |
  54 + | | | |
  55 + | Encrypted | | u-boot-dtb.bin |
  56 + | data | | |
  57 + | | | |
  58 + | | +-----------------------------+
  59 + v v | Padding |
  60 + ----------------------- +-----------------------------+ <--- *csf
  61 + ^ | Command Sequence File |
  62 + 0x2000 | | (commands + SRK table + |
  63 + (in bytes) | | signatures + certificates + |
  64 + v | Nonce + MAC) |
  65 + ------- +-----------------------------+
  66 + | Padding |
  67 + +-----------------------------+ <--- *csf + 0x2000
  68 + | DEK Blob |
  69 + +-----------------------------+
  70 + | Padding |
  71 + +-----------------------------+
  72 +
  73 +1.2 Get a secure boot working
  74 +-----------------------------
  75 +
  76 +You need to go through all the steps described into the
  77 +mx6_mx7_secure_boot.txt guide, and get a signed U-Boot which can
  78 +boot successfully on a closed target. Otherwise, the following
  79 +steps will not work.
  80 +
  81 +1.3 Compile the CST to enable the encrypting feature
  82 +----------------------------------------------------
  83 +
  84 +The encrypting feature is not enabled by default. You need to
  85 +execute the following commands to enable it:
  86 +
  87 + $ sudo apt-get install libssl-dev openssl
  88 + $ cd <CST install directory>/code/back_end/src
  89 + $ gcc -o cst_encrypted -I ../hdr -L ../../../linux64/lib *.c
  90 + -lfrontend -lcrypto
  91 + $ cp cst_encrypted ../../../<where your original CST executable is>
  92 +
  93 +1.4 Creating the CSF description files
  94 +--------------------------------------
  95 +
  96 +The CSF contains all the commands that the ROM executes during the
  97 +secure boot. These commands instruct the HAB on which memory areas
  98 +of the image to authenticate, which keys to install, use, etc...
  99 +
  100 +CSF examples for encrypted boot are available under
  101 +doc/imx/hab/habv4/csf_examples/ directory.
  102 +
  103 +For both CSF, first part is same compared to the CSF used for
  104 +the secure boot step.
  105 +Here we describe how to encrypt the U-Boot image and then sign it.
  106 +
  107 +1.4.1 csf_u-boot_enc.txt
  108 +-------------------------
  109 +
  110 +This first CSF is used to encrypt the U-Boot image and generate the
  111 +dek.bin file. The Authenticate Data command has to be modified, and
  112 +two new commands have to be added:
  113 +
  114 +- Modify the Authenticate Data command to only cover IVT and DCD:
  115 +
  116 + Blocks = 0x877ff400 0x00000000 0x00000c00 "u-boot-dtb.imx"
  117 +
  118 +- Add the new Install Secret Key command to generate the dek.bin
  119 + file and install the blob. The parameter which depends of your
  120 + configuration is the Blob Address. Padding of 0x2000 is
  121 + recommended. Following the csf_uboot.txt data for instance:
  122 +
  123 + Blob Address = Authenticate Start Address + Padding + length
  124 + = 0x877ff400 + 0x2000 + 0x9ec00 = 0x878a0000
  125 +
  126 +- Add the new Decrypt Data command to encrypt the file. As the file
  127 + specified in parameter will be modified, we suggest to copy it.
  128 + Then modify the Blocks command depending of your U-Boot image.
  129 + In our example:
  130 +
  131 + $ cp u-boot-dtb.imx u-boot-dtb.imx-enc
  132 + Block = (Authenticate start addr + 0xc00) 0xc00 (length - 0xc00)
  133 + u-boot-dtb.imx-enc
  134 + = (0x877ff400 + 0xc00) 0xc00 (0x9ec00 - 0xc00)
  135 + u-boot-dtb.imx-enc
  136 + = 0x87800000 0xc00 0x9e000 u-boot-dtb.imx-enc
  137 +
  138 +1.4.2 csf_u-boot_sign_enc.txt
  139 +-----------------------------
  140 +
  141 +This second CSF is used to sign the encrypted U-Boot image previously
  142 +generated (u-boot-dtb.imx-enc). The Authenticate Data part has also
  143 +to be changed, the modifications are the following:
  144 +
  145 +- The Authenticate Data command is same compared to the one in
  146 + csf_uboot.txt file, except that this time, the file parameter
  147 + is the file previously encrypted: u-boot-dtb.imx-enc.
  148 +
  149 + Blocks = 0x877ff400 0x000 0x0009ec00 "u-boot-dtb.imx-enc"
  150 +
  151 +- For the two new commands, we do not want to they modify our previously
  152 + signed/generated files. Therefore, for the Key parameter of the
  153 + Install Secret Key command, the value is now dek-dummy.bin, which
  154 + will generate a new dek file instead of erasing the previous one.
  155 + About the decrypt data command, you need to copy the u-boot-dtb.imx
  156 + file again in a u-boot-dtb.imx-dummy file, to not replace the
  157 + original encrypted file with an encrypted one:
  158 +
  159 + Key = "dek-dummy.bin"
  160 + Blocks = 0x87800000 0x00000c00 0x9e000 "u-boot-dtb.imx-dummy"
  161 +
  162 +1.5 Encrypt the U-Boot image
  163 +----------------------------
  164 +
  165 +The image is encrypted using the Code Signing Tool. It generates also
  166 +a CSF binary and a dek.bin file, which will be used on the future
  167 +steps below.
  168 +
  169 +- Create the CSF binary file and encrypt the U-Boot image
  170 +
  171 + $ ./cst_encrypted -i csf_u-boot_enc.txt -o csf_u-boot_enc.bin
  172 +
  173 +1.6 Sign the encrypted U-Boot image
  174 +-----------------------------------
  175 +
  176 +The image is then signed using the Code Signing Tool. It also
  177 +generate a CSF binary, which will be used on the future steps below.
  178 +
  179 +- Create the CSF binary file and sign the encrypted U-Boot image
  180 +
  181 + $ ./cst_encrypted -i csf_u-boot_sign_enc.txt -o csf_u-boot_sign_enc.bin
  182 +
  183 +1.7 Swap Nonce/MAC from csf_u-boot_enc.bin to csf_u-boot_sign_enc.bin
  184 +---------------------------------------------------------------------
  185 +
  186 +First, calculate Nonce/MAC size based on MAC bytes value
  187 +in CSF. As Mac bytes is 16:
  188 +
  189 + Nonce/MAC size = Nonce size + MAC bytes + CSF header for Nonce/Mac
  190 + = 12 + 16 + 8 = 36 bytes
  191 +
  192 +Then, calculate Nonce/MAC offset in CSF:
  193 +
  194 + MAC offset = csf_u-boot-enc.bin size - Nonce/MAC size
  195 + = 3972 - 36 = 3936 Bytes
  196 +
  197 +In the next step, extract Nonce/NAC from the first CSF:
  198 +
  199 + $ dd if=csf_u-boot_enc.bin of=noncemac.bin bs=1 skip=3936 count=36
  200 +
  201 +Finally, replace the MAC of csf_u-boot_sign_enc.bin with the extracted
  202 +one:
  203 +
  204 + $ dd if=noncemac.bin of=csf_u-boot_sign_enc.bin bs=1 seek=3936 count=36
  205 +
  206 +1.8 Generate encryptedu-boot with no dek
  207 +----------------------------------------
  208 +
  209 +As described in the layout in the first part of this document, the
  210 +final image is composed of these different parts padded to known
  211 +values, to make it compliant with the CSF.
  212 +
  213 +First, pad the CSF to 0x2000:
  214 +
  215 + $ objcopy -I binary -O binary --pad-to 0x2000 --gap-fill=0xff
  216 + csf_u-boot_sign_enc.bin csf_u-boot_sign_enc_padded.bin
  217 +
  218 +Then, append this file to the encrypted U-Boot image:
  219 +
  220 + $ cat u-boot-dtb.imx-enc csf_u-boot_sign_enc_padded.bin >
  221 + u-boot_encrypted_no_dek.bin
  222 +
  223 +Pad this new file to width+offset (0x9ec00 + 0x2000 = 0xa0c00):
  224 +
  225 + $ objcopy -I binary -O binary --pad-to 0xa0c00 --gap-fill=0x00
  226 + u-boot_encrypted_no_dek.bin u-boot_encrypted_no_dek_padded.bin
  227 +
  228 +1.9 Generate the DEK Blob
  229 +-------------------------
  230 +The missing part to get our final U-Boot encrypted image is a DEK
  231 +blob. To generate it, copy the dek.bin file generated at step 1.5
  232 +on the Boot partition of your SD Card. Then interrupt the boot
  233 +and your chip. You need the fatwrite and dek_blob command, which
  234 +should be enabled by the secure boot. If not, you have to enable
  235 +them in Kconfig and recompile U-Boot
  236 +
  237 +Run the following commands:
  238 +
  239 + => mmc list
  240 + FSL_SDHC: 0 (SD) #index to use for mmc in following commands
  241 + => fatload mmc 0 0x80800000 dek.bin
  242 + => dek_blob 0x80800000 0x80801000 128
  243 + => fatwrite mmc 0 0x80801000 dek_blob.bin 0x48
  244 +
  245 +1.10 Finalize the encrypted U-Boot image
  246 +----------------------------------------
  247 +
  248 +Finally, copy the generated dek_blob.bin file from your SDCard to
  249 +your CST repository. Append it with the last padded file to get your
  250 +final image:
  251 +
  252 + $ cat u-boot_encrypted_no_dek_padded.bin dek_blob.bin >
  253 + u-boot_encrypted.bin
  254 +
  255 +If the image does not boot, please verify the size of your
  256 +U-Boot image, the length specified into CSF and the padding values.
  257 +
  258 +2. About the PRIBLOB bitfield from CAAM SCFGR register
  259 +------------------------------------------------------
  260 +
  261 +It is highly recommended to set the PRIBLOB bitfield from the CAAM
  262 +SCFGR register to 0x3 once your encrypted U-Boot image is completed.
  263 +To do so, a command has been implemented in u-boot:
  264 +
  265 + => set_priblob_bitfield
  266 +
  267 +Once this bitfield is set to 0x3, it ensures cryptographic separation
  268 +of private blob types avoiding any modification or replacement of
  269 +DEK blobs. Newly created blobs will be incompatible with blobs
  270 +required to decrypt an encrypted boot image. When the HAB later
  271 +executes the command to decrypt the DEK, an incompatible DEK blob
  272 +will be detected and cause an error. A substitute encrypted boot image
  273 +will not be decrypted, and will not be executed.
  274 +
  275 +References:
  276 +[1] AN4581: "Secure Boot on i.MX 50, i.MX 53, i.MX 6 and i.MX 7 Series
  277 +using HABv4" - Rev. 2
  278 +[2] AN12056: "Encrypted Boot on HABv4 and CAAM Enabled Devices" - Rev. 1