Documentation/vendorcode/eltan: Update security document
Update the security document to reflect the current state of the coreboot implementation. Add more detail and document the change to the public vboot API. BUG=N/A TEST=build Change-Id: I228d0faae0efde70039680a981fea9a436d2384f Signed-off-by: Wim Vervoorn <wvervoorn@eltan.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/38591 Reviewed-by: Patrick Georgi <pgeorgi@google.com> Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
This commit is contained in:
Wim Vervoorn
Patrick Georgi
parent
5c65d00ef2
commit
94545910e6
|
|
@ -1,38 +1,111 @@
|
|||
# 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.
|
||||
|
||||
## 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[]` 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 following items: `config`, `revision`, `cmos_layout.bin`.
|
||||
`oemmanifest.bin` should be added to the list 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 following 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)
|
||||
|
||||
A verify_list entry 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 `grub` entry in
|
||||
`payload_verify_list[]` can point to the `grub_additional_list[]` that contains the items used by
|
||||
the grub payload and the `seabios` entry in `payload_verify_list[]` can point to the
|
||||
`seabios_additional_list[]` that contains the items used by the seabios payload. By doing this the
|
||||
entries that are verified (and measured) depend on the payload selected at runtime.
|
||||
|
||||
## 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
|
||||
To enable measured boot support:
|
||||
* Enabled *VENDORCODE_ELTAN_MBOOT*
|
||||
* Create `mb_log_list` table with list of items to measure
|
||||
|
||||
* Measured boot can be enabled using **CONFIG_MBOOT**
|
||||
* Create mb_log_list table with list of item to measure
|
||||
* 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
|
||||
To enable verified boot support:
|
||||
* Enable *VENDORCODE_ELTAN_VBOOT*
|
||||
* Create the verify lists `*_verify_list[]`
|
||||
* *VENDORCODE_ELTAN_VBOOT_KEY_FILE* must point to location of the public key file 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 *VENDORCODE_ELTAN_VBOOT* is enabled
|
||||
|
||||
The `oemmanifest.bin` file contains the SHA-256 (or SHA-512) hashes of all the different parts
|
||||
contained in verify_lists.
|
||||
|
||||
When *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 `oemmanifest.bin` file
|
||||
should be in the RW part of the coreboot image.
|
||||
|
||||
### Hashing
|
||||
|
||||
The `oemmanifest.bin` file 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 `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 `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 `VENDORCODE_ELTAN_VBOOT_SIGNED_MANIFEST` is enabled.
|
||||
|
||||
This can be done with the following command:
|
||||
`openssl dgst -sign <private_key_file_name> -sha256 -out <signature_binary> <hash_binary>`
|
||||
|
||||
The signed manifest can be created by adding the signature to the manifest:
|
||||
`cat <hash_binary> <signature_binary> >hash_table.bin`
|
||||
|
||||
## Create binary
|
||||
The `oemmanifest.bin` file 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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue