Wim Vervoorn has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/38591 )
Change subject: Documentation/vendorcode/eltan: Updated security document ......................................................................
Documentation/vendorcode/eltan: Updated security document
The security document has been updated to reflect the current state of the coreboot implementation.
More detail has been added and the change to the public vboot API is documented.
BUG=N/A TEST=build
Change-Id: I228d0faae0efde70039680a981fea9a436d2384f Signed-off-by: Wim Vervoorn wvervoorn@eltan.com --- M Documentation/vendorcode/eltan/security.md 1 file changed, 109 insertions(+), 22 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/91/38591/1
diff --git a/Documentation/vendorcode/eltan/security.md b/Documentation/vendorcode/eltan/security.md index 04537df..79c0896 100644 --- a/Documentation/vendorcode/eltan/security.md +++ b/Documentation/vendorcode/eltan/security.md @@ -1,38 +1,125 @@ # Eltan Security
-## Security This code enables measured boot and verified boot support. -Verified boot is available in coreboot, but based on ChromeOS. This vendorcode -uses a small encryption library and leave much more space in flash for the -payload. +Verified boot is available in coreboot, but based on ChromeOS. This vendorcode security +solution is intended to be used for system without ChromeOS support. + +This solution allows implementing verified boot support for systems that do not contain a TPM.
## Hashing Library -The library suppports SHA-1, SHA-256 and SHA-512. The required routines of -`3rdparty/vboot/firmware/2lib` are used. +The API functions of `3rdparty/vboot/firmware` are used. + +The function `cb_sha_little_endian()` uses `vb2_digest_buffer()` to provide a little endian +digest.
## Measured boot -measured boot support will use TPM2 device if available. The items specified -in `mb_log_list[]` will be measured. +Measured boot support requires a TPM2 device. + +The items specified in `mb_log_list[]` and `*_verify_list[]` the will be measured. + +The `mb_log_list[]` should only contain items that are not contained in one of the verify_lists +below (except for the `bootblock_verify_list[]`). + +The list can contain the next items: `config`, `revision`, `cmos_layout.bin`. +`oemmanifest.bin` should be added when Verified boot is enabled.
## Verified boot -verified boot support will use TPM2 device if available. The items specified -in the next table will be verified: -* `bootblock_verify_list[]` -* `verify_item_t romstage_verify_list[]` -* `ram_stage_additional_list[]` -* `ramstage_verify_list[]` -* `payload_verify_list[]` -* `oprom_verify_list[]` +verified boot support will use the OEM manifest to verify the items. + +The verification process is controlled using the next verify lists: +* `bootblock_verify_list[]` (will not be measured, verified in bootblock) +* `romstage_verify_list[]` (verified in early romstage) +* `postcar_verify_list[]` (verified in just before postcar loading) +* `ramstage_verify_list[]` (verified in just before ramstage loading) +* `payload_verify_list[]` (verified in just before payload loading) +* `oprom_verify_list[]` (verified before option rom execution) + +The verify_list contains a `related_items` member. This can point to an additional +`verify_list` which will be verified before the specified item is verified. As an example the +`ramstage_verify_list[]` can point to the `ram_stage_additional_list[]` that contains the items +used by ramstage. + +In this example loading the ramstage will trigger verification of the items in the +`ram_stage_additional_list[]`. This list can contain items like the vbt file and the dsdt.asl +file used by the ramstage. + +## Creating private and public keys +Create private key in RSA2048 format: +`openssl genrsa -F4 -out <private_key_file> 2048` + +Create public key using private key: +`futility --vb1 create <private_key_file> <public_key_file_without_extension>` + +The public key will be included into coreboot and used for verified boot only.
## Enabling support - -* Measured boot can be enabled using **CONFIG_MBOOT** +To enable measured boot support: +* Enabled **CONFIG_VENDORCODE_ELTAN_MBOOT** * Create mb_log_list table with list of item to measure + +To enable verified boot support: +* Enable **CONFIG_VENDORCODE_ELTAN_VBOOT** * Create tables bootblock_verify_list[], verify_item_t romstage_verify_list[], - ram_stage_additional_list[], ramstage_verify_list[], payload_verify_list[], - oprom_verify_list[] -* Verified boot can be enabled using **CONFIG_VERIFIED_BOOT** -* Added Kconfig values for verbose console output + postcar_verify_list[], ramstage_verify_list[], payload_verify_list[], oprom_verify_list[] +* **CONFIG_VENDORCODE_ELTAN_VBOOT_KEY_FILE** must point to location of the public key created + with futility + +## Creating signed binary + +During build of coreboot binary an empty oemmanifest.bin is added to the binary. + +This binary must be replaced by a correct (signed) binary when +**CONFIG_VENDORCODE_ELTAN_VBOOT** is enabled + +The oemmanifest.bin contains the SHA-256 (or SHA-512) hashes of all the different parts +contained in verify_lists. + +When **CONFIG_VENDORCODE_ELTAN_VBOOT_SIGNED_MANIFEST** is enabled the manifest should be signed +and the signature should appended to the manifest. + +Please make sure the public key is in the RO part of the coreboot image. The OEM manifest +should be in the RW part of the coreboot image. + +### Hashing + +The oemmanifest.bin contains the hashes of different binaries parts of the binary e.g.: +bootblock, romstage, postcar, ramstage, fsp etc. + +The total number of items must match `CONFIG_VENDORCODE_ELTAN_OEM_MANIFEST_ITEMS`. + +For every part the SHA (SHA-256) must be calculated: +First extract the binary from the coreboot image using: +`cbfstool <coreboot_file_name> extract -n <cbfs_name> -f <item_binary_file_name>` +followed by: +`openssl dgst -sha256 -binary -out <hash_file_name> <item_binary_file_name>` + +Replace -sha256 with -sha512 when `CONFIG_VENDORCODE_ELTAN_VBOOT_USE_SHA512` is enabled. + +All the hashes must be combined to a hash binary. The hashes need to be placed in the same +order as defined by the `HASH_IDX_XXX` values. + +### Signing + +The oemmanifest, needs to be signed when `CONFIG_VENDORCODE_ELTAN_VBOOT_SIGNED_MANIFEST` is +enabled. + +This can be done with the next command: +`openssl dgst -sign <private_key_file_name> -sha256 -out <signature_binary> <hash_binary>` + +The oemmanifest.bin can be created by adding the signature_binary to the hash_binary: +`cat <hash_binary> <signature_binary' >hash_table.bin` + +When signing is disabled the hash binary can be copied to `hash_table.bin` + +## Create binary +The oemmanifest.bin must be replaced in the coreboot binary by the generated hash_table.bin. + +To replace the binary: +Remove using: +`cbfstool <coreboot_file_name> remove -n oemmanifest.bin` +Then add the new image using: +`cbfstool coreboot.bin add -f <hash_table_file_name> -n oemmanifest.bin -t raw ` +`-b <CONFIG_VENDORCODE_ELTAN_OEM_MANIFEST_LOC>`
## Debugging