path: root/README.md (plain)
blob: 89243aff94c732f1ef19bf81dc8107927c5f2cc5

1	#Amlogic 1.0
2
3	we copy it from external/avb
4	commit: 2afa76e8859a39cf0ef2b2f96ff092f6ee440a41
5
6	# Android Verified Boot 2.0
7
8	This repository contains tools and libraries for working with Android
9	Verified Boot 2.0. Usually AVB is used to refer to this codebase.
10
11	## Introduction
12
13	The main job of `avbtool` is to create `vbmeta.img` which is the
14	top-level object for verified boot. This image is designed to go into
15	the `vbmeta` partition (or, if using A/B, the slot in question
16	e.g. `vbmeta_a` or `vbmeta_b`) and be of minimal size (for out-of-band
17	updates). The vbmeta image is cryptographically signed and contains
18	verification data (e.g. cryptographic digests) for verifying
19	`boot.img`, `system.img`, and other partitions/images.
20
21	The vbmeta image can also contain references to other partitions where
22	verification data is stored as well as a public key indicating who
23	should sign the verification data. This indirection provides
24	delegation, that is, it allows a 3rd party to control content on a
25	given partition by including their public key in `vbmeta.img`. By
26	design, this authority can be easily revoked by simply updating
27	`vbmeta.img` with new descriptors for the partition in question.
28
29	Storing signed verification data on other images - for example
30	`boot.img` and `system.img` - is also done with `avbtool`.
31
32	In addition to `avbtool`, a library - `libavb` - is provided. This
33	library performs all verification on the device side e.g. it starts by
34	loading the vbmeta partition, checks the signature, and then goes on
35	to load the boot partition for verification. This library is intended
36	to be used in both boot loaders and inside Android. It has a simple
37	abstraction for system dependencies (see `avb_sysdeps.h`) as well as
38	operations that the boot loader or OS is expected to implement (see
39	`avb_ops.h`). The main entry point for verification is
40	`avb_slot_verify()`.
41
42	It is expected that most devices will use A/B (e.g. multiple copies of
43	the OS in separate so-called 'slots') in addition to AVB. While
44	managing A/B metadata and associated metadata (e.g. managing
45	`stored_rollback_index[n]` locations) is outside the scope of
46	`libavb`, enough interfaces are exposed so the boot loader can
47	integrate its A/B stack with `libavb`. In particular
48	`avb_slot_verify()` takes a `slot_suffix` parameter and its result
49	struct `AvbSlotVerifyData` convey the rollback indexes in the image
50	that was verified.
51
52	AVB also includes an A/B implementation that boot loaders may
53	optionally use. This implementation is in the `libavb_ab` library and
54	integrates with image verification including updating the
55	`stored_rollback_index[n]` locations on the device as needed. The
56	bootloader can use this through the `avb_ab_flow()` function which in
57	turn calls `avb_slot_verify()` as needed.
58
59	In `libavb_ab`, A/B metadata is stored in the `misc` partition using a
60	format private to `libavb_ab` in the location on `misc` reserved for
61	this. For more information about the `misc.img` file format see
62	the
63	[bootloader_message.h](https://android.googlesource.com/platform/bootable/recovery/+/master/bootloader_message/include/bootloader_message/bootloader_message.h) file
64	in AOSP. A/B metadata can be written to `misc.img` using the
65	`set_ab_metadata` sub-command of `avbtool`. A/B metadata is comprised
66	of data for each slo and per-slot metadata has a priority field (0 to
67	15), number of tries remaining for attempting to boot the slot (0 to
68	7), and a flag to indicate whether the slot has successfully booted.
69
70	A/B metadata integrity is provided by a simple magic marker and a
71	CRC-32 checksum. If invalid A/B metadata is detected, the behavior is
72	to reset the A/B metadata to a known state where both slots are given
73	seven boot tries.
74
75	An implementation of a boot_control HAL using AVB-specific A/B
76	metadata is also provided.
77
78	Android Things has specific requirements and validation logic for the
79	vbmeta public key. An extension is provided in `libavb_atx` which
80	performs this validation as an implementatio of `libavb`'s public key
81	validation operation (see `avb_validate_vbmeta_public_key()` in
82	`avb_ops.h`).
83
84	## Files and Directories
85
86	* `libavb/`
87	+ An implementation of image verification. This code is designed
88	to be highly portable so it can be used in as many contexts as
89	possible. This code requires a C99-compliant C compiler. Part of
90	this code is considered internal to the implementation and
91	should not be used outside it. For example, this applies to the
92	`avb_rsa.[ch]` and `avb_sha.[ch]` files. System dependencies
93	expected to be provided by the platform is defined in
94	`avb_sysdeps.h`. If the platform provides the standard C runtime
95	`avb_sysdeps_posix.c` can be used.
96	* `libavb_ab/`
97	+ An A/B implementation for use in boot loaders.
98	* `libavb_atx/`
99	+ An Android Things Extension for validating public key metadata.
100	* `libavb_user/`
101	+ Contains an AvbOps implementation suitable for use in userspace
102	on the device (used in boot_control.avb and avbctl).
103	* `boot_control/`
104	+ An implemementation of the Android boot_control HAL for use with
105	boot loaders using `libavb_ab`.
106	* `Android.mk`
107	+ Build instructions for building libavb (a static library for use
108	on the device), host-side libraries (for unit tests), and unit
109	tests.
110	* `avbtool`
111	+ A tool written in Python for working with images related to
112	verified boot.
113	* `test/`
114	+ Unit tests for `abvtool`, `libavb`, `libavb_ab`, and
115	`libavb_atx`.
116	* `tools/avbctl/`
117	+ Contains the source-code for a tool that can be used to control
118	AVB at runtime.
119	* `examples/uefi/`
120	+ Contains the source-code for a UEFI-based boot-loader utilizing
121	`libavb/` and `libavb_ab/`.
122
123	## Audience and portability notes
124
125	This code is intended to be used in bootloaders in devices running
126	Android. The suggested approach is to copy the appropriate header and
127	C files mentioned in the previous section into the boot loader and
128	integrate as appropriate.
129
130	The `libavb/` and `libavb_ab/` codebase will evolve over time so
131	integration should be as non-invasive as possible. The intention is to
132	keep the API of the library stable however it will be broken if
133	necessary. As for portability, the library is intended to be highly
134	portable, work on both little- and big-endian architectures and 32-
135	and 64-bit. It's also intended to work in non-standard environments
136	without the standard C library and runtime.
137
138	If the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code will
139	include useful debug information and run-time checks. Production
140	builds should not use this. The preprocessor symbol `AVB_COMPILATION`
141	should be set only when compiling the libraries. The code must be
142	compiled into a separate libraries.
143
144	Applications using the compiled `libavb` library must only include the
145	`libavb/libavb.h` file (which will include all public interfaces) and
146	must not have the `AVB_COMPILATION` preprocessor symbol set. This is
147	to ensure that internal code that may be change in the future (for
148	example `avb_sha.[ch]` and `avb_rsa.[ch]`) will not be visible to
149	application code.
150
151	## Versioning and compatibility
152
153	AVB uses a version number with three fields - the major, minor, and
154	sub version. Here's an example version number
155
156	1.4.3
157	^ ^ ^
158	| | |
159	the major version ---+ | |
160	the minor version -----+ |
161	the sub version -------+
162
163	The major version number is bumped only if compatibility is broken,
164	e.g. a struct field has been removed or changed. The minor version
165	number is bumped only if a new feature is introduced, for example a
166	new algorithm or descriptor has been added. The sub version number is
167	bumped when bugs are fixed or other changes not affecting
168	compatibility are made.
169
170	The `AvbVBMetaImageHeader` struct (as defined in the
171	`avb_vbmeta_image.h`) carries the major and minor version number of
172	`libavb` required to verify the struct in question. This is stored in
173	the `required_libavb_version_major` and
174	`required_libavb_version_minor` fields. Additionally this struct
175	contains a textual field with the version of `avbtool` used to create
176	the struct, for example "avbtool 1.4.3" or "avbtool 1.4.3 some_board
177	Git-4589fbec".
178
179	Note that it's entirely possible to have a `AvbVBMetaImageHeader`
180	struct with
181
182	required_libavb_version_major = 1
183	required_libavb_version_minor = 0
184	avbtool_release_string = "avbtool 1.4.3"
185
186	if, for example, creating an image that does not use any features
187	added after AVB version 1.0.
188
189	## Adding new features
190
191	If adding a new feature for example a new algorithm or a new
192	descriptor then `AVB_VERSION_MINOR` in `avb_version.h` and `avbtool`
193	must be bumped and `AVB_VERSION_SUB` should be set to zero.
194
195	Unit tests **MUST** be added to check that
196
197	* The feature is used if - and only if - suitable commands/options are
198	passed to `avbtool`.
199	* The `required_version_minor` field is set to the bumped value if -
200	and only if - the feature is used.
201
202	If `AVB_VERSION_MINOR` has already been bumped since the last release
203	there is obviously no need to bump it again.
204
205	## Usage
206
207	The content for the vbmeta partition can be generated as follows:
208
209	$ avbtool make_vbmeta_image \
210	--output OUTPUT \
211	[--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \
212	[--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \
213	[--include_descriptors_from_footer /path/to/image.bin] \
214	[--setup_rootfs_from_kernel /path/to/image.bin] \
215	[--chain_partition part_name:rollback_index_location:/path/to/key1.bin] \
216	[--signing_helper /path/to/external/signer] \
217	[--append_to_release_string STR]
218
219	An integrity footer containing the hash for an entire partition can be
220	added to an existing image as follows:
221
222	$ avbtool add_hash_footer \
223	--image IMAGE \
224	--partition_name PARTNAME --partition_size SIZE \
225	[--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \
226	[--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \
227	[--hash_algorithm HASH_ALG] [--salt HEX] \
228	[--include_descriptors_from_footer /path/to/image.bin] \
229	[--setup_rootfs_from_kernel /path/to/image.bin] \
230	[--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \
231	[--signing_helper /path/to/external/signer] \
232	[--append_to_release_string STR]
233
234	An integrity footer containing the root digest and salt for a hashtree
235	for a partition can be added to an existing image as follows. The
236	hashtree is also appended to the image.
237
238	$ avbtool add_hashtree_footer \
239	--image IMAGE \
240	--partition_name PARTNAME --partition_size SIZE \
241	[--algorithm ALGORITHM] [--key /path/to/key_used_for_signing_or_pub_key] \
242	[--public_key_metadata /path/to/pkmd.bin] [--rollback_index NUMBER] \
243	[--hash_algorithm HASH_ALG] [--salt HEX] [--block_size SIZE] \
244	[--include_descriptors_from_footer /path/to/image.bin] \
245	[--setup_rootfs_from_kernel /path/to/image.bin] \
246	[--output_vbmeta_image OUTPUT_IMAGE] [--do_not_append_vbmeta_image] \
247	[--generate_fec] [--fec_num_roots FEC_NUM_ROOTS] \
248	[--signing_helper /path/to/external/signer] \
249	[--append_to_release_string STR]
250
251	The integrity footer on an image can be removed from an image. The
252	hashtree can optionally be kept in place.
253
254	$ avbtool erase_footer --image IMAGE [--keep_hashtree]
255
256	For hash- and hashtree-images the vbmeta struct can also be written to
257	an external file via the `--output_vbmeta_image` option and one can
258	also specify that the vbmeta struct and footer not be added to the
259	image being operated on.
260
261	To calculate the maximum size of an image that will fit in a partition
262	of a given size after having used the `avbtool add_hashtree_footer`
263	command on it, use the `--calc_max_image_size` option:
264
265	$ avbtool add_hashtree_footer --partition_size $((10*1024*1024)) \
266	--calc_max_image_size
267	10330112
268
269	The `--signing_helper` option can be used in `make_vbmeta_image`,
270	`add_hash_footer` and `add_hashtree_footer` commands to specify any
271	external program for signing hashes. The data to sign (including
272	padding e.g. PKCS1-v1.5) is fed via `STDIN` and the signed data is
273	returned via `STDOUT`. If `--signing_helper` is present in a command
274	line, the `--key` option need only contain a public key. Arguments for
275	a signing helper are `algorithm` and `public key`. If the signing
276	helper exits with a non-zero exit code, it means failure.
277
278	Here's an example invocation:
279
280	/path/to/my_signing_program SHA256_RSA2048 /path/to/publickey.pem
281
282	The `append_vbmeta_image` command can be used to append an entire
283	vbmeta blob to the end of another image. This is useful for cases when
284	not using any vbmeta partitions, for example:
285
286	$ cp boot.img boot-with-vbmeta-appended.img
287	$ avbtool append_vbmeta_image \
288	--image boot-with-vbmeta-appended.img \
289	--partition_size SIZE_OF_BOOT_PARTITION \
290	--vbmeta_image vbmeta.img
291	$ fastboot flash boot boot-with-vbmeta-appended.img
292
293	## Build system integration notes
294
295	Android Verified Boot is enabled by the `BOARD_AVB_ENABLE` variable
296
297	BOARD_AVB_ENABLE := true
298
299	This will make the build system create `vbmeta.img` which will contain
300	a hash descriptor for `boot.img`, a hashtree descriptor for
301	`system.img`, a kernel-cmdline descriptor for setting up `dm-verity`
302	for `system.img` and append a hash-tree to `system.img`.
303
304	By default, the algorithm `SHA256_RSA4096` is used with a test key
305	from the `external/avb/test/data` directory. This can be overriden by
306	the `BOARD_AVB_ALGORITHM` and `BOARD_AVB_KEY_PATH` variables to use
307	e.g. a 4096-bit RSA key and SHA-512:
308
309	BOARD_AVB_ALGORITHM := SHA512_RSA4096
310	BOARD_AVB_KEY_PATH := /path/to/rsa_key_4096bits.pem
311
312	Remember that the public part of this key needs to be available to the
313	bootloader of the device expected to verify resulting images. Use
314	`avbtool extract_public_key` to extract the key in the expected format
315	(**AVB_pk** in the following). If the device is using a different root
316	of trust than **AVB_pk** the `--public_key_metadata` option can be
317	used to embed a blob (**AVB_pkmd** in the following) that can be used
318	to e.g. derive **AVB_pk**. Both **AVB_pk** and **AVB_pkmd** are passed
319	to the `validate_vbmeta_public_key()` operation when verifying a slot.
320
321	To prevent rollback attacks, the rollback index should be increased on
322	a regular basis. The rollback index can be set with the
323	`BOARD_AVB_ROLLBACK_INDEX` variable:
324
325	BOARD_AVB_ROLLBACK_INDEX := 5
326
327	If this is not set, the rollback index defaults to 0.
328
329	The variable `BOARD_AVB_MAKE_VBMETA_IMAGE_ARGS` can be used to specify
330	additional options passed to `avbtool make_vbmeta_image`. Typical
331	options to be used here include `--prop`, `--prop_from_file`, and
332	`--chain_partition`.
333
334	The variable `BOARD_AVBTOOL_BOOT_ADD_HASH_FOOTER_ARGS` can be used to
335	specify additional options passed to `avbtool add_hash_footer` for
336	`boot.img`. Typical options to be used here include `--hash_algorithm`
337	and `--salt`.
338
339	The variable `BOARD_AVBTOOL_SYSTEM_ADD_HASHTREE_FOOTER_ARGS` can be
340	used to specify additional options passed to `avbtool
341	add_hashtree_footer` for `system.img`. Typical options to be used here
342	include `--hash_algorithm`, `--salt`, `--block_size`, and
343	`--generate_fec`.
344
345	Build system variables (such as `PRODUCT_SUPPORTS_VERITY_FEC`) used
346	for previous version of Verified Boot in Android are not used in AVB
347