citadel-tools/update-generator/README.md

Introduction

This code is used to produce the files needed to update citadel. The citadel-fetch command is installed in citadel and may be run manually to check for updates.

N.B. This update framework is at the moment not production ready. It defends against arbitrary installation and rollback attacks. It partially defends against endless data attacks. It does not defend against fast-forward or indefinite freeze attacks. This system is vulnerable to key compromise and does not provide a method to update the root key through the update mechanism. Further work needs to be done to prevent these issues. Consider using libraries from the Update Framework (TUF).

Usage

Within the citadel-tools directory, run cargo run --bin update_generator generate-keypair to generate a keypair. Replace the existing public key file by moving update_server_key.pub to citadel/meta-citadel/recipes-citadel/citadel-config/files/citadel-fetch/update_server_key.pub . The private key is available in the same directory as keypair.priv.

Run cargo run --bin update_generator create-signed-file -r 1.0.0 -k 6.5.3 -e 1.0.0 replacing the version numbers with yours and a version.cbor file will be generated. Alternatively, the create-signed-file can be run with no parameters in which case it will read the version number of the available images in build/images and generate a version.cbor automagically.

Finally, the files generated (version.cbor and images) must be uploaded/ Run cargo run --bin update_generator upload-to-server to automatically upload all the files to the server. To perform the upload manually, put this version.cbor file to the server at: {UPDATE_SERVER_NAME}/{CLIENT}/{CHANNEL}/. For example: https://update.subgraph.com/public/dev/ . Upload the image files to {UPDATE_SERVER_NAME}/{CLIENT}/{CHANNEL}/. For example: https://update.subgraph.com/public/dev/rootfs_1.0.0.img

More information is available in the update_generator help menu.

For debugging, testing and internal dev use, the config.toml file provides a way to change the path on the server where the files are saved by changing the CLIENT and CHANNEL.

Basic structure

We host the files used by this program as a file server. The current hostname is update.subgraph.com.

An installed citadel server will automatically check for updates by reading the file at https://update.subgraph.com/{CLIENT}/{CHANNEL}/version.cbor

{CLIENT} will default to "public" but is read from the currently running system.

{CHANNEL} will default to "prod" but is read from the currently running system.

The version.cbor file is signed with Subgraph-controlled keys or equivalent client-controlled keys. The corresponding public key will be embedded in the rootfs image during build. The public key is called update_server_key.pub and is stored in /etc/citadel/ .

Update File Structure

version.cbor file

The version.cbor file is the only file read during update and contains all information required for the user's system to decide to update or not as well as where the update files are located on the server. This file is merely a container which provides a cryptographic guarantee that the serialized_citadel_version struct (which contains the actual information we need to disseminate) is authentic.

1. serialized_citadel_version (CitadelVersionStruct): the serialized data containing the actionable information we need to read to make decisions on the update
2. signature: the ed25519 signature of the above serialized data
3. signatory: the name of the org or person who produced the version.cbor file

CitadelVersionStruct

1. client: the Subgraph client making the request
2. channel: whether this is a production release or other
3. component_version (Vec): a vector containing structures called ComponentVersion which contain the information on each component's version number and the location of the download file of the component
4. publisher: the name of the org or person who released this update

ComponentVersion

1. component: the name of the image we may update. Either the rootfs, the kernel or the extra image
2. version: a string which contains the semver describing the version of the component
3. file_path: where on the update server can the file be downloaded from. This is relative to the domain name we are currently fetching from