### TUF Repository Setup

Source: https://github.com/theupdateframework/taps/blob/master/POUFs/reference-POUF/pouf1.md

Repository setup involves initializing online keys, databases for keys and roles, and preloading the client with initial root metadata and repository location.

```APIDOC
Repository Setup:

  1. Initialize the repository with online keys.
  2. Initialize databases for keys and roles:
     - Role database: Stores keys, threshold, paths, and delegations.
     - Key database: Stores signature scheme, keyid, and key value.
  3. Preload client with initial root metadata and repository location.
```

--------------------------------

### TUF Test Case Description Example

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Provides an example of a test case description, illustrating how to specify the purpose of a test, particularly in relation to defending against metadata replay attacks.

```python
Test defense against metadata replay attacks: provide a snapshot role that
has a lower version than that already trusted by the client.
```

--------------------------------

### TUF Example: Trusting a Mirror for Snapshot and Targets

Source: https://github.com/theupdateframework/taps/blob/master/tap5.md

Shows an example where TUF clients download snapshot and targets metadata from a mirror, while root and timestamp metadata are downloaded from PyPI. This is achieved by specifying different URLs for each role.

```Javascript
{
  "signed": {
    "roles": {
      "root": {
        "keyids": [...],
        "URLs": ["https://pypi.python.org/metadata/root.json"],
        ...
      },
      "timestamp": {
        "keyids": [...],
        "URLs": ["https://pypi.python.org/metadata/timestamp.json"],
        ...
      },
      "snapshot": {
        "keyids": [...],
        "URLs": ["http://example.com/metadata/snapshot.json"],
        ...
      },
      "targets": {
        "keyids": [...],
        "URLs": ["http://example.com/metadata/targets.json"],
        ...
      },
      ...
    },
    ...
  },
  ...
}
```

--------------------------------

### Example TUF Test Cases

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Provides concrete examples of test case definitions in JSON format, illustrating various scenarios such as basic positive cases, version conflicts, hash mismatches, and delegation issues.

```javascript
[
{
  'description':     '0: Basic positive case, valid test data',
  'expected_result': 'success',
  'initial_data':    'test_sets/test0/initial/',
  'repository_data': 'test_sets/test0/repository/',
  'target':          'target.txt'
},
{
  'description':
     '1: replay: snapshot w/ lower version than that already trusted by client',
  'expected_result': 'failure',
  'initial_data':    'test_sets/test1/initial/',
  'repository_data': 'test_sets/test1/repository/',
  'target':          'target.txt'
},
{
  'description':
     '2: target file provided does not match hash in trustworthy metadata',
  'expected_result': 'failure',
  'initial_data':    'test_sets/test2/initial/',
  'repository_data': 'test_sets/test2/repository/',
  'target':          'target.txt'
},
{
  'description':
     '3: delegated role is signed by key no longer trusted by delegating role'
  'expected_result': 'failure',
  'initial_data':    'test_sets/test3/initial/',
  'repository_data': 'test_sets/test3/repository/',
  'target':          'target_123.txt'
},
{
  'description':     '4: Positive w/ delegations (also controls for Test 3)',
  'expected_result': 'success',
  'initial_data':    'test_sets/test3c/initial/',
  'repository_data': 'test_sets/test3c/repository/',
  'target':          'target_123.txt'
}
]
```

--------------------------------

### TAP 4 map.json Example

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

An example of a map.json file used in TAP 4 to define repository mappings and path-to-repository relationships. This file helps clients identify known repositories and their trust relationships.

```Javascript
{
  "repositories": {
    "Repository1": [<test_case_0/repo1>],
    "Repository2": [<test_case_0/repo2>],
    "Repository3": ...,
  },
  "mapping": [
    {
      "paths":        ["project123/*"],
      "repositories": ["Repository1", "Repository2"],
      "terminating":  true,
    },
    {
      "paths":        ["*"],
      "repositories": ["Repository3"]
    }
  ]
}
```

--------------------------------

### Delegation with Succinct Roles Example

Source: https://github.com/theupdateframework/taps/blob/master/tap15.md

An example of a delegation object that utilizes the 'succinct_roles' field, specifying key IDs, threshold, bit length, and a name prefix for hashed bin delegations.

```json
{
    "delegations": {
        "keys": {
            "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a": {...}
        },
        "succinct_roles": {
            "keyids": [
                "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a"
            ],
            "threshold": 1,
            "bit_length": 11,
            "name_prefix": "alice.hbd",
        },
    }
}
```

--------------------------------

### Root File Example with Signature Method

Source: https://github.com/theupdateframework/taps/blob/master/tap9.md

A sample Root file demonstrating the 'signatures' section containing 'keyid' and 'method', and the 'signed' section with 'keys' and their types. It highlights the potential issue where the 'method' field might be unprotected.

```python
{
  "signatures": [{
    "keyid": "8c7e2de8e96047a9d473e29c0d35daf5ec79b51addf62...<snip>",
    "method": "rsassa-pss",
    "sig": "oAsb1STplQf...<snip>...j2XsDvevw=="
  }],
  "signed": {
    "keys": {
      "20b1b4c6fd067c1b87c67b80890...<snip>...": {
        "keytype": "RSA",
        "keyval": { "public": "-----BEGIN PUBLIC...<snip>...\n" }
      },
      ...
    },
    ...
}
```

--------------------------------

### Hashed Bin Delegations Example

Source: https://github.com/theupdateframework/taps/blob/master/tap15.md

Example of delegating metadata with hashed bin delegations, highlighting the repetitive information that can be made more succinct. This structure is used in TUF for managing target files efficiently.

```json
{
    "delegations": {
        "keys": {
            "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a": {}
        },
        "roles": [
            {
                "name": "alice.hbd-000",
                "keyids": [
                    "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a"
                ],
                "threshold": 1,
                "path_hash_prefixes": ["000", "001"],
                "terminating": false
            },
            {
                "name": "alice.hbd-001",
                "keyids": [
                    "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a"
                ],
                "threshold": 1,
                "path_hash_prefixes": ["002", "003"],
                "terminating": false
            },
            {
                "name": "alice.hbd-7ff",
                "keyids": [
                    "943efed2eea155f383dfe5ccad12902787b2c7c8d9aef9664ebf9f7202972f7a"
                ],
                "threshold": 1,
                "path_hash_prefixes": ["ffe", "fff"],
                "terminating": false
            }
        ]
    }
}
```

--------------------------------

### TUF Metadata Structure Example

Source: https://github.com/theupdateframework/taps/blob/master/tap9.md

Illustrates a portion of a TUF Root file, detailing the 'signatures', 'signed', 'keys', and 'roles' sections. This structure defines the keys and their associated roles within the framework.

```python
{
  "signatures": [
    ...
  ],
  "signed": {
    ...
    "keys": {
      "0bde74244f238cd6d4e3839d35a5b248d6cde5759b760ebdbee45a386109a41a": {
        "keytype": "rsa",
        "keyval": {
            "public": "-----BEGIN PUBLIC KEY-----<etc>"
        }
      },
      ...
    },
    "roles": {
      "targets": {
        "keyids": [
          "0bde74244f238cd6d4e3839d35a5b248d6cde5759b760ebdbee45a386109a41a"
        ],
        "threshold": 1
      },
      ...
    }
  }
}
```

--------------------------------

### TUF Map File Example

Source: https://github.com/theupdateframework/taps/blob/master/tap4.md

An example of a `map.json` file used by The Update Framework (TUF) to define repository mappings for target files. It specifies repositories, their URLs, and a priority-ordered list of mappings based on target paths, repository assignments, signing thresholds, and termination rules.

```javascript
{
  // For each repository, its key name is the directory where files, including
  // the root metadata file, are cached, and its value is a list of URLs where
  // files may be downloaded.
  "repositories": {
    "Django": ["https://djangoproject.com/"],
    "PyPI":   ["https://pypi.python.org/"]
  },
  // For each set of targets, specify a list of repositories where files may be
  // downloaded.
  "mapping": [
    {
      // Much like target delegation, the order of these entries indicates
      // the priority of the delegation.  The entries listed first will be
      // considered first.

      // Map the targets "/django/django-1.*.tgz" to both Django and PyPI.
      "paths":        ["/django/django-1.*.tgz"],
      "repositories": ["Django", "PyPI"],

      // At least one repository must sign for the same length and hashes
      // of the "/django/django-1.*.tgz" targets.
      "threshold": 1

      // In this case, the "terminating" attribute is set to false.
      "terminating":  false,
      // Therefore, if this mapping has not signed for "/django/django-1.*.tgz"
      // targets, the following mapping will be consulted.

    },
      ...
    {
      // Map all other targets only to PyPI.
      "paths":        ["*"],
      "repositories": ["PyPI"],
      "terminating": true
      "threshold": 1
    }
  ]
}
```

--------------------------------

### Example Target File Patterns

Source: https://github.com/theupdateframework/taps/blob/master/tap4.md

Illustrates common patterns for specifying target files, including versioned archives and wildcard matching, as used in TUF repository assignments.

```django
django-2.0.1.tgz
```

```glob
django*
```

```glob
*.tar.gz
```

--------------------------------

### Metadata Structure Example

