GPG

Revision 17 as of 2013-06-11 19:54:45

Clear message

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:

  • Update client (validate channels.json, index.json and all files)
  • Upgrader (validate all files)

The following GPG key chain will be used:

The client has 4 keyrings:

  • master - mandatory, persistent, contains the MASTER key, unsigned (never changes, never expires)
  • system-image - mandatory, persistent, contains the SYSTEM IMAGE MASTER key, signed by the MASTER key (hopefully never changes, never expires)
  • signing - mandatory, persistent, contains the SYSTEM IMAGE SIGNING key, signed by the SYSTEM IMAGE MASTER key (updated regularly, expires after 2 years)
  • device - optional, temporary, contains the keys valid for the index.json and update files for the device, signed by the SYSTEM IMAGE SIGNING key (updated regularly, expires after a month)
  • blacklist - optional, persistent, contains any key that should no longer be trusted, signed by the SYSTEM IMAGE MASTER key

The client will ship with the master, system-image and signing keyrings on disk. Those will be updated as needed by the downloader. The upgrader will ship with just the master keyring.

The client pushes the system-image, signing and device (if present) keyrings 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. Even though the imaging signing keyring must be signed by the system image master key, the file itself cannot be signed by the system image master key or the archive master key.

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

Files

Keyrings

  • https://server/gpg/system-image.tar.xz is a GPG keyring tarball

  • https://server/gpg/system-image.tar.xz.asc is the signature for the system-image keyring. This is DIRECTLY signed by the MASTER key.

  • https://server/gpg/signing.tar.xz is a GPG keyring tarball

  • https://server/gpg/signing.tar.xz.asc is the signature for the system-image keyring. This is DIRECTLY signed by the SYSTEM IMAGE MASTER key.

  • https://server/<channel>/<device>/device.tar.xz is a GPG keyring tarball

  • https://server/<channel>/<device>/device.tar.xz.asc is the signature for the device keyring. This is DIRECTLY signed by the current SYSTEM IMAGE SIGNING key.

  • https://server/gpg/blacklist.tar.xz is a GPG keyring tarball

  • https://server/gpg/blacklist.tar.xz.asc is the signature for the blacklist keyring. This is DIRECTLY signed by the SYSTEM IMAGE MASTER key.

Other files

  • https://server/channels.json is ALWAYS DIRECTLY signed by the current SYSTEM IMAGE SIGNING key.

  • https://server/<channel>/<device>/index.json is ALWAYS DIRECTLY signed by a key contained in the keyring linked from channels.json or if no keyring linked, by the current SYSTEM IMAGE SIGNING key.

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:

  • keyring.gpg - a standard GPG keyring
  • keyring.json - a JSON file with the following syntax
    • expiry is a UTC UNIX EPOCH at which the keyring should be considered invalid (optional, defaults to no-expiry)
    • type is one of "master", "system-image", "signing", "device" or "blacklist"
    • model is the name of the model this keyring applies to (optional, defaults to any model) 

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

Use cases

Standard update

  • The client has the MASTER key, the current SYSTEM IMAGE MASTER key and the current SYSTEM IMAGE SIGNING key in its keyring.

  • The client downloads the blacklist from https://server/gpg/blacklist.tar.xz (and .asc) and loads all the invalid fingerprints

  • The client attempts to grab https://server/channels.json, and validates its signature against the image signing key.

  • The client looks for the entry for the channel and device in use, if present it looks for and downloads a device keyring, and validates its signature against the image signing key.

  • The client then downloads and validates https://server/<channel>/<device>/index.json against the device keyring (if present) or the image signing keyring.

  • The update is then resolved, all files downloaded and validated against the device keyring (if present) or the signing keyring and copied to android:/cache/.
  • The client then exports system-image keyring as android:/cache/system-image.gpg
  • The client then exports signing keyring as android:/cache/signing.gpg
  • The client then exports the device keyring as android:/cache/device.gpg (if present)
  • The upgrader loads the blacklist keyring from the system partition (if possible)
  • Any key contained in the blacklist will be removed from the keyrings before any validation will be done.
  • {for every file}
    • The upgrader checks that the file is DIRECTLY signed by a key stored in either device.gpg (if present) or signing.gpg
    • If device.gpg is present, and the file is signed by a device key, the upgrader checks that the device key is DIRECTLY signed by a key stored in signing.gpg
    • The upgrader checks that the signing key is DIRECTLY signed by a key stored in system-image.gpg
    • The upgrader checks that the system-image key is DIRECTLY signed by the MASTER key which it has locally.
    • Once all checks pass, the file is unpacked and applied

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 SYSTEM IMAGE MASTER key
  3. Issue a new device key (or keys depending on vendor)
  4. Generate a new device keyring with the new key
  5. Sign the new device keyring with the SYSTEM IMAGE SIGNING key
  6. Get new signed versions of any index.json and tarball signed by the old key

