apps/boot/README.md

# Verified Boot Storage Applet for AVB 2.0

  - Status: Draft as of April 6, 2017

## Introduction

The application and support libraries in this directory provide
a mechanism for a device's bootloader, using [AVB](https://android.googlesource.com/platform/external/avb/),
to store sensitive information.  For a bootloader, sensitive information
includes whether the device is unlocked or locked, whether it is unlockable,
and what the minimum version of the OS/kernel is allowed to be booted.  It
may also store other sensitive flags.

The verified boot storage applet provides a mechanism to store this
data in a way that enforceѕ the expected policies even if the higher level
operating system is compromised or operates in an unexpected fashion.


## Design Overview

The Verified Boot Storage Applet, VBSA, provides three purpose-built
interfaces:

  - Lock storage and policy enforcement
  - Rollback index storage
  - Applet state

Each will be detailed below.

### Locks

There are four supported lock types:

  - `LOCK_CARRIER`
  - `LOCK_DEVICE`
  - `LOCK_BOOT`
  - `LOCK_OWNER`

Each lock has a single byte of "lock" storage.  If that byte is 0x0, then it is
unlocked, or cleared.  If it is non-zero, then the lock is locked.  Any
non-zero value is valid and may be used by the bootloader if any additional
internal flagging is necessary.

In addition, a lock may have associated metadata which must be supplied during
lock or unlock, or both.

See `ese_boot_lock_*` in include/ese/app/boot.h for the specific interfaces.


#### LOCK\_CARRIER

The Carrier Lock implements a lock which can only be set when the device is not
in production and can only be unlocked if provided a cryptographic signature.

This lock is available for use to implement "sim locking" or "phone locking"
such that the carrier can determine if the device is allowed to boot an
unsigned or unknown system image.

To provision this lock, device-specific data must be provided in an exact
format.  An example of this can be found in
`'ese-boot-tool.cpp':collect_device_data()`.  This data is then provided to
the applet using `ese_boot_lock_xset()`.

##### Metadata format for locking/provisioning

The following system attributes must be collected in the given order:

  - ro.product.brand
  - ro.product.device
  - ro.build.product
  - ro.serialno
  - [Modem ID: MEID or IMEI]
  - ro.product.manufacturer
  - ro.product.model

The data is serialized as follows:

    \[length||string\]\[...\]

The length is a `uint8_t` and the value is appended as a stream of
`uint8_t` values.

This data is then prefixed with the desired non-zero lock value before
being submitted to the applet.  If successful, the applet will have
stored a SHA256 hash of the device data

Note, `LOCK_CARRIER` can only be locked (non-zero lock value) when the
applet is not in 'production' mode.

##### Clearing/unlocking

If `LOCK_CARRIER` is set to a non-zero value and the applet is in
production mode, then clearing the lock value requires authorization.

Authorization comes in the form of a `RSA_SHA256-PKCS#1` signature over
the provisioned device data SHA256 hash and a supplied montonically
increasing "nonce".

The nonce value must be higher than the last seen nonce value and the
signature must validate using public key internally stored in the
applet (`CarrierLock.java:PK_MOD`).

To perform a clear, `ese_boot_lock_xset()` must be called with lock
data that begins with 0x0, to clear the lock, and then contains data of
the following format:

```
    unlockToken = VERSION || NONCE || SIGNATURE

    SIGNATURE = RSA_Sign(SHA256(deviceData))
```

  - The version is a little endian `uint64_t` (8 bytes).
  - The nonce is a little endian `uint64_t` (8 bytes).
  - The signature is a RSA 2048-bit with SHA-256 PKCS#1 v1.5 (256 bytes).

On unlock, the device data hash is cleared.

##### Testing

It is possible to test the key with a valid signature but a fake
internal nonce and fake internal device data using
`ese_boot_carrier_lock_test()`.  When using this interface, it
expects the same unlock token as in the prior but prefixes with the
fake data:

```
    testVector = LAST_NONCE || DEVICE_DATA || unlockToken
```

  - The last nonce is the value the nonce is compared against (8 bytes).
  - Device data is a replacement for the internally stored SHA-256
    hash of the deviec data. (32 bytes).

#### LOCK\_DEVICE

The device lock is one of the setting used by the bootloader to
determine if the boot lock can be changed.  It may only be set by the
operating system and is meant to protect the device from being reflashed
by someone that cannot unlock or access the OS.  This may also be used
by an enterprise administrator to control lock policy for managed
devices.

As `LOCK_DEVICE` has not metadata, it can be set and retrieved using
`ese_boot_lock_set()` and `ese_boot_lock_get()`.

#### LOCK\_BOOT