Source: https://github.com/theupdateframework/taps/blob/master/tap9.md

Illustrates the typical structure of TUF metadata, including the 'signatures' and 'signed' sections. The 'signatures' section contains signature details like 'keyid', 'method', and 'sig'.

```python
{
  "signatures": [
     {
       "keyid": "588f02cf6907c3f199b201e845f5a458285e9ae956680e0e2fdcc7987306ef7c",
       "method": "rsassa-pss",
       "sig": "fce1a97b55076065c7dc7c78fb0206d5dd87db817ccc7bcf83c3cdf..."
     }
  ],
  "signed": {
    ...
  }
}
```

--------------------------------

### Python Rotation to Null Example

Source: https://github.com/theupdateframework/taps/blob/master/tap20.md

An example of a Python dictionary representing a rotation file that points to a null key. This structure is used by clients to detect role revocations.

```python
{
    "_type" : "rotate",
    "version" : 2,
    "role" : "foo",
    "keys" : {
        NULL
        },
    "threshold" : 1
}
```

--------------------------------

### TUF Specification Client Workflow

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

References the TUF Specification's Client Workflow section, which the client updater implementation should adhere to. This guides the testing process to ensure the updater correctly handles metadata and targets.

```APIDOC
Client Workflow in Section 5 of the TUF Specification
(https://theupdateframework.github.io/specification/latest/#detailed-client-workflow)
```

--------------------------------

### Signature Header Example with Same KeyID for Different Keys

Source: https://github.com/theupdateframework/taps/blob/master/tap12.md

Demonstrates a signature header where the same keyID (K) is used in multiple delegations to a metadata file (C), but each delegation uses a different key (D and E). This scenario shows how TUF clients must track keys used during verification to ensure a threshold of unique keys has signed the metadata.

```json
{
    "sigs": [
      {
        "keyid": "K",
        "sig": "abcd..."
      },
      {
        "keyid": "K",
        "sig": "efgh..."
      },
      ...
    ],
    ...
  }
```

--------------------------------

### Signature Header Example with Unique KeyIDs

Source: https://github.com/theupdateframework/taps/blob/master/tap12.md

Illustrates the structure of a signature header in a metadata file (C) when two different metadata files (A and B) delegate to it using the same key (D) but with different keyIDs (K and L). This highlights how TUF handles distinct key identifiers for the same underlying key in different delegation contexts.

```json
{
    "sigs": [
      {
        "keyid": "K",
        "sig": "abcd..."
      },
      {
        "keyid": "L",
        "sig": "abcd..."
      },
      ...
    ],
    ...
  }
```

--------------------------------

### TUF Example: Restricting Trust to Django on PyPI

Source: https://github.com/theupdateframework/taps/blob/master/tap5.md

Demonstrates how to configure TUF to trust PyPI only for the Django project's metadata. This involves setting specific URLs and keys for the 'root' and 'targets' roles, while using PyPI for 'timestamp' and 'snapshot'.

```Javascript
{
  "signed": {
    "roles": {
      "root": {
        "keyids": [...],
        "URLs": ["http://example.com/metadata/root.json"],
        ...
      },
      "timestamp": {...},
      "snapshot": {...},
      "targets": {
        "URLs": ["https://pypi.python.org/metadata/delegations/Django.json"],
        "keyids": [...],
        ...
      },
      ...
    },
    ...
  },
  ...
}
```

--------------------------------

### TUF Targets Metadata with Role Signing Requirements

Source: https://github.com/theupdateframework/taps/blob/master/tap3.md

This JSON structure defines targets metadata for The Update Framework (TUF). It showcases how to configure signing requirements, including the number of roles needed for agreement ('min_roles_in_agreement') and individual role signing thresholds ('threshold'). This example illustrates scenarios where one or multiple roles must sign targets.

