tuf: Support importing root keys from a fioctl tarball

cmd/server/tuf_init.go

@@ -4,15 +4,171 @@
 package main
 
 import (
+	"archive/tar"
+	"compress/gzip"
+	"encoding/json"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
 	"github.com/foundriesio/update-server/storage"
+	"github.com/foundriesio/update-server/storage/tuf"
 )
 
-type TufInitCmd struct{}
+// rootJsonSuffix is the suffix ota-tuf uses for root metadata files (e.g.
+// "1.root.json").
+const rootJsonSuffix = ".root.json"
+
+// tufKeyFileSuffix is the suffix fioctl/garage-sign use for private key files
+// stored in the offline keys tarball.
+const tufKeyFileSuffix = ".sec"
+
+type TufInitCmd struct {
+	ImportKeys  string `arg:"--import-keys" help:"Path to a fioctl offline keys tarball with the root key(s) to sign the rotation; enables TUF root import (requires auth-init to have been run first)"`
+	ImportRoots string `arg:"--import-roots" help:"Path to a gzipped tarball containing all root.json files to import"`
+}
 
 func (c TufInitCmd) Run(args CommonArgs) error {
 	fs, err := storage.NewFs(args.DataDir)
 	if err != nil {
 		return err
 	}
-	return fs.Tuf.InitTuf()
+	if c.ImportKeys != "" || c.ImportRoots != "" {
+		if c.ImportKeys == "" {
+			return fmt.Errorf("--import-keys is required to import TUF root metadata")
+		}
+		if c.ImportRoots == "" {
+			return fmt.Errorf("--import-roots is required to import TUF root metadata")
+		}
+		roots, err := loadTufRootsArchive(c.ImportRoots)
+		if err != nil {
+			return err
+		}
+		keys, err := loadTufKeysArchive(c.ImportKeys)
+		if err != nil {
+			return err
+		}
+		if err := fs.Tuf.ImportTuf(roots, keys); err != nil {
+			return err
+		}
+		printRootKeyBackupNotice(fs)
+		return nil
+	}
+	if err := fs.Tuf.InitTuf(); err != nil {
+		return err
+	}
+	printRootKeyBackupNotice(fs)
+	return nil
+}
+
+// printRootKeyBackupNotice warns the operator that the newly created root key
+// is irreplaceable and must be backed up along with the HMAC secret used to
+// decrypt it.
+func printRootKeyBackupNotice(fs *storage.FsHandle) {
+	rootKeyPath := filepath.Join(fs.Config.TufDir(), "keys", "root.key")
+	hmacPath := filepath.Join(fs.Config.AuthDir(), storage.HmacFile)
+	fmt.Println()
+	fmt.Println("TUF initialization completed successfully.")
+	fmt.Println()
+	fmt.Println("IMPORTANT: A new root key was created at:")
+	fmt.Printf("    %s\n", rootKeyPath)
+	fmt.Println()
+	fmt.Println("This key is encrypted at rest using the HMAC secret at:")
+	fmt.Printf("    %s\n", hmacPath)
+	fmt.Println()
+	fmt.Println("Make a backup copy of BOTH files and store them somewhere safe NOW.")
+	fmt.Println("The root key is useless without the HMAC secret needed to decrypt it.")
+	fmt.Println("If either file is lost it CANNOT be recovered, and you will permanently")
+	fmt.Println("lose the ability to rotate or manage your TUF root of trust.")
+	fmt.Println()
+}
+
+// loadTufKeysArchive opens a fioctl offline keys tarball and extracts the
+// root key files it contains. Only private key files (those ending in
+// ".sec") are parsed; all other archive entries are ignored.
+func loadTufKeysArchive(path string) ([]tuf.AtsKey, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("unable to open keys archive: %w", err)
+	}
+	defer f.Close() // nolint:errcheck
+
+	gz, err := gzip.NewReader(f)
+	if err != nil {
+		return nil, fmt.Errorf("unable to open keys archive (expected a gzipped tarball): %w", err)
+	}
+	defer gz.Close() // nolint:errcheck
+
+	var keys []tuf.AtsKey
+	tr := tar.NewReader(gz)
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		} else if err != nil {
+			return nil, fmt.Errorf("unable to read keys archive: %w", err)
+		}
+		if hdr.Typeflag == tar.TypeDir || !strings.HasSuffix(hdr.Name, tufKeyFileSuffix) {
+			continue
+		}
+
+		if data, err := io.ReadAll(tr); err != nil {
+			return nil, fmt.Errorf("unable to read %s from keys archive: %w", hdr.Name, err)
+		} else {
+			var key tuf.AtsKey
+			if err := json.Unmarshal(data, &key); err != nil {
+				return nil, fmt.Errorf("unable to parse key file %s: %w", hdr.Name, err)
+			}
+			if key.KeyType != "" && key.KeyValue.Private != "" {
+				keys = append(keys, key)
+			}
+		}
+	}
+	if len(keys) == 0 {
+		return nil, fmt.Errorf("keys archive does not contain any valid private key files (expected .sec files with private key material)")
+	}
+	return keys, nil
+}
+
+// loadTufRootsArchive reads a gzipped tar archive and returns the raw bytes of
+// every root.json file it contains. Only files ending in ".root.json" are
+// extracted; all other archive entries are ignored.
+func loadTufRootsArchive(path string) ([][]byte, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return nil, fmt.Errorf("unable to open roots archive: %w", err)
+	}
+	defer f.Close() // nolint:errcheck
+
+	gz, err := gzip.NewReader(f)
+	if err != nil {
+		return nil, fmt.Errorf("unable to open roots archive (expected a gzipped tarball): %w", err)
+	}
+	defer gz.Close() // nolint:errcheck
+
+	var roots [][]byte
+	tr := tar.NewReader(gz)
+	for {
+		hdr, err := tr.Next()
+		if err == io.EOF {
+			break
+		} else if err != nil {
+			return nil, fmt.Errorf("unable to read roots archive: %w", err)
+		}
+		if hdr.Typeflag == tar.TypeDir || !strings.HasSuffix(hdr.Name, rootJsonSuffix) {
+			continue
+		}
+
+		if data, err := io.ReadAll(tr); err != nil {
+			return nil, fmt.Errorf("unable to read %s from roots archive: %w", hdr.Name, err)
+		} else {
+			roots = append(roots, data)
+		}
+	}
+	if len(roots) == 0 {
+		return nil, fmt.Errorf("roots archive does not contain any root.json files (expected files ending in %q)", rootJsonSuffix)
+	}
+	return roots, nil
 }