The boot lock is used by the bootloader to control whether it should
only boot verified system software or not.  When the lock value
is cleared (0x0), the bootloader will boot anything.  When the lock
value is non-zero, it should only boot software that is signed by a key
stored in the bootloader except if `LOCK_OWNER` is set.  Discussion of
`LOCK_OWNER` will follow.

`LOCK_BOOT` can only be toggled when in the bootloader/fastboot and if
both `LOCK_CARRIER` and `LOCK_DEVICE` are cleared/unlocked.

As with `LOCK_DEVICE`, `LOCK_BOOT` has no metadata so it does not need the
extended accessors.

#### LOCK\_OWNER

The owner lock is used by the bootloader to support an alternative
OS signing key provided by the device owner.  `LOCK_OWNER` can only be
toggled if `LOCK_BOOT` is cleared. `LOCK_OWNER` does not require
any metadata to unlock, but to lock, it requires a blob of up to 2048
bytes be provided.  This is just secure storage for use by the
bootloader.  `LOCK_OWNER` may be toggled in the bootloader or the
operating system.  This allows an unlocked device (`LOCK_BOOT=0x0`) to
install an owner key using fastboot or using software on the operating
system itself.

Before `LOCK_OWNER`'s key should be honored by the bootloader, `LOCK_BOOT`
should be set (in the bootloader) to enforce use of the key and to keep
malicious software in the operating system from changing it.

(Note, that the owner key should not be treated as equivalent to the
bootloader's internally stored key in that the device user should have a
means of knowing if an owner key is in use, but the requirement for the
device to be unlocked implies both physical access the `LOCK_DEVICE`
being cleared.)


### Rollback storage

Verifying an operating system kernel and image is useful both for system
reliability and for ensuring that the software has not been modified by
a malicious party.  However, if the system software is updated,
malicious software may attempt to "roll" a device back to an older
version in order to take advantage of mistakes in the older, verified
code.

Rollback index values, or versions, may be stored securely by the bootloader
to prevent these problems.  The Verified Boot Storage applet provides
eight 64-bit slots for storing a value.  They may be read at any time,
but they may only be written to when the device is in the bootloader (or
fastboot).

Rollback storage is written to using
`ese_boot_rollback_index_write()` and read using
`ese_boot_rollback_index_read()`.

### Applet state

The applet supports two operational states:

  - production=true
  - production=false

On initial installation, production is false.  When the applet is not
in production mode, it does not enforce a number of security boundaries,
such as requiring bootloader or hlos mode for lock toggling or
CarrierLock verification.  This allows the factory tools to run in any
mode and properly configure a default lock state.

To transition to "production", a call to `ese_boot_set_production(true)`
is necessary.

To check the state and collect debugging information, the call
`ese_boot_get_state()` will return the current bootloader value,
the production state, any errors codes from lock initialization, and the
contents of lock storage.

#### Example applet provisioning

After the applet is installed, a flow as follows would prepare the
applet for use:

  - `ese_boot_session_init();`
  - `ese_boot_session_open();`
  - `ese_boot_session_lock_xset(LOCK_OWNER, {0, ...});`
  - `ese_boot_session_lock_set(LOCK_BOOT, 0x1);`
  - `ese_boot_session_lock_set(LOCK_DEVICE, 0x1);`
  - [collect device data]
  - `ese_boot_session_lock_set(LOCK_CARRIER, {1, deviceData});`
  - `ese_boot_session_set_production(true);`
  - `ese_boot_session_close();`

### Additional details

#### Bootloader mode

Bootloader mode detection depends on hardware support to signal the
applet that the application processor has been reset.  Additionally,
there is a mechanism for the bootloader to indicate that is loading the
main OS where it flips the value.  This signal provides the assurances
around when storage is mutable or not during the time a device is
powered on.

#### Error results

EseAppResult is an enum that all `ese_boot_*` functions return.  The
enum only covers the lower 16-bits.  The upper 16-bits are reserved for
passing applet and secure element OS status for debugging and analysis.
When the lower 16-bits are `ESE_APP_RESULT_ERROR_APPLET`, then the
upper bytes will be the applet code. That code can then be
cross-referenced in the applet by function and code.  If the lower
bytes are `ESE_APP_RESULT_ERROR_OS`, then the status code are the
ISO7816 code from an uncaught exception or OS-level error.

##### Cooldown

`ESE_APP_RESULT_ERROR_COOLDOWN` indicates that the secure element needs to
stay powered on for a period of time -- either at the end of use or before the
requested command can be serviced.  As the behavior is implementation specific,
the only effective option is to keep the secure element powered for the number of
seconds specified by the response `uint32_t`.