```json
{
  "signed": {
    "keys_for_delegations": {
      "ca9781...<snip>": {"keytype": "ed25519", "keyval": KEYVAL},
      "acac86...<snip>": {},
      "de7d1b...<snip>": {},
      "1a2b41...<snip>": {},
      "93ec2c...<snip>": {},
      "f2d502...<snip>": {},
      "fce9cf...<snip>": {},
      "498aeb...<snip>": {}
    },
    "delegations": [
      {
        "name": "first_delegation",
        "paths": ["/foo/*.pkg"],
        "terminating": false,
        "min_roles_in_agreement": 1,
        "roleinfo": [
          {
            "rolename": "alice",
            "keyids": [
              "ca978112ca1bbdcafac231b39a23dc4da786eff8147c4e72b9807785afee48bb",
              "acac86c0e609ca906f632b0e2dacccb2b77d22b0621f20ebece1a4835b93f6f0",
              "de7d1b721a1e0632b7cf04edf5032c8ecffa9f9a08492152b926f1a5a7e765d7"
            ],
            "threshold": 3
          }
        ]
      },
      {
        "name": "second_delegation",
        "paths": ["/baz/*.pkg"],
        "terminating": true,
        "min_roles_in_agreement": 2,
        "roleinfo": [
          {
            "rolename": "release-engineering",
            "keyids": [
              "1a2b4110927d4cba257262f614896179ff85ca1f1353a41b5224ac474ca71cb4"
            ],
            "threshold": 1
          },
          {
            "rolename": "quality-assurance",
            "keyids": [
              "93ec2c3dec7cc08922179320ccd8c346234bf7f21705268b93e990d5273a2a3b",
              "f2d5020d08aea06a0a9192eb6a4f549e17032ebefa1aa9ac167c1e3e727930d6",
              "fce9cf1cc86b0945d6a042f334026f31ed8e4ee1510218f198e8d3f191d15309"
            ],
            "threshold": 2
          },
          {
            "rolename": "continuous-integration",
            "keyids": [
              "498aeb78523452123dce43434fff346678768676867bae345353453455432544"
            ],
            "threshold": 1
          }
        ]
      }
    ]
  }
}
```

--------------------------------

### Create TAF Repository

Source: https://github.com/theupdateframework/taps/blob/master/POUFs/TAF-POUF/pouf2.md

Demonstrates the command-line interface command to create a new TAF authentication repository. This is a foundational step for using the system.

```python
taf repo create repo_path
```

--------------------------------

### Sigstore Signing Process Overview

Source: https://github.com/theupdateframework/taps/blob/master/tap18.md

Outlines the essential steps required to sign metadata using Fulcio, involving OIDC token acquisition, key pair generation, CSR creation, Fulcio certificate request, private key signing, and bundle creation with Rekor timestamping.

```APIDOC
Signing Process with Fulcio:
1. Initiate OIDC session to obtain an identity token.
2. Generate a local key pair.
3. Create a Certificate Signing Request (CSR) with identity token subject.
4. Request a short-lived certificate from Fulcio using CSR and identity token.
   - Fulcio uploads the certificate to a Certificate Transparency log.
5. Use the generated private key to sign targets metadata.
6. Upload the certificate, signature, and metadata hash to Rekor for timestamping (SET).
7. Create a bundle containing the signature, Fulcio certificate, and SET.

Note: These steps are typically automated by Sigstore tooling.
```

--------------------------------

### TAP 4 Directory Structure - Initial Trusted Metadata

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Illustrates the directory structure for Initial Trusted Metadata when TAP 4 is supported. It shows the inclusion of map.json, keys.json, and repository-specific directories containing metadata.

```APIDOC
- map.json // See section above on map.json
- keys.json
- <repository_1_name>
            |- metadata
                  |- root.json
                  ...
- <repository_2_name>
            |- metadata
                  |- root.json
                  ...
...
```

--------------------------------

### Git Tampered Commit Object Detection

Source: https://github.com/theupdateframework/taps/blob/master/tap19.md

Illustrates the consequence of modifying a Git commit object without updating its hash. The example shows how Git detects this discrepancy when the object is accessed, leading to errors like 'hash mismatch' and 'bad object'.

```bash
$ ls -l .git/object/65
-rw-r--r-- 1 saky users 143 Jun  6 19:20 774be295aaf5ac9412ebe81584138643ebded2
-r--r--r-- 1 saky users 532 Jun  6 19:15 774be295aaf5ac9412ebe81584138643ebded2.valid
$ cat .git/object/65/774be295aaf5ac9412ebe81584138643ebded2 | zlib-flate -uncompress
commit 222tree b4d01e9b0c4a9356736dfddf8830ba9a54f5271c
author Aditya Sirish <aditya@saky.in> 1654557334 -0400
committer Aditya Sirish <aditya@saky.in> 1654557334 -0400

Initial commit

Signed-off-by: Aditya Sirish <aditya@saky.in>
$ cat .git/object/65/774be295aaf5ac9412ebe81584138643ebded2 | zlib-flate -uncompress | sha1sum
2c65b30ada8c10d9ec028359ca82d7a410067ed4  -  # this does not match the commit ID
$ git show
error: hash mismatch 65774be295aaf5ac9412ebe81584138643ebded2
fatal: bad object HEAD

```

--------------------------------

### TUF Root File Format (Before TAP 9)

Source: https://github.com/theupdateframework/taps/blob/master/tap9.md

Illustrates the structure of a TUF Root file before the implementation of TAP 9, showing the inclusion of the 'method' field within signatures.