effect on the downloader

  • On the next check, the downloader will download a refreshed blacklist keyring
  • The new device keyring will be downloaded with the next update
  • MITM attacks are prevented by the use of the https certificate so an old version of the keyring can't be pushed to the client. If for some reason https could be intercepted and the client somehow would never be able to grab the new blacklist keyring, then the expiry set on the keyring would make it invalid after a month.

effect on the upgrader

  • The upgrader will read the blacklist keyring from the system partition, so as soon as the donwloader runs once after revocation, the user won't be able to use something signed by the invalidated key.
  • If the system partition doesn't contain the revoked entry or the blacklist can't be read for some reason then a user can have their system update to something signed by a key from the device keyring (using sdcard based flash) until the keyring expires (a month).

compromised SYSTEM 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 SYSTEM IMAGE MASTER key
  3. Issue a new SYSTEM IMAGE SIGNING key
  4. Generate a new signing keyring with the new key
  5. Sign the new signing keyring with the SYSTEM IMAGE MASTER key
  6. Re-sign channels.json, all the index.json, all the device keyrings and any tarball signed by the old SYSTEM IMAGE SIGNING key

effect on the downloader

  • On the next check, the download will download a refreshed blacklist keyring
  • Validation of channels.json will fail, causing a download of the signing keyring and its validation against the system-image keyring
  • MITM attacks are prevented by the use of the https certificate so an old version of the keyring can't be pushed to the client. If for some reason https could be intercepted and the client somehow would never be able to grab the new blacklist keyring, then the expiry set on the keyring and the key would make it invalid after two years.

effect on the upgrader

  • The upgrader will read the blacklist keyring from the system partition, so as soon as the donwloader runs once after revocation, the user won't be able to use something signed by the invalidated key.
  • If the system partition doesn't contain the revoked entry or the blacklist can't be read for some reason then a user can have their system update to something signed by a key from the signing keyring (using sdcard based flash) until the keyring expires (2 years). It's to be noted that even though the device keyring will expire after a month (if used for the particular device), a new one can be generated from the compromised signing key.

compromised SYSTEM IMAGE MASTER key

procedure

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

effect on the downloader

  • On the next check, the download will try to download a refreshed blacklist keyring
  • Validation of the blacklist keyring will fail, causing a download of the system-image keyring and its validation against the master keyring
  • Validation of the signing keyring will fail, causing a download of the signing keyring and its validation against the system-image keyring
  • The rest continues as normal
  • MITM attacks are prevented by the use of the https certificate so an old version of the keyring can't be pushed to the client. If for some reason https could be intercepted and the client somehow would never be able to grab the new blacklist keyring, then the attacker would be able to fake the update server as the system-image keyring doesn't expire.

effect on the upgrader

  • The upgrader will read the blacklist keyring from the system partition, so as soon as the donwloader runs once after revocation, the user won't be able to use something signed by the invalidated key.
  • If the system partition doesn't contain the revoked entry or the blacklist can't be read for some reason then a user could create a fake signing keyring and sign their images with that, the system-update keyring doesn't expire so there's nothing that'd make this stop after a while.

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.