Bootstrap Process

After generating keys via POST /tuf/v1/bootstrap/generate, the next step is to initialize the TUF repository through the bootstrap process. The bootstrap.go file contains the logic for managing the bootstrap process, including status checking, locking, and asynchronous initialization.

API Endpoints for Bootstrap

All endpoints require:

Authentication (authMiddleware)
Administrator privileges (adminMiddleware)

GET `/tuf/v1/bootstrap` - Bootstrap Status

Method: GET
Path: /tuf/v1/bootstrap
Purpose: Checks the current bootstrap process status for the administrator

The function checks:

Existence of root metadata in the repository
Redis lock BOOTSTRAP_<adminName> to determine bootstrap status
Pre-locks (temporary locks during bootstrap execution)

Example Successful Response (bootstrap not performed)

{
  "data": {
    "bootstrap": false,
    "state": null,
    "id": "",
    "redis_locks": {
      "bootstrap_lock": "",
      "pre_locks": []
    }
  },
  "message": "System available for bootstrap."
}

Example Successful Response (bootstrap completed)

{
  "data": {
    "bootstrap": true,
    "state": null,
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "redis_locks": {
      "bootstrap_lock": "550e8400-e29b-41d4-a716-446655440000",
      "pre_locks": []
    }
  },
  "message": "Bootstrap already completed for this admin."
}

GET `/tuf/v1/bootstrap/locks` - Detailed Lock Information

Method: GET
Path: /tuf/v1/bootstrap/locks
Purpose: Returns detailed information about all bootstrap locks in Redis

The function returns information about:

BOOTSTRAP lock for the administrator
Pre-locks (temporary locks)
Bootstrap settings (settings stored in Redis)

Example Response

{
  "data": {
    "BOOTSTRAP": {
      "key": "BOOTSTRAP_admin1",
      "value": "550e8400-e29b-41d4-a716-446655440000",
      "exists": true
    },
    "pre_locks": [
      {
        "key": "pre-550e8400-e29b-41d4-a716-446655440000",
        "value": "550e8400-e29b-41d4-a716-446655440000",
        "exists": true
      }
    ],
    "settings": [
      {
        "key": "bootstrap:settings:550e8400-e29b-41d4-a716-446655440000",
        "value": "...",
        "exists": true
      }
    ]
  },
  "message": "Bootstrap locks status retrieved successfully"
}

POST `/tuf/v1/bootstrap` - Initialize Bootstrap

Method: POST
Path: /tuf/v1/bootstrap
Purpose: Initializes the TUF repository with the provided bootstrap payload

Workflow

The postBootstrap function performs the following steps:

Check for active bootstrap for the administrator
Validate payload from request body
Generate task_id (UUID)
Create pre-lock in Redis
Start bootstrap process in background (goroutine)
Return task_id to client

Request Body

{
  "settings": {
    "roles": {
      "root": {
        "expiration": 365
      },
      "timestamp": {
        "expiration": 1
      },
      "snapshot": {
        "expiration": 7
      },
      "targets": {
        "expiration": 365
      },
      "bins": {
        "expiration": 1,
        "number_of_delegated_bins": 4
      }
    }
  },
  "metadata": {
    "root": {
      "signatures": [...],
      "signed": {...}
    }
  },
  "timeout": 300
}

Successful Response (HTTP 202 Accepted)

{
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "last_update": "2024-01-15T10:30:00Z"
  },
  "message": "Bootstrap accepted and started in background"
}

Errors

409 Conflict - Bootstrap already in progress:

{
  "error": "Bootstrap already in progress for this admin",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "admin": "admin1",
    "status": "in_progress"
  }
}

409 Conflict - Bootstrap already completed:

{
  "error": "Bootstrap already completed for this admin",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000",
    "admin": "admin1",
    "status": "completed"
  }
}

404 Not Found - System already has metadata:

{
  "error": "System already has a Metadata. Bootstrap already completed."
}

400 Bad Request - Invalid payload format:

{
  "error": "Missing required field: settings.roles.root.expiration"
}

Redis Locks and Bootstrap States

Redis Key Structure

The system uses the following Redis keys to manage the bootstrap process:

BOOTSTRAP_<adminName> - Main lock for the administrator
- During execution: "pre-<task_id>"
- After completion: "<task_id>" (without "pre-" prefix)
pre-<task_id> - Temporary lock during bootstrap execution
- Deleted after process completion
- Value: "<task_id>"
bootstrap:settings:<task_id> - Bootstrap settings (if used)
ROOT_SIGNING_<adminName> - Root metadata signing state
- Cleared after bootstrap completion
Role settings (with _<adminName> suffix):
- ROOT_EXPIRATION_<adminName>
- ROOT_THRESHOLD_<adminName>
- ROOT_NUM_KEYS_<adminName>
- TARGETS_EXPIRATION_<adminName>
- TARGETS_THRESHOLD_<adminName>
- TARGETS_NUM_KEYS_<adminName>
- TARGETS_ONLINE_KEY_<adminName>
- SNAPSHOT_EXPIRATION_<adminName>
- SNAPSHOT_THRESHOLD_<adminName>
- SNAPSHOT_NUM_KEYS_<adminName>
- TIMESTAMP_EXPIRATION_<adminName>
- TIMESTAMP_THRESHOLD_<adminName>
- TIMESTAMP_NUM_KEYS_<adminName>
- BINS_EXPIRATION_<adminName> (if used)
- BINS_THRESHOLD_<adminName>
- BINS_NUM_KEYS_<adminName>
- NUMBER_OF_DELEGATED_BINS_<adminName>

Pre-Lock Mechanism

The pre-lock mechanism ensures:

Protection against parallel bootstrap for one administrator
State tracking of bootstrap execution
Automatic deletion of temporary locks after completion

Asynchronous Bootstrap Processing

Background Process

Bootstrap is executed asynchronously in a separate goroutine.

This means:

The client receives a result shortly after sending the request
The bootstrap process runs in the background
Status can be checked via GET /tuf/v1/bootstrap or GET /tuf/v1/bootstrap/locks

Main Bootstrap Function

The process includes:

Saving settings in Redis
Finalizing bootstrap (creating online roles, saving metadata)

Saving Settings

The saveSettings function saves all role settings in Redis with the _<adminName> suffix for isolation between administrators. Settings include:

Expiration periods for each role
Threshold values
Number of keys
Special settings (e.g., TARGETS_ONLINE_KEY, NUMBER_OF_DELEGATED_BINS)

Bootstrap Finalization

Finalization performs:

Creating online roles (targets, snapshot, timestamp) via BootstrapOnlineRoles
Deleting pre-lock key
Clearing ROOT_SIGNING state
Setting final BOOTSTRAP state (without "pre-" prefix)