```python
{
  "signatures": [
    {
      "keyid": "ed3c845525d34937bf0584989a76fa300c0a6072de714b11b8dca535e10b9088",
      "method": "rsassa-pss-sha256",
      "sig": "3a0e4666ffbdb5d80001d1539c6a4c27821c3d69065b17ed02a099591b0b4..."
    },
  ],
  "signed": {
    ...
    "keys": {
      "ed3c845525d34937bf0584989a76fa300c0a6072de714b11b8dca535e10b9088": {
        "keytype": "rsa",
        "keyval": {
          "public": "-----BEGIN PUBLIC KEY----- <etc>"
       }
    }
  }
}
```

--------------------------------

### TUF Client File Download Procedure

Source: https://github.com/theupdateframework/taps/blob/master/tap5.md

Describes the six-step process a TUF client follows to download metadata and target files from a repository. This includes loading and verifying the root metadata, updating timestamp, snapshot, and top-level targets metadata, and finally downloading delegated targets and actual target files.

```APIDOC
TUF Client File Download Steps:

1. Load Root Metadata:
   - Load the latest downloaded root metadata file.
   - Verify signature threshold and expiration.
   - If invalid, abort or attempt to update root metadata.

2. Update Timestamp Metadata:
   - Use similar steps as root metadata update.

3. Update Snapshot Metadata:
   - Use similar steps as root metadata update.

4. Update Top-Level Targets Metadata:
   - Use similar steps as root metadata update.
   - Handle cases where repository URLs (R) are provided for roles, influencing snapshot lookups.

5. Update Delegated Targets Metadata:
   - Use only repository URLs (M) for downloading.
   - Download in order from M until found or report missing.

6. Download Target Files:
   - Use a process similar to step 5 to download target files.
```

--------------------------------

### TUF Repository Directory Structure

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Illustrates the expected directory layout for TUF repository data, including the `keys.json` file, the `metadata` directory containing signed metadata files, and the `targets` directory containing the actual target files.

```text
- keys.json
- metadata
      |- root.json
      |- timestamp.json
      |- snapshot.json
      |- targets.json
      |- <a delegated role>.json
      |- <another delegated role>.json
      |   ...
- targets
      |- <some_target.img>
      |-  ...
```

--------------------------------

### Sigstore Bundle Structure (Protobuf)

Source: https://github.com/theupdateframework/taps/blob/master/tap18.md

Describes the structure of the Sigstore bundle, which contains verification information such as transparency log references (SET), the Fulcio X.509 signing certificate, and a signature over targets metadata.

```APIDOC
Sigstore Bundle Structure:
  Contains verification information including:
  - Transparency log references (e.g., Signed Email Timestamp - SET from Rekor)
  - Fulcio X.509 signing certificate
  - Signature over targets metadata
  - Reference to the Sigstore [protobuf-specs](https://github.com/sigstore/protobuf-specs/blob/main/protos/sigstore_bundle.proto)
```

--------------------------------

### Targets Metadata File Format

Source: https://github.com/theupdateframework/taps/blob/master/tap3.md

Defines the structure of the targets metadata file, including keys for delegations, delegation details, role information, and path patterns. This format allows specifying multiple role names required for signing.

```json
{
  "signed": {
    "keys_for_delegations": {KEYID: {"keytype: KEYTYPE, "keyval": KEYVAL}, ...},
    "delegations": [
        {
          "name": DELEGATION-NAME,
          "paths": [PATHPATTERN-1, PATHPATTERN-2, ...],
          "terminating": BOOLEAN,
          "min_roles_in_agreement": NUM_ROLES,
          "roleinfo": [
            {
              "rolename": ROLENAME,
              "keyids": [KEYID],
              "threshold": THRESHOLD,
            }
          ]
        },
        // Multiple delegations can be specified here after the first one.
        ...
    ]
  }
}
```

--------------------------------

### TAP 4 keys.json Structure

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Illustrates the hierarchical structure of keys.json under TAP 4, showing how keys are organized by repository name and role. This format separates signing keys for different repositories and roles within the TUF metadata.

```javascript
{
  <repository_1_name>: {
    <rolename_1>: [
      {'keytype': <type, e.g. 'ed25519'>,
       'keyid': <id string>,
       'keyval': {'public': <key string>, 'private': <key string>}
      },
      {'keytype': <type, e.g. 'ed25519'>,
       'keyid': <id string>,
       'keyval': {'public': <key string>, 'private': <key string>}
      }
    ],
    <rolename_2>: [...]},

  <repository_2_name>: {...}
}
```

