From c3a9d7d025fd58453f6b1faef645495f45bcad70 Mon Sep 17 00:00:00 2001 From: Santiago Torres Date: Mon, 24 Mar 2014 13:37:48 -0400 Subject: [PATCH] Added first draft of the developer tools readme --- tuf/README-developer-tools.md | 123 ++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) create mode 100644 tuf/README-developer-tools.md diff --git a/tuf/README-developer-tools.md b/tuf/README-developer-tools.md new file mode 100644 index 00000000..e9b21481 --- /dev/null +++ b/tuf/README-developer-tools.md @@ -0,0 +1,123 @@ +# Developing for a TUF repository # + +## Table of Contents ## +- [Overview](#overview) +- [Creating a simple project](#creating_a_simple_project) + - [Generating a key](#generating_a_key) + - [The Project class](#the_project_class) + - [Signing and writing metadata](#signing_and_writing_metadata) +- [Loading an Existing project](#Loading_an_existing_project) +- [Managing keys](#managing_keys) +- [Managing targets](#managing_targets) +- [Delegations](#delegations) + - [Restricted paths](#restricted_paths) + - [Keys and thresholds](#keys_and_thresholds) + + +## Overview ## +The TUF developer tool is a Python library that enables developers to create +and maintain the required metadata for diles hosted in a TUF Repository. This +document has two parts. The first part walks through the creation of a +prototypal TUF project. The second part demonstrates the full capabilities of +the TUF developer tool, which can be userd to expand the project from the first +part to meet the developer''s needs. + + +## Creating a Simple project ## +### Generating a Key ### +First, uou will needd to generate a key to sign the metadata. Keys are generated +in pairs: one public and the other private. the private key is password-protected +and is used to sign metadata. The public key can be shared freely, andi s used +to verify signatures made by the private key. + +The generate_and_write_rsa_keypair function will create two key files in the +path (path/to/) and named "key.pub", which is the public key and "key" +which is the private key. + +``` +>>> from tuf.developer_tool import * + +>>> generate_and_write_rsa_keypair("path/to/key") +Enter a password for the RSA key: +Confirm: +>>> +``` + + +### The project class ### +TUF-dev is built around the Project class, which is used to organize groups of +targets associated with a single set of metadata. Each Project instance keeps +track of which target files ar associated with a single set of metadata. Each +Project instance keeps track of which target files are signed and which need +signing, which keys are used to sign metadata. It also keeps track of delegated +rolse, which are covered later. + +Before creating a project, you must know hwere it be located in the TUF +Repository. In the following example, we will create a project to be hosted as +"repo/example_project" within the repository, and store a local copy of the +metadata at "path/to/metadata". The project will comprise a single target file, +"local/path/to/example_project/target_1" locally, and we will secure it with +the key generated above. + +``` +>>> public_key = import_rsa_publickey_from_file("path/to/key.pub") + +>>> project = create_new_project(metadata_directory="local/path/to/metadata/", +... targets_directory="local/path/to/example_project", +... location_in_repository="repo/example_project", key=public_key) +>>> project.add_target("target_1") +``` + +At this point, the metadata is not valid. We have assigned a key to the project, +but we have not *signed* it with that key. + + +### Signing and writing the metadata ### +In order to signe the metadata, we need to impot the private key corresponding +to the public key we added to the project. One the key is loaded to the project, +it will automatically be used to sign the metadata whenever it is written. + +``` +>>> private_key = import_rsa_privatekey_from_file("path/to/key") +Enter password for the RSA key: +>>> project.load_signing_key(private_key) +>>> project.write() +``` + +When all changes to a project have been written, the Project instance can safely +be deleted. + + +To make changes to existing metadata, we will need the Project again. We can +restore it with the load_project() function. + +``` +>>> from tuf.developer_tool import * +>>> project = load_project("local/path/to/metadata") +>>> +``` +Each time the project is loaded anew, the necessary private keys must also be +loaded in order to sign metadata. + +``` +>>> private_key = import_rsa_privatekey_from_file("path/to/key") +Enter a password for the RSA key: + +>>> project.load_signing_key(private_key) + +>>> project.write() +``` + + +## Managing keys ## +When generating keys, it is possible to specity the length of the key in bits +and its password as parameters: + +``` +>>> generate_and_write_rsa_keypair("path/to/key",bits=2048, password="pw") +``` +The bits parameter defaults to 3072, and values below 2048 will raise an error. +The password parameter is only intended to be used in scripts. + + +