[efi-boot-shim.git] / README.md

# shim, a first-stage UEFI bootloader

shim is a trivial EFI application that, when run, attempts to open and
execute another application. It will initially attempt to do this via the
standard EFI `LoadImage()` and `StartImage()` calls. If these fail (because Secure
Boot is enabled and the binary is not signed with an appropriate key, for
instance) it will then validate the binary against a built-in certificate. If
this succeeds and if the binary or signing key are not forbidden then shim
will relocate and execute the binary.

shim will also install a protocol which permits the second-stage bootloader
to perform similar binary validation. This protocol has a GUID as described
in the shim.h header file and provides a single entry point. On 64-bit systems
this entry point expects to be called with SysV ABI rather than MSABI, so calls
to it should not be wrapped.

On systems with a TPM chip enabled and supported by the system firmware,
shim will extend various PCRs with the digests of the targets it is
loading.  A full list is in the file [README.tpm](README.tpm) .

To use shim, simply place a DER-encoded public certificate in a file such as
pub.cer and build with `make VENDOR_CERT_FILE=pub.cer`.

There are a couple of build options, and a couple of ways to customize the
build, described in [BUILDING](BUILDING).

See the [test plan](testplan.txt), and file a ticket if anything fails!
Commit	Line	Data
031e5cce SM	1	# shim, a first-stage UEFI bootloader
031e5cce SM	2
ffc0e242 MG	3	shim is a trivial EFI application that, when run, attempts to open and
ffc0e242 MG	4	execute another application. It will initially attempt to do this via the
031e5cce SM	5	standard EFI `LoadImage()` and `StartImage()` calls. If these fail (because Secure
031e5cce SM	6	Boot is enabled and the binary is not signed with an appropriate key, for
ffc0e242	7	instance) it will then validate the binary against a built-in certificate. If
031e5cce	8	this succeeds and if the binary or signing key are not forbidden then shim
ffc0e242 MG	9	will relocate and execute the binary.
	10
	11	shim will also install a protocol which permits the second-stage bootloader
	12	to perform similar binary validation. This protocol has a GUID as described
	13	in the shim.h header file and provides a single entry point. On 64-bit systems
f892ac66 MTL	14	this entry point expects to be called with SysV ABI rather than MSABI, so calls
f892ac66 MTL	15	to it should not be wrapped.
ffc0e242	16
ab881f03 MTL	17	On systems with a TPM chip enabled and supported by the system firmware,
ab881f03 MTL	18	shim will extend various PCRs with the digests of the targets it is
031e5cce	19	loading. A full list is in the file [README.tpm](README.tpm) .
ab881f03	20
2220be4e	21	To use shim, simply place a DER-encoded public certificate in a file such as
031e5cce	22	pub.cer and build with `make VENDOR_CERT_FILE=pub.cer`.
ab881f03 MTL	23
ab881f03 MTL	24	There are a couple of build options, and a couple of ways to customize the
031e5cce	25	build, described in [BUILDING](BUILDING).
2dd2f760 SM	26
2dd2f760 SM	27	See the [test plan](testplan.txt), and file a ticket if anything fails!