```javascript
{
  'imagerepo': {
    'root': [{
      'keytype': 'ed25519',
      'keyid': '94c836f0c45168f0a437eef0e487b910f58db4d462ae457b5730a4487130f290',
      'keyval': {
        'public': 'f4ac8d95cfdf65a4ccaee072ba5a48e8ad6a0c30be6ffd525aec6bc078211033',
        'private': '879d244c6720361cf1f038a84082b08ac9cd586c32c1c9c6153f6db61b474957'
      }
    }],
    'timestamp': [{
      'keytype': 'ed25519',
      'keyid': '6fcd9a928358ad8ca7e946325f57ec71d50cb5977a8d02c5ab0de6765fef040a',
      'keyval': {
        'public': '97c1112bbd9047b1fdb50dd638bfed6d0639e0dff2c1443f5593fea40e30f654',
        'private': 'ef373ea36a633a0044bbca19a298a4100e7f353461d7fe546e0ec299ac1b659e'
      }
    }],
    'delegated_role1': [{
      'keytype': 'ed25519',
      'keyid': '8650aed05799a74f5febc9070c5d3e58d62797662d48062614b1ce0a643ee368',
      'keyval': {
        'public': 'c5a78db3f3ba96462525664e502f2e7893b81e7e270d75ffb9a6bb95b56857ca',
        'private': '134dc07435cd0d5a371d51ee938899c594c578dd0a3ab048aa70de5dd71f99f2'
      }
    }]
  },
  'director': {
    'root': [
      ...
    ]
  }
}
```

--------------------------------

### TUF Initial Trusted Metadata Structure

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Details the expected directory structure for initial trusted metadata used by a TUF client updater. This includes essential files like keys.json and root.json, and can extend to other metadata files for delegated roles.

```python
- keys.json
- metadata
        |- root.json
```

```python
- keys.json
- metadata
        |- root.json
        |- timestamp.json
        |- snapshot.json
        |- targets.json
        |- <a delegated role>.json
        |- <another delegated role>.json
        |   ...
```

--------------------------------

### Combined Roles and Succinct Roles Delegation Structure

Source: https://github.com/theupdateframework/taps/blob/master/tap15.md

Illustrates the structure of a delegation that can contain either 'roles' or 'succinct_roles', highlighting the mutual exclusivity and the potential for intermediate delegations.

```json
{
    "keys": {
        KEYID: KEY,
        ...
    },
   ("roles": [
        {
            "name": ROLENAME,
            "keyids": [KEYID, ...],
            "threshold": THRESHOLD,
           ("path_hash_prefixes": [HEX_DIGEST, ...], |
            "paths": [PATHPATTERN, ...],)
            "terminating": TERMINATING,
        },
        ...,
    ], |
    "succinct_roles": {
        "keyids": [KEYID, ...],
        "threshold": THRESHOLD,
        "bit_length": BIT_LENGTH,
        "name_prefix": NAME_PREFIX,
    },)
}
```

--------------------------------

### Rekor Online Verification Steps

Source: https://github.com/theupdateframework/taps/blob/master/tap18.md

Steps required for online verification using the Rekor transparency log. This involves obtaining and verifying signed tree heads and inclusion proofs against TUF metadata.

```APIDOC
Rekor Online Verification:
  1. Obtain Rekor signed tree head.
     - Query Rekor for consistency proof against current signed tree head.
     - Verify consistency proof.
     - Persist newest signed tree head.
  2. Query Rekor for inclusion proof against certificate and TUF metadata.
  3. Verify inclusion proof.
  4. Verify root hash consistency with signed tree head.
```

--------------------------------

### TAP 8: Motivation for Generalized Key Rotation

Source: https://github.com/theupdateframework/taps/blob/master/tap8.md

This section explains the motivation behind TAP 8, focusing on the benefits of a generalized key rotation mechanism for roles other than the root. It highlights the self-maintaining nature of project roles and the challenges with ephemeral keys.

