GPG key management

Introduction

To ensure all updates are signed, yet allow us to allow external entities to sign updates and handle the case where our key is compromised, the following GPG setup will be implemented.

Two different bits need to do GPG verification:

The following GPG key chain will be used:

The client has 4 keyrings:

The client will ship with the archive master keyring on disk. If the client is shipped with the image-master and image-signing keyrings, the associated .tar.xz and .tar.xz.asc files will also be provided (see below). Those will be updated as needed by the client. The upgrader will ship with just the archive master keyring.

The client pushes the image-master, image-signing, and device-signing (if present) keyring tar.xz and .tar.xz.asc (signature) files to the cache partition for the upgrader to use. The upgrader will attempt to read the blacklist from the system partition, should it fail to do so, it'll continue without blacklist.

Signing and Validation

In the descriptions below, when a file's signature is checked for validity, it must be DIRECTLY signed by the specified key. Specifically, indirect signature chains are NOT supported. For example, if a file is said to be DIRECTLY signed by the image-signing key, only the image-signing key (inside the associated keyring) is acceptable. The file cannot be signed by the image-master key or the archive-master key, even though the image-signing key is signed by the image-master.

Another point to clarify. Some files may be signed by either the image-signing key, or the device-signing key if there is one. When the device-signing key is specified (i.e. in the index.json file), then files signed by either key are accepted.

Blacklist keyring

The blacklist keyring is a bit special. It differs from the others in that any key in that keyring is considered invalid during any signature validation process, regardless of whether the key is valid, revoked, or expired. Think of it as a set operation; we take the set of keys that signed a file and difference it with all the keys in the blacklist. The remaining keys are the valid signatures of the file.

This keyring is downloaded by the client, stored alongside the others in the data partition (but not in a user writable location) and ISN'T passed to the upgrader. Instead the upgrader accesses it directly from the data partition. If it can find it, it uses it, if it can't, it doesn't. A missing blacklist keyring won't lead to upgrade failure.

The reason behind this is that we need to always use an up-to-date blacklist keyring coming from a user inaccessible location. Otherwise, a user flashing using eMMC could simply skip that keyring (as it's optional) and provide files signed from a compromised key (before the matching keyring expires) which would then be considered valid. Similarly, we can't make the blacklist keyring mandatory as the user could then simply provide an older version of it when updating from eMMC. We can't make the keyring expire every month either as that keyring is signed by image-master key and so signature can't be automated.

Therefore the current design is the only reliable way of rapidly revoking keys and ensuring that no revoked key may be used for both over-the-air and over-the-wire updates.

Files

Keyrings

Other files

GPG keyring tarball format

The GPG keyrings will be distributed as .tar.xz tarballs with a detached (.asc) GPG signature.

The content of those tarballs will be made of two files: 

{
    'expiry': 123456,
    'type': 'blacklist',
    'model': nexus7
}

Use cases

Standard update

compromised device key

procedure

  1. Revoke the key if possible and publish to the GPG network
  2. Add the key to the blacklist keyring, have the keyring signed by the IMAGE MASTER key
  3. Issue a new device-signing key (or keys depending on vendor)
  4. Generate a new device-signing keyring with the new key
  5. Sign the new device keyring with the IMAGE SIGNING key
  6. Re-sign any index.json and tarball that were signed by the old key

effect on the client

effect on the upgrader

compromised IMAGE SIGNING key

procedure

  1. Revoke the key and publish to the GPG network
  2. Add the key to the blacklist keyring, have the keyring signed by the IMAGE MASTER key
  3. Issue a new IMAGE SIGNING key
  4. Generate a new image-signing keyring with the new key
  5. Sign the new image-signing keyring with the IMAGE MASTER key
  6. Re-sign channels.json, all the index.json, all the device-signing keyrings and any tarball that were signed by the old IMAGE SIGNING key

effect on the client

effect on the upgrader

compromised IMAGE MASTER key

procedure

  1. Revoke the key and publish to the GPG network
  2. Issue a new IMAGE MASTER key
  3. Add the key to the blacklist keyring, have the keyring signed by the new IMAGE MASTER key
  4. Generate a new image-master keyring with the new key
  5. Sign the new image-master keyring with the ARCHIVE MASTER key
  6. Re-sign the image-signing keyring with the new IMAGE MASTER key

effect on the client

effect on the upgrader

compromised archive master key

That should never happen as there's nothing we can do if that happens short of re-generating all the keys and hoping we can get the users to update to a fixed system before anyone abuses the compromised key.

ImageBasedUpgrades/GPG (last edited 2013-06-21 14:41:31 by stgraber)