docs/quick-start.md

@@ -69,6 +69,50 @@ root metadata must be initialized:
   ./fioserver --datadir=./datadir tuf-init
 ```
 
+### Importing an existing fleet's TUF root
+
+If you already have a fleet of devices provisioned against a Foundries.io
+factory, initializing a brand new TUF root would leave those devices unable
+to validate metadata from this server. Instead, you can import the factory's
+existing root of trust so that already-provisioned devices continue to trust
+updates.
+
+The import reads every version of the factory's `root.json` from a tarball you
+provide, stores them so devices can walk the trust chain, and then generates a
+new root (version N+1) with fresh online keys for the `root`, `targets`,
+`snapshot`, and `timestamp` roles. The new root is signed by both the factory's
+offline root key (proving continuity of trust) and the new root key.
+
+You will need:
+
+* The factory's offline keys tarball (typically `offline-creds.tgz`),
+  which contains the offline root key used to sign the rotation.
+* A gzipped tarball containing all of the factory's `root.json` files (e.g.
+  `1.root.json`, `2.root.json`, ...). See `fioctl keys tuf show-root`.
+```
+  ./fioserver --datadir=./datadir tuf-init \
+    --import-keys ./offline-creds.tgz \
+    --import-roots ./roots.tgz
+```
+
+Options:
+
+* `--import-keys` — path to the fioctl offline keys tarball. Providing this
+  (or `--import-roots`) enables import mode.
+* `--import-roots` — path to a gzipped tarball containing all of the factory's
+  `root.json` files. See `fioctl keys tuf download-roots`.
+
+> **Note:** `tuf-init` requires `auth-init` to have been run first so that the
+> imported role keys can be encrypted at rest.
+
+> **IMPORTANT:** A successful import generates a new root key at
+> `<datadir>/tufrepo/keys/root.key`. This key is encrypted at rest using the
+> HMAC secret at `<datadir>/auth/hmac.secret`, so you must back up BOTH files —
+> the `root.key` is useless without the `hmac.secret` needed to decrypt it.
+> Store copies of both somewhere safe immediately. If either file is lost it
+> CANNOT be recovered, and you will permanently lose the ability to rotate or
+> manage your TUF root of trust.
+
 ## Run the Server
 
 `./fioserv serve --datadir=datadir`

storage/file_tuf_import.go

@@ -0,0 +1,173 @@
+// Copyright (c) Qualcomm Technologies, Inc. and/or its subsidiaries.
+// SPDX-License-Identifier: BSD-3-Clause-Clear
+
+package storage
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"slices"
+	"strconv"
+	"time"
+
+	"github.com/foundriesio/update-server/clock"
+	"github.com/foundriesio/update-server/storage/tuf"
+)
+
+// importedRoot holds the imported root metadata along with its raw bytes. The
+// raw bytes are stored verbatim so the original signatures remain verifiable.
+type importedRoot struct {
+	raw  []byte
+	root tuf.AtsTufRoot
+}
+
+// ImportTuf initializes TUF for this server by migrating from an existing
+// fioctl/ota-tuf setup.
+//
+// rootJSONs are the raw bytes of every known root.json version. candidateKeys
+// are the private keys extracted from a fioctl offline keys tarball,
+// including the offline private key(s) for the root role. Every imported
+// root.json is stored verbatim, fresh online keys are generated for every role,
+// and a new root.json (version = highest imported version + 1) is created and
+// signed by both the imported (old) root key(s) and the newly generated root
+// key so that clients can verify the chain of trust from the previously
+// trusted root.
+//
+// It fails if TUF data already exists.
+func (h TufFsHandle) ImportTuf(rootJSONs [][]byte, candidateKeys []tuf.AtsKey) error {
+	if h.isInitialized() {
+		return ErrTufAlreadyInitialized
+	}
+
+	if len(rootJSONs) == 0 {
+		return fmt.Errorf("no root metadata was provided to import")
+	}
+	roots := make([]importedRoot, 0, len(rootJSONs))
+	for _, raw := range rootJSONs {
+		var root tuf.AtsTufRoot
+		if err := json.Unmarshal(raw, &root); err != nil {
+			return fmt.Errorf("unable to parse root metadata: %w", err)
+		}
+		if len(root.Signed.Roles) == 0 {
+			return fmt.Errorf("provided metadata does not look like a TUF root.json")
+		}
+		roots = append(roots, importedRoot{raw: raw, root: root})
+	}
+
+	return h.importTuf(roots, candidateKeys)
+}
+
+// importTuf performs the actual import once the root metadata and keys have
+// been parsed.
+func (h TufFsHandle) importTuf(roots []importedRoot, candidateKeys []tuf.AtsKey) error {
+	hmacSecret, err := h.auth.GetHmacSecret()
+	if err != nil {
+		return fmt.Errorf("unable to read HMAC secret (run auth-init first): %w", err)
+	} else if len(hmacSecret) == 0 {
+		return fmt.Errorf("HMAC secret is empty; run auth-init first")
+	}
+
+	// The highest-version imported root is the trust anchor to chain from.
+	slices.SortFunc(roots, func(a, b importedRoot) int {
+		return a.root.Signed.Version - b.root.Signed.Version
+	})
+	base := roots[len(roots)-1]
+
+	// ensure we have all the root.json versions
+	for idx, root := range roots {
+		if idx+1 != root.root.Signed.Version {
+			return fmt.Errorf("missing %d.root.json version", idx+1)
+		}
+	}
+
+	rootThresh := base.root.Signed.Roles[tuf.RoleRoot].Threshold
+	if rootThresh > 1 {
+		return fmt.Errorf("unable to import TUF root. The signature threshold for the root role must be 1. Current value is: %d", rootThresh)
+	}
+
+	oldRootRole, ok := base.root.Signed.Roles[tuf.RoleRoot]
+	if !ok {
+		return fmt.Errorf("imported root.json (version %d) has no root role", base.root.Signed.Version)
+	}
+
+	oldSigner, err := findFirstRootSigner(oldRootRole.KeyIDs, candidateKeys)
+	if err != nil {
+		return err
+	}
+
+	if err := os.MkdirAll(h.keysDir(), defaultDirAccess); err != nil {
+		return fmt.Errorf("unable to create TUF keys directory: %w", err)
+	}
+
+	// Generate fresh online keys for every role owned by this server.
+	signers := make(map[tuf.RoleName]*tuf.Signer, len(tufRoles))
+	for _, role := range tufRoles {
+		signer, err := tuf.NewSigner()
+		if err != nil {
+			return fmt.Errorf("unable to generate %s key: %w", role, err)
+		}
+		if err := h.writeKey(hmacSecret, role, signer); err != nil {
+			return err
+		}
+		signers[role] = signer
+	}
+
+	keys := make(map[string]tuf.AtsKey, len(signers))
+	roles := make(map[tuf.RoleName]tuf.RootRole, len(signers))
+	for _, role := range tufRoles {
+		signer := signers[role]
+		keys[signer.Id] = signer.PublicAtsKey()
+		roles[role] = tuf.RootRole{KeyIDs: []string{signer.Id}, Threshold: 1}
+	}
+	newRoot := tuf.AtsTufRoot{
+		Signed: tuf.RootMeta{
+			SignedCommon: tuf.SignedCommon{
+				Type:    tuf.RoleRoot.TufType(),
+				Expires: clock.Now().UTC().Add(h.RootExpiration).Truncate(time.Second),
+				Version: base.root.Signed.Version + 1,
+			},
+			ConsistentSnapshot: false,
+			Keys:               keys,
+			Roles:              roles,
+		},
+	}
+
+	// The new root must be signed by the new root key and one matching old
+	// root key so it chains from the previously trusted root.
+	newSigned, err := signers[tuf.RoleRoot].Sign(newRoot.Signed)
+	if err != nil {
+		return fmt.Errorf("unable to sign new root metadata: %w", err)
+	}
+	oldSigned, err := oldSigner.Sign(newRoot.Signed)
+	if err != nil {
+		return fmt.Errorf("unable to sign new root metadata with imported key %s: %w", oldSigner.Id, err)
+	}
+	newRoot.Signatures = []tuf.Signature{newSigned, oldSigned}
+
+	// Persist every imported root verbatim, then the newly generated root.
+	if err := h.mkdirs(defaultDirAccess, true); err != nil {
+		return fmt.Errorf("unable to create TUF directory: %w", err)
+	}
+	for _, imp := range roots {
+		name := strconv.Itoa(imp.root.Signed.Version) + rootJsonSuffix
+		if err := h.writeFile(name, string(imp.raw), defaultFileAccess); err != nil {
+			return fmt.Errorf("unable to write %s: %w", name, err)
+		}
+	}
+	return h.writeRoot(newRoot)
+}
+
+func findFirstRootSigner(keyIDs []string, candidateKeys []tuf.AtsKey) (*tuf.ImportSigner, error) {
+	for _, key := range candidateKeys {
+		signer, err := tuf.ImportSignerFromAtsKey(key)
+		if err != nil {
+			// Not a usable signing key (e.g. public-only or unsupported type).
+			continue
+		}
+		if slices.Contains(keyIDs, signer.Id) {
+			return signer, nil
+		}
+	}
+	return nil, fmt.Errorf("unable to find root key signer for key IDs: %v", keyIDs)
+}