```markdown
# Motivation

TUF supports key rotation for the root keys using an ad hoc method.
Several use cases can benefit from a generalized mechanism:


## Self-maintaining *project* role

It is common to have a single *project role* delegated from the targets
role so that the members of the project can change without the
delegations to the project being replaced.  The *project role*
represents a single point of failure / compromise.  (Some projects may
prefer a quorum of developers instead, but this requires
delegations to be redone whenever this quorum changed.) Adding and
removing delegations of a project often uses the project role's key which is
delegated to.  This project role gives persons with access to it elevated
privileges, and needs intervention from a higher level of delegations if
it needs to be rotated.

With TAP 8, the delegation can be assigned to a role (that contains a set
of keys and a threshold value).  Developers could then collectively sign
rotation metadata to change the set of keys and update the set of developers
as people enter or leave the project. If the project role had a single key,
this key could be rotated to ensure only the current developers have access.
In addition, this mechanism could be used to give each developer their own
key, and rotate these keys in and out without going through the delegator.


## Why root key rotation is not supported

TAP 8 provides a methodology for key rotations for roles other than root,
leaving the root rotation mechanism in place. The root metadata file contains
information, like the spec-version, that needs to be seen for each version of
the file. This means that even if the keys are not changed, a client must
download every version of the root metadata in order to ensure the client
spec-version is in line with the server spec-version.

## Use of ephemeral keys (TAP 18)

TAP 18 proposes the use of Sigstore's Fulcio to replace long-lived keys with
short-lived keys backed by OIDC identities. This use of identities
rather than keys simplifies key management for signers in TUF, but it presents an
issue when teams that manage a targets metadata file change over time. In
TUF today, if a team member leaves, they can pass on a key for use by another
team member until the delegating targets metadata is able to update the
delegation to a new team member. However, OIDC identities are generally tied
to email accounts and other personal data, and so cannot be shared even for
the short term. To address this, teams need a way to indicate that a different
OIDC identity should be used without waiting for interaction from the
delegating metadata.
```

--------------------------------

### go-tuf Pull Request for Fulcio Integration

Source: https://github.com/theupdateframework/taps/blob/master/tap18.md

References a pull request in the go-tuf repository that implements the Fulcio feature, indicating a practical integration of the discussed security concepts.

```APIDOC
go-tuf Pull Request #181:
  Adds Fulcio integration feature.
```

--------------------------------

### TUF Reference Implementation Operations

Source: https://github.com/theupdateframework/taps/blob/master/POUFs/reference-POUF/pouf1.md

The TUF reference implementation supports optional features like mirrors and consistent snapshots. Mirrors are managed via 'mirrors.json' map files, and consistent snapshots follow the TUF specification.

```APIDOC
Operations:

  Supports mirrors using map files named 'mirrors.json'.
  Implements consistent snapshots as described in the TUF specification.
  Includes optional features beyond the core specification.
```

--------------------------------

### Fetch IPFS README

Source: https://github.com/theupdateframework/taps/blob/master/tap19.md

Retrieves a README file from IPFS using its content identifier (CID). This is the initial step to access the file for demonstration.

```bash
ipfs get /ipfs/QmQPeNsJPyVWPFDVHb77w8G42Fvo15z4bG2X8D2GhfbSXc
```

--------------------------------

### TUF Root File Format (After TAP 9)

Source: https://github.com/theupdateframework/taps/blob/master/tap9.md

Demonstrates the updated structure of a TUF Root file after TAP 9, where the 'method' field is removed from signatures and the 'scheme' is included within the key definition.

```python
{
  "signatures": [
    {
    "keyid": "ed3c845525d34937bf0584989a76fa300c0a6072de714b11b8dca535e10b9088",
    "sig": "3a0e4666ffbdb5d80001d1539c6a4c27821c3d69065b17ed02a099591b0b4..."
    },
  ],
  "signed": {
    ...
    "keys": {
      "ed3c845525d34937bf0584989a76fa300c0a6072de714b11b8dca535e10b9088": {
        "keytype": "rsa",
        "scheme": "rsassa-pss-sha256",
        "keyval": {
          "public": "-----BEGIN PUBLIC KEY----- <etc>"
       }
    }
  }
}
```

--------------------------------

### TAF Client Update Process

Source: https://github.com/theupdateframework/taps/blob/master/POUFs/TAF-POUF/pouf2.md

Details the steps a client follows to download and validate repositories using TAF's updater, ensuring the integrity and authenticity of the distributed Git repositories.

```markdown
Client Update Steps:
1. Client downloads the authentication repository.
2. Authentication repository is cloned as a bare repository in the user's temp directory.
3. Repository validation occurs:
   - Metadata and target files are accessed using 'git show'.
4. If validation is successful:
   - The target repository is cloned or new changes are pulled using Git.
```

--------------------------------

### Transferring TAP Ownership Process

Source: https://github.com/theupdateframework/taps/blob/master/tap1.md

Details the process and considerations for transferring ownership of a TAP from one champion to another.

```APIDOC
Transferring TAP Ownership:

  Procedure:
    1. Send a request message to the original author and the TUF mailing list: https://groups.google.com/forum/?fromgroups#!forum/theupdateframework

  Considerations:
    - Prefer retaining the original author as a co-author.
    - Reasons for transfer: Lack of time/interest, unresponsiveness.
    - Avoid transfer due to disagreement on TAP direction; submit a competing TAP instead.
    - TUF team makes unilateral decisions if the original author is unresponsive.
```

--------------------------------

### targets.json and Delegated Roles Metadata Structure

Source: https://github.com/theupdateframework/taps/blob/master/POUFs/reference-POUF/pouf1.md

Describes the structure of targets.json and delegated target roles, including information about target files, their hashes, lengths, and optional custom data. It also covers the delegation mechanism for managing target access.

```APIDOC
targets.json:
  signed:
    _type: "targets"
    spec_version: SPEC_VERSION
    version: VERSION
    expires: EXPIRES
    targets: TARGETS
    delegations: DELEGATIONS (optional)

  TARGETS: Object mapping target paths to file metadata.
    TARGETPATH: Path to a target file relative to a mirror's base URL.
    LENGTH: Integer, size of the target file in bytes.
    HASHES: Dictionary of cryptographic hashes (e.g., {"sha256": HASH}).
    custom: Optional dictionary for application-specific data.

  DELEGATIONS:
    keys: { KEYID: KEY, ... }
    roles: [
      {
        name: ROLENAME,
        keyids: [ KEYID, ... ],
        threshold: THRESHOLD,
        path_hash_prefixes: [ HEX_DIGEST, ... ] | paths: [ PATHPATTERN, ... ],
        terminating: TERMINATING
      }, ...
    ]

  ROLENAME: Name of the delegated role.
  TERMINATING: Boolean indicating if subsequent delegations should be considered.
```

--------------------------------

### TUF TAP Metadata Structure

Source: https://github.com/theupdateframework/taps/blob/master/tap2.md

Defines the key metadata fields required at the beginning of each TUF TAP document. This includes TAP number, title, version, author, status, and dependencies.

```APIDOC
TAP: <TAP number>
Title: <TAP title>
Version: <version string>
Last-Modified: <date string>
Author: <list of authors' real names and optionally, email addrs>
Type: <Standardization | Informational>
Status: <Draft | Active | Accepted | Deferred | Rejected | Withdrawn | Final | Superseded>
+Content-Type: <text/markdown>
+Requires: <TAP numbers>
Created: <date created on, in dd-mmm-yyyy format>
+TUF-Version: <version number>
+Post-History: <dates of postings to the TUF mailing list>
+Replaces: <TAP number>
+Superseded-By: <TAP number>
```

--------------------------------

### Previous Targets Metadata File Format (Single Role Delegation)

Source: https://github.com/theupdateframework/taps/blob/master/tap3.md

Illustrates the prior TUF specification for targets metadata, where each delegation could only specify a single role required to sign the targets. This format lacked the ability to enforce combined signatures from multiple roles within a single delegation.

```json
{
  "signed": {
    "delegations": {
      "roles": [
        // This is the first delegation to a <b>single</b> role.
        {
          // We specify the name, keyids, and threshold of a single role as
          // required to sign the following targets.
          <b>"name"</b>: <b>ROLENAME-1</b>,
          "keyids": [KEYID-1],
          "threshold": THRESHOLD-1,
          "paths": ["/foo/*.pkg"],
          "terminating": false,
        },
        // This is the second delegation to a <b>single</b> role.
        // Note that this delegation is separate from the first one.
        // The first delegation may override this delegation.
        {
          <b>"name"</b>: <b>ROLENAME-2</b>,
          "keyids": [KEYID-2],
          "threshold": THRESHOLD-2,
          "paths": ["/foo/bar.pkg"],
          "terminating": false,
        }
        // Note that, unfortunately, there is no way to require <b>multiple</b>
        // roles to sign targets in a single delegation.
      ],
      ...
    },
    ...
}

```

--------------------------------

### Snapshot Merkle Tree Diagram

Source: https://github.com/theupdateframework/taps/blob/master/tap16.md

Illustrates the structure and flow of a snapshot Merkle tree within the TUF system, showing how targets metadata files are incorporated into the tree and verified against the root.

```markdown
![Diagram of snapshot Merkle tree](merkletap-1.jpg)
```

--------------------------------

### TAP 4 Directory Structure - Repository Data

Source: https://github.com/theupdateframework/taps/blob/master/tap7.md

Depicts the directory structure for Repository Data when TAP 4 is supported. It includes repository-specific directories containing both metadata and targets.

```APIDOC
- keys.json
- <repository_1_name>
            |- metadata
                  |- root.json
                  |- timestamp.json
                  |- snapshot.json
                  |- targets.json
                  |- <a delegated role>.json
                  |- <another delegated role>.json
                  |   ...
            |- targets
                  |- <some_target.img>
                  |-  ...
- <repository_2_name>
            |- metadata
                  |- root.json
                  |- ...
            |- targets
                  |- ...
...
```