No subject

bundlers and packagers. The top-level Targets role delegates a separate role
for each bundle and each package.

The targets role hierarchy looks like this (with many more bundle and package
roles):

Root
`-- Targets
    |-- bundles/tor-browser-stable
    |-- bundles/tor-browser-beta
    `-- pkgs/openssl

Each bundle version and package version that bundlers and packagers released
has a separate bundleinfo and pkginfo file, respectively. These bundleinfo and
pkginfo files are opaque to the authentication layer: it considers them target
files like any other. However, the decision layer understands the contents of
these files and uses them to make subsequent download and installation
decisions (with the downloads always being done through the authentication
layer).

2.2. Repository Structure
-------------------------

Top-level metadata files are:

/meta/root.txt
/meta/release.txt
/meta/timestamp.txt
/meta/targets.txt
/meta/mirrors.txt

The /meta/targets.txt file would include a delegations section such as:

delegations : {
    keys : {
        'ABC...' : { details },
        '123...' : { details },
        ...
      },
    roles : {
        'bundles/tor-browser-stable' : {
            keys : ['ABC...', '123...'],
            threshold : 2,
            paths : ['bundles/tor-browser-stable/**'],
          },
        'pkgs/openssl' : {
            keys : ['DEF...', '456...'],
            threshold : 2,
            paths : ['pkgs/openssl/**'],
          },
        ...
      }
  }

The above would mean that the top-level Targets role had delegated a role
whose full name would be targets/bundles/tor-browser-stable (as it is
delegated by the targets role, the prepended targets/ is implicit in the
delegated role's name). This role for the tor-browser-stable bundle would be
trusted for the specified paths relative to the repository's targets/
directory. Thus, a specific version's bundleinfo file created by the bundler
could be placed on the repository at, for example:

  /targets/bundles/tor-browser-stable/win32/0.1/tor-browser-stable_win32_0.1.bundleinfo

(Note that this bundle role is trusted for all targets files matching the path
'bundles/tor-browser-stable/**' under the repository's targets/ directory, as
specified when this role was created through the above delegation.)

The bundle maintainer would sign a metadata file listing the hash and size of
this bundleinfo. This metadata would be placed on the repository at:

  /meta/targets/bundles/tor-browser-stable/win32/0.1/tor-browser-stable_win32_0.1.txt

(Note that the basename of these files isn't crucial to this aspect of the
design. They don't need to repeat the path info, though that's probably
helpful for humans.)

More generally, the metadata location is:

  /meta/ROLE_NAME/[ANY_PATH/]ANY_NAME.txt

Packages are similar to bundles with the difference that there are one or more
target files in addition to the pkginfo file. A package maintainer may supply
the following files to be placed on the repository:

  /targets/pkgs/openssl/win32/0.9.8m/openssl_win32_0.9.8m.pkginfo
  /targets/pkgs/openssl/win32/0.9.8m/libeay32.dll
  /targets/pkgs/openssl/win32/0.9.8m/ssleay32.dll

The hashes and sizes of these files are listed in metadata signed by the
targets/pkgs/openssl role (that is, the openssl package maintainer's role).
This metadata would be placed on the repository at:

  /meta/targets/pkgs/openssl/win32/0.9.8m/openssl_win32_0.9.8m.txt

2.3. Update Procedure
---------------------

The update procedure is:

  * The decision layer uses the authentication layer to retrieve a list of
    all available bundleinfo files.
    o Implementation: the decision layer asks the authentication layer
      for a list of all available metadata file paths/names. The
      authentication layer obtains this information from the release metadata.
  * Looking at the paths/names of available bundleinfo files, the decision
    layer identifies whether there is a newer version of a bundle it is
    interested in.
    o Implementation: the bundle names, OS, arch, and bundle version are
      all contained in paths of the available bundle metadata files.
  * The decision layer notices a bundle version in the list that it wants
    and uses the authentication layer to retrieve the bundleinfo file for that
    version.
  * The decision layer reads the contents of the bundleinfo file which
    indicate the necessary package versions and any other info the decision
    layer needs.
  * The decision layer uses the authentication layer to retrieve the pkginfo
    files for each of the package versions that it wants.
  * The decision layer understands the contents of the pkginfo files. These
    files indicate the individual files that are part of this version of the
    package.
  * The decision layer uses the authentication layer to retrieve the
    individual files (e.g. /targets/pkgs/openssl/win32/0.9.8m/libeay32.dll)
    that are needed.
  * The decision layer hands off the relevant installation instructions
    (from the bundleinfo and pkginfo files) and individual package files to
    the code that performs the installation/upgrade.

2.4.bundleinfo and pkginfo
--------------------------

As the contents of the bundleinfo and pkginfo are opaque to the authentication
layer, essentially there are two completely separate sets of metadata in this
design. It would make sense to have them use the same format (e.g. Canonical
JSON) and be parsed/generated by the same code.

The bundleinfo and pkginfo files would contain largely the same information as
these files do in the current Thandy spec (though they wouldn't be directly
signed but rather would be described in signed authentication-layer metadata).

There are a few reasons it is good to have the bundleinfo/pkginfo be opaque to
the authentication layer. One reason is that changes to bundleinfo/pkginfo
fields can be tested independently of the authentication layer. Also,
non-backwards-compatible changes could be made by introducing a new file name
such as bundleinfo.v2 which would be effectively invisible to legacy clients.

2.5. Differences with TUF
-------------------------

The authentication layer's metadata and roles are very similar to the current
TUF specification. However, there are a few differences.

TUF currently does not allow a single role to directly delegate multiple roles
deep. In TUF, one would need the following role structure:

Root
`-- Targets
    |-- bundles
    |   `-- tor-browser-stable
    `-- pkgs
        `-- openssl

That is, the Targets role would have to first delegate a bundles role which
then delegates a tor-browser-stable role.

Relatedly, TUF gives each delegated role the ability to sign a single metadata
file whose name is exactly the role's name. This may be non-ideal for Thandy
because bundlers and packagers would need to keep a continuously growing
metadata file that lists all of the versions that they want to be available to
clients or, alternatively, delegate subroles for each version in order to use
separate metadata files for each. (Note that this is talking about the
authentication layer's metadata, not bundleinfo and pkginfo files.)

In contrast, with this proposal, a bundler/packager would sign a metadata file
that lists only the new target files they are adding to the repository.---This
isn't a case where there's one correct way to do things, but my understanding
is that Thandy would like old versions to remain available within their
expiration times and would like bundlers/packagers to not have to deal with
issues such as accidentally removing an old version they didn't mean to remove
when generating and signing metadata to make a new version available.

[end of proposal]