For chips that support it, like the one this applet is being tested on, the
cooldown time can be requested with a special APDU to `ese_transceive()`:

```
    FFE10000
```

In response, a 6 byte response will contain a `uint32_t` and a successful status
code (`90 00`).  The unsigned little-endian integer indicates how many seconds
the chip needs to stay powered and unused to cooldown.  If this happens before
the locks or rollback storage can be read, the bootloader will need to
determine a safe delay or recovery path until boot can proceed securely.

## Examples

There are many ways to integrate this library and the associated applet.
Below are some concrete examples to guide standard approach.

### Configuration in factory

- Install configure the secure element and install the applets  
(outside of the scope of this document).
- Boot to an environment to run the ese-boot-tool.
- Leave the inBootloader() signal asserted (recommended but not required).
- Configure the desired lock states:
  - `# ese-boot-tool lock set carrier 1 modem-imei-string`
  - `# ese-boot-tool lock set device 1`
  - `# ese-boot-tool lock set boot 1`
  - `# ese-boot-tool lock set owner 0`
- To move from factory mode to production mode call:
  - `# ese-boot-tool production set true`

### Configuration during repair

- Boot to an environment to run the ese-boot-tool.
- Leave inBootloader() signal asserted or implement the steps below in  
  the bootloader.
- Transition out of production mode:
  - `# ese-boot-tool production set false`
- If a `LOCK_CARRIER` problem is being repaired, it is possible to reset the  
  internal nonce counter and all lock state with the command below.  A full  
  lock reset is not expected in most cases.
  - `# ese-boot-tool lock reset`
- Reconfigure the lock states:
  - `# ese-boot-tool lock set carrier 1 modem-imei-string`
  - `# ese-boot-tool lock set device 1`
  - `# ese-boot-tool lock set boot 1`
  - `# ese-boot-tool lock set owner 0`
    (To clear data from the owner lock, set owner 1 must be called with  
     4096 00s.)
- Then move back to production mode:
  - `# ese-boot-tool production set true`

### Use during boot

Do not load any non-repair or non-factory OS without clearing the inBootloader
signal as the applet may be transitioned out of production mode and/or the
rollback state may be changed.

#### Checking rollback values

- Read and write rollback values as per libavb using the API
  - `ese_boot_rollback_index_write()`
  - `ese_boot_rollback_index_read()`
- Prior to leaving the bootloader, clear the inBootloader signal.

As rollback index values can only be written when inBootloader signal is set,
it is critical to clear it when leaving the bootloader.

#### Checking locks

The pseudo-code and comments below should outline the basic algorithm, but it
does not include integration into libavb or include use of rollback index
value checking:

```
// Read LOCK_BOOT
ese_boot_lock_get(session, kEseBootLockIdBoot, &lockBoot);

if (lockBoot != 0x0) {  // Boot is LOCKED.
    // Read the LOCK_OWNER
    ese_boot_lock_xget(session, kEseBootLockIdOwner, &lockOwner);
    if (lockOwner != 0x0) {  // Owner is LOCKED
      // Get the lock owner value with metadata.
      // This is done as a second stage to avoid wasted copying when it
      // is not locked.
      uint8_t ownerData[kEseBootOwnerKeyMax + 1];
      ese_boot_lock_xget(session, kEseBootLockIdOwner, ownerData
                         sizeof(ownerData), &ownerDataUsed);
      // lockOwner == ownerData[0]
      // Parse the stored metadata into a key as per your bootloader
      // design.
      SomeBootKey key;
      parseDeviceOwnerKeyForBooting(ownerData + 1, ownerDataUsed, &key);
      // Boot using the supplied owner key
      // (E.g., as part of avb_validate_vbmeta_public_key())
      setDeviceOwnerKeyForBooting(&key);
      continueBootFlow();
} else {  // Boot is UNLOCKED (0x0)
    // Perform the boot flow.
    setBootIsUnverified();
    continueBootFlow();
}
```

### In fastboot

- `LOCK_BOOT` may be toggled by a fastboot command.  If the conditions of  
  unlock are not allowed by applet policy, it will fail.
- `LOCK_OWNER`may be toggled and set a boot key from a fastboot command  
  or from an unlocked OS image.
- If the verified boot design dictates that rollback indices are clear on  
  lock/unlock, this can be done by calling
  - `ese_boot_rollback_index_write()` on each slot with the value of 0.

Note, `LOCK_DEVICE` and `LOCK_CARRIER` should not need to be used by fastboot.

For debugging and support, it may be desirable to connect the
`ese_boot_get_state()` to allow fastboot to return the current value of
production, inbootloader, and the lock metadata.