Take our usability survey to improve this site.

Resume-on-Reboot

When an OTA is downloaded and prepared to be applied via A/B update, virtual A/B, or another method available via RecoverySystem class, Resume-on-Reboot will attempt to unlock the Credential Encrypted (CE) storage after the device reboots to apply the OTA. This can be paired with an OTA system that applies updates when it is more convenient to the user such as times when the device is expected to be idle.

Background

For application developers, Android supports Direct Boot which enables the apps to start up before the Credential Encrypted (CE) storage is unlocked by the user. As more app developers implement Direct Boot support, the user has a better experience before their Lock Screen Knowledge Factor (LSKF) is entered after a boot.

Resume-on-Reboot allows unlocking the CE storage of all apps, including those that do not yet support Direct Boot, after a reboot initiated by an OTA. This feature enables users to receive notifications from all their installed apps post reboot.

Threat model

An implementation of Resume-on-Reboot must preserve the property that when a device falls into an attacker’s hands, it is extremely difficult for that attacker to recover the user’s CE-encrypted data, even if the device is powered on, CE storage is unlocked, and the user has unlocked the device after receiving an OTA; for insider attack resistance, we also assume the attacker gains access to broadcast cryptographic signing keys.

Specifically, we require that CE storage cannot be read by an attacker who physically has the device and then has these capabilities and limitations:

  • Can use the signing key of any vendor or company to sign arbitrary messages.
  • Can cause an OTA to be received by the device.
  • Can modify the operation of any hardware (Application Processor, flash, etc) except as detailed below, but such modification involves a delay of at least one hour and a power cycle that destroys RAM contents.
  • Cannot modify the operation of tamper-resistant hardware (for example, Titan M).
  • Cannot read the RAM of the live device.
  • Cannot guess the user’s credential (PIN, pattern, password) or otherwise cause it to be entered.

Guidelines to the implementer

As of July 2020 implementations of Resume-on-Reboot HAL broadly fall into two categories:

  1. If the SoC hardware supports RAM persistence across reboots, OEMs can use the default implementation in AOSP (Default RAM Escrow).
  2. If the device hardware or SoC supports a secure hardware enclave (a discrete security co-processor with its own RAM and ROM), additionally it must:
    • Be able to detect main CPU reboot.
    • Have a hardware timer source that persists across reboots; that is, the enclave must be able to detect the reboot and expire a timer set before the reboot.
    • Support storing an escrowed key in the enclave RAM/ROM such that it can't be recovered with offline attacks. It must store the Resume-on-Reboot key in a way that makes it impossible for insiders or attackers to recover it.

Default RAM Escrow

AOSP has an implementation of the Resume-on-Reboot HAL using RAM persistence. For this to work, OEMs must ensure that their SoCs support RAM persistence across reboots. Some SoCs are unable to persist RAM contents across a reboot, so OEMs are advised to consult their SoC partners before enabling this default HAL. The canonical reference for this in the section below.

When an OTA is downloaded and prepared to be applied by means of A/B update, virtual A/B, or another method available via RecoverySystem class, Resume-on-Reboot will attempt to unlock the Credential Encrypted (CE) storage after the device reboots to apply the OTA update. This can be paired with an OTA system that applies updates when it is more convenient to the user such as times when the device is expected to be idle.

Flow of OTA update using Resume-on-Reboot

The OTA client app on the phone must have the Manifest.permission.REBOOT and Manifest.permisson.RECOVERY permissions to call the necessary methods to implement Resume-on-Reboot. With that prerequisite in place, the flow of an update is:

  1. OTA client app downloads update
  2. OTA client app calls to RecoverySystem#prepareForUnattendedUpdate which triggers the user to be prompted for their PIN, pattern, or password on the lock screen during the next unlock
  3. When the user next unlocks the device at the lockscreen, the device is ready to have the update applied
  4. OTA client app calls to RecoverySystem#rebootAndApply which immediately triggers a reboot

At the end of this flow, the device reboots and the Resume-on-Reboot mechanism unlocks the credential encrypted (CE) storage. To apps, this appears as a normal user unlock, so they receive all the signals, such as ACTION_LOCKED_BOOT_COMPLETED and ACTION_BOOT_COMPLETED as they normally would.

Modifying product configurations

In order for a product to be marked as supporting the Resume-on-Reboot feature, it must include an implementation of the RebootEscrow HAL and include the feature marker XML file. The default implementation works well on devices that use warm reboot (that is, power is not removed from DRAM during reboot).

Reboot escrow feature marker

The feature marker must also be present:

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.reboot_escrow.xml:$(TARGET_COPY_OUT_VENDOR)/etc/permissions/android.hardware.reboot_escrow.xml

Default reboot escrow HAL implementation

To use the default implementation, 65536 (0x10000) bytes must be reserved for the implementation. These bytes must not be written to non-volatile storage for the security properties to hold.

Linux kernel device tree changes

In the Linux kernel's device tree, you must reserve memory for a pmem region. In the following example 0x50000000 has been reserved:

  reserved-memory {
    my_reservation@0x50000000 {
      no-map;
      reg = <0x50000000 0x10000>;
    }
  }

  reboot_escrow@0 {
    compatible = "pmem-region";
    reg = <0x50000000 0x10000>;
  };

Verify that you have a new device in the block directory with a name like /dev/block/pmem0 (such as pmem1 or pmem2).

Device.mk changes

Assuming that your new device from the previous step is named pmem0, the following new entries must be added to vendor/<oem>/<product>/device.mk:

# Resume on Reboot support
PRODUCT_PROPERTY_OVERRIDES += \
    ro.rebootescrow.device=/dev/block/pmem0
PRODUCT_PACKAGES += \
    android.hardware.rebootescrow-service.default

SELinux rules

New entries to the device's file_contexts must be added:

/dev/block/pmem0  u:object_r:rebootescrow_device:s0
/vendor/bin/hw/android\.hardware\.rebootescrow-service\.default  u:object_r:hal_rebootescrow_default_exec:s0