Snap for 6660490 from 01553a27989ebcb915bb80dedf9d49b06ed41867 to sdk-release
Change-Id: I285c4e3cb5defac4f76f2e46cf9efe2b9dec7527
diff --git a/avbtool.py b/avbtool.py
index 7dfbbc0..1211df3 100755
--- a/avbtool.py
+++ b/avbtool.py
@@ -2385,12 +2385,13 @@
misc_image.seek(self.AB_MISC_METADATA_OFFSET)
misc_image.write(ab_data)
- def info_image(self, image_filename, output):
+ def info_image(self, image_filename, output, atx):
"""Implements the 'info_image' command.
Arguments:
image_filename: Image file to get information from (file object).
output: Output file to write human-readable information to (file object).
+ atx: If True, show information about Android Things eXtension (ATX).
"""
image = ImageHandler(image_filename, read_only=True)
o = output
@@ -2443,6 +2444,31 @@
if num_printed == 0:
o.write(' (none)\n')
+ if atx and header.public_key_metadata_size:
+ o.write('Android Things eXtension (ATX):\n')
+ key_metadata_offset = (header.SIZE +
+ header.authentication_data_block_size +
+ header.public_key_metadata_offset)
+ key_metadata_blob = vbmeta_blob[key_metadata_offset: key_metadata_offset
+ + header.public_key_metadata_size]
+ version, pik, psk = struct.unpack('<I1620s1620s', key_metadata_blob)
+ o.write(' Metadata version: {}\n'.format(version))
+
+ def print_atx_certificate(cert):
+ version, public_key, subject, usage, key_version, _signature = \
+ struct.unpack('<I1032s32s32sQ512s', cert)
+ o.write(' Version: {}\n'.format(version))
+ o.write(' Public key (sha1): {}\n'.format(
+ hashlib.sha1(public_key).hexdigest()))
+ o.write(' Subject: {}\n'.format(subject.hex()))
+ o.write(' Usage: {}\n'.format(usage.hex()))
+ o.write(' Key version: {}\n'.format(key_version))
+
+ o.write(' Product Intermediate Key:\n')
+ print_atx_certificate(pik)
+ o.write(' Product Signing Key:\n')
+ print_atx_certificate(psk)
+
def verify_image(self, image_filename, key_path, expected_chain_partitions,
follow_chain_partitions, accept_zeroed_hashtree):
"""Implements the 'verify_image' command.
@@ -4428,6 +4454,10 @@
help='Write info to file',
type=argparse.FileType('wt'),
default=sys.stdout)
+ sub_parser.add_argument('--atx',
+ help=('Show information about Android Things '
+ 'eXtension (ATX).'),
+ action='store_true')
sub_parser.set_defaults(func=self.info_image)
sub_parser = subparsers.add_parser(
@@ -4765,7 +4795,7 @@
def info_image(self, args):
"""Implements the 'info_image' sub-command."""
- self.avb.info_image(args.image.name, args.output)
+ self.avb.info_image(args.image.name, args.output, args.atx)
def verify_image(self, args):
"""Implements the 'verify_image' sub-command."""
diff --git a/docs/aftl-architecture.png b/docs/aftl-architecture.png
new file mode 100644
index 0000000..5526f92
--- /dev/null
+++ b/docs/aftl-architecture.png
Binary files differ
diff --git a/docs/aftl-boot-flow.png b/docs/aftl-boot-flow.png
new file mode 100644
index 0000000..f724808
--- /dev/null
+++ b/docs/aftl-boot-flow.png
Binary files differ
diff --git a/docs/aftl-image-location.png b/docs/aftl-image-location.png
new file mode 100644
index 0000000..0e609d7
--- /dev/null
+++ b/docs/aftl-image-location.png
Binary files differ
diff --git a/docs/aftl-image-structure.png b/docs/aftl-image-structure.png
new file mode 100644
index 0000000..2487314
--- /dev/null
+++ b/docs/aftl-image-structure.png
Binary files differ
diff --git a/libavb_aftl/README.md b/libavb_aftl/README.md
new file mode 100644
index 0000000..abf2636
--- /dev/null
+++ b/libavb_aftl/README.md
@@ -0,0 +1,305 @@
+# Android Firmware Transparency Log 1.0
+---
+
+This repository contains tools and libraries for working with the Android
+Firmware Transparency Log components of Android Verified Boot. AFTL will be
+used to refer to these components.
+
+[TOC]
+
+# What is it?
+
+The Android Firmware Transparency Log (AFTL) is an implementation of binary
+transparency that leverages cryptographic proofs of inclusion of build images
+using a public append-only ledger. The device manufacturer stores these
+cryptographic proofs, called inclusion proofs, on-device to allow for offline
+validation of the build during system update and device boot. This ensures that
+only a publicly known build is running on the device. Furthermore, it allows
+device manufacturers and other interested parties to audit the information in
+the log to detect unexpected or malicious uses of the publisher's signing keys.
+
+
+## System overview
+
+An AFTL can be implemented using a
+[Trillian](https://github.com/google/trillian) instance which manages a Merkle
+tree with build metadata (particularly the [VBMeta
+struct](https://android.googlesource.com/platform/external/avb/+/refs/heads/master#The-VBMeta-struct))
+and keeps a repository of other data that were made transparent.
+
+
+
+As part of the finalizing step in the build process the `aftltool` reaches out
+to the **AFTL personality** to submit a manufacturer-signed message (containing
+VBMeta struct and other metadata) to the AFTL. Then the AFTL personality
+submits that data to Trillian to incorporate it into the Merkle tree. After
+integration into the log, the AFTL personality returns the inclusion proof back
+to the `aftltool`, which in turn incorporates the inclusion proof with the
+VBMeta image.
+
+The AFTL uses two sets of keys for authentication and validation, the
+transparency log key and the manufacturer key.
+
+* **Transparency log key:** Used by Trillian to sign inclusion proofs. The
+ public key is embedded with the device for on-device for validation.
+* **Manufacturer key:** Used by OEMs or other build providers to sign
+ submissions sent to the log. This ensures that malicious entries posing as a
+ valid OEM entry cannot be provided to the log. For the log to authenticate
+ messages, the manufacturer key must be shared out-of-band with the AFTL prior
+ to submission.
+
+## The AftlImage struct
+
+The central data structure used for AFTL validation is the `AftlImage` struct.
+The structure is saved on the vbmeta partition, right after the
+`AvbVBMetaImage` struct, as illustrated below.
+
+
+
+This structure contains the `AftlImageHeader` header that describes the number
+of inclusion proofs (`AftlIcpEntry`) represented by this structure. Each
+inclusion proof has associated metadata, such as the transparency log URL. A
+high-level description of the structures is given below. See
+[aftltool](https://android.googlesource.com/platform/external/avb/+/refs/heads/master/aftltool.py)
+and
+[libavb_aftl](https://android.googlesource.com/platform/external/avb/+/refs/heads/master/libavb_aftl/)
+for more details.
+
+
+
+
+Each `AftlIcpEntry` structure contains the information required to validate an
+inclusion proof from a specific transparency log server for a given [VBMeta
+structure](https://android.googlesource.com/platform/external/avb/+/master#the-vbmeta-struct)
+given the corresponding transparency log public key. The inclusion proof
+validation process is described in the [inclusion proofs](#inclusion-proofs)
+section of this document.
+
+*Note*: A single `AftlImage` can have multiple inclusion proofs from different
+transparency logs. This allows the device manufacturer to not rely on a single
+transparency log, and ensures that the builds represented by the VBMeta
+structure are deemed transparent in multiple disparate jurisdictions.
+
+## Inclusion proofs
+
+An inclusion proof allows a user to prove that a specific VBMeta structure is
+included in a transparency log. An inclusion proof consists of three parts:
+
+* A `SignedVBMetaPrimaryAnnotation` structure containing the hash of the
+VBMeta structure (and other build meta information) that is signed with the
+manufacturer key.
+* A set of sibling node hashes (`Proof`) in a Merkle tree on the path from the
+leaf node in question, which represents the logged annotation, to the root
+node.
+* A `TrillianLogRootDescriptor` structure containing the log's root hash,
+along with related metadata, which is signed by the transparency log’s private
+key.
+
+Validation of an inclusion proof can be performed with the following steps,
+which are implemented in both `aftltool` and `libavb_aftl`.
+
+1. Calculate the hash of the VBMeta structure stored on the device.
+1. Determine if the hash matches the hash stored in the
+`SignedVBMetaPrimaryAnnotation` structure inside the `AftlImage` on device. If
+it does, continue validation.
+1. Given the set of hashes provided from the transparency log as part of the
+inclusion proof, attempt to recalculate the root hash. Details of the process
+can be found [here](https://www.certificate-transparency.org/log-proofs-work)
+in the Merkle Audit Proofs section.
+1. Check the calculated root hash against the log's root hash from the
+inclusion proof. If it matches, continue validation.
+1. Finally, verify the log root signature given the calculated root hash and
+the public key of the transparency log that is stored on device. If the
+signature is valid, the inclusion proof is valid.
+
+# Tools and libraries
+
+This section contains information about the tools and libraries added to AVB
+repository or modified to include AFTL support.
+
+## aftltool and libavb\_aftl
+
+The main purpose of
+[aftltool](https://android.googlesource.com/platform/external/avb/+/refs/heads/master/aftltool.py)
+is to add an inclusion proof to an existing `vbmeta.img` to be used
+for transparency checks at boot or system update time. This enhanced image is
+stored in the `vbmeta` partition or in the `vbmeta_a` and
+`vbmeta_b` slots when using A/B and will still be of minimal size
+(for out-of-band updates). Creation, query, and verification tasks can be
+performed with `aftltool`.
+
+In addition to the `aftltool`, the
+[libavb](https://android.googlesource.com/platform/external/avb/+/master/libavb/)
+library comes with an extension called
+[libavb\_aftl](https://android.googlesource.com/platform/external/avb/+/master/libavb_aftl/).
+This component performs all verification on the device side related to AFTL and
+inclusion proofs. That is, it loads the `vbmeta` partition, checks
+the VBMeta structure signature, walks through each inclusion proof stored in
+the `AftlImage`, and validates them against a trusted transparency
+log key stored on the device.
+
+This library is intended to be used in both the boot loader and inside Android
+as part of the OTA client. The main entry point for verification is
+`aftl_slot_verify()`, which is intended to be called after `vbmeta`
+verification is done via `avb_slot_verify()`.
+
+## Files and directories
+
+* `libavb_aftl/`
+ + An implementation of AFTL inclusion proof validation. This
+ code is designed to be highly portable so it can be used in as many contexts
+ as possible. This code requires a C99-compliant C compiler. Only the content
+ declared in `libavb_aftl.h` is considered public. The other files are
+ considered internal to the implementation and may change without notice.
+* `libavb_aftl/README.md`
+ + This document.
+* `test/`
+ + Unit tests for `libavb_aftl.`
+* `test/data/`
+ + Test data for the `aftltool` and `libavb_aftl` unit tests.
+* `aftltool`
+ + A symlink to `aftltool.py`.
+* `aftltool.py`
+ + A tool written in Python for working with images related to AFTL.
+* `Android.bp`
+ + Build rules for `aftltool`, `libavb_aftl` (a static library
+ for use on the device), host-side libraries (for unit tests), and unit
+ tests.
+* `aftltool_test.py`
+ + Source-code for `aftltool` related unit tests.
+* `aftltool_integration_test.py`
+ + Source-code for `aftltool` related integration tests against
+ a live transparency log.
+
+## Portability
+
+The `libavb_aftl` code is intended to be used in bootloaders in devices that
+will load Android or other operating systems. The suggested approach is to copy
+the appropriate header and C files mentioned in the previous section into the
+boot loader and integrate as appropriate. The library is intended to be highly
+portable, working on both little and big endian architectures, as well as
+32-bit and 64-bit variants of each. It is also intended to work in environments
+without the standard C library and runtime.
+
+As in libavb, if the `AVB_ENABLE_DEBUG` preprocessor symbol is set, the code
+will include useful debug information and run-time checks.
+
+## Versioning and compatibility
+
+The `libavb_aftl` library follows the [versioning of
+libavb](https://android.googlesource.com/platform/external/avb/+/master#Versioning-and-Compatibility).
+
+## Using aftltool
+
+The content for the vbmeta partition is assumed to have been generated
+previously using `avbtool`. Instructions can be found in the
+[README.md](https://android.googlesource.com/platform/external/avb/+/master/README.md)
+for libavb. After the VBMeta partition is generated, it can be extended with
+inclusion proofs from transparency logs in the following manner:
+
+
+```
+aftltool make_icp_from_vbmeta \
+ --vbmeta_image_path /path/to/image.bin \
+ --output OUTPUT \
+ [--signing_helper /path/to/external/signer] \
+ [--signing_helper_with_files /path/to/external/signer_with_files] \
+ --version_incremental STR \
+ --transparency_log_servers host:port,/path/to/log_key.pub \
+ --manufacturer_key /path/to/priv_key \
+ [--padding_size NUM]
+```
+
+The
+[version\_incremental](https://developer.android.com/reference/android/os/Build.VERSION#INCREMENTAL)
+is a part of the build fingerprint which allows for tagging the transparency
+log entry for easier tracking.
+
+An example of how to use the `make_icp_from_vbmeta` command is as follows:
+
+```
+aftltool make_icp_from_vbmeta \
+ --vbmeta_image_path ./vbmeta.img \
+ --output ./vbmeta_icp.img \
+ --version_incremental 99999999 \
+ --transparency_log_servers \
+ log.aftl-android.com:9000,/aftl-log-rsa-pub.pem \
+ --manufacturer_key ./manufacturer-rsa.pem \
+ --algorithm SHA256_RSA4096 \
+ --padding 4096
+```
+
+The AFTL information can be viewed in a human readable format in the following
+manner:
+
+```
+aftltool info_image_icp \
+ --vbmeta_image_path /path/to/image.bin \
+ [--output OUTPUT]
+```
+
+An example using `info_image_icp` is as follows:
+
+```
+aftltool info_image_icp --vbmeta_image_path ./vbmeta.img
+```
+
+Verification of an AFTL enhanced vbmeta image can be performed with the
+following command:
+
+```
+aftltool verify_image_icp \
+ --vbmeta_image_path /path/to/image.bin \
+ --transparency_log_pub_keys [TRANSPARENCY_LOG_PUB_KEYS [TRANSPARENCY_LOG_PUB_KEYS ...]]
+[--output OUTPUT]
+```
+
+An example using `verify_image_icp` is as follows:
+
+```
+aftltool verify_image_icp --vbmeta_image_path ./vbmeta.img --transparency_log_pub_keys ./log_pub_key.pem
+```
+
+More information on the options can be found using `aftltool --help`.
+
+# Build system integration
+
+AFTL modifications only will work if AVB is enabled in the build. In Android,
+AVB is enabled in an `Android.mk` file by the `BOARD_AVB_ENABLE` variable as
+described in the AVB
+[README.md](https://android.googlesource.com/platform/external/avb/#Build-System-Integration).
+
+When calling the
+[sign\_target\_files\_apks.py](https://android.googlesource.com/platform/build/+/master/tools/releasetools/sign_target_files_apks.py)
+script, the following parameters must be set:
+
+* `--aftl_tool_path`, the location of aftltool.py
+* `--aftl_server`, the address of the transparency log
+* `--aftl_key_path`, which gives the path to the DER encoded transparency log public key
+* `--aftl_manufacturer_key_path`, which gives the path to the DER encoded OEM
+ private key. Note: This key is different to the signing key used to sign VBMeta
+ structure
+
+Remember that the public part of the transparency log keys need to be available
+to the bootloader of the device to validate the inclusion proofs.
+
+# Device integration
+
+This section discusses recommendations and best practices for integrating
+`libavb` AFTL support with a device boot loader. It's important to emphasize
+that these are just recommendations. Most of these recommendations are the same
+as those for AVB.
+
+## Recommended bootflow
+
+The boot flow should ensure checking of the inclusion proofs independent of the
+unlock state of the device. It is recommended to present the user with a
+warning in case transparency checks fail.
+
+AFTL modifies this flow in the following manner: as soon as a valid OS has been
+found, search for an `AftlImage` for each VBMeta image and validate their
+inclusion proofs (this is done by the `aftl_slot_verify` function). The result
+of the verification can be appended to the kernel command line for further
+processing by the OS.
+
+
