diff --git a/DESIGN.md b/DESIGN.md index fb77127..24d8373 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -3182,6 +3182,7 @@ and `[standing]` need a restart. ``` nodkey broker [--config FILE] nodkey broker reload [--config FILE] [--timeout DURATION] +nodkey broker check [--config FILE] [--files DIR] [--credentials DIR] nodkey run [--secret VAR=NAME]... [--grant-token FILE] [--reason TEXT] [--mask | --no-mask] -- COMMAND [ARGS...] nodkey ssh-agent [--socket PATH] nodkey ssh-grant --key NAME --user USER --host NAME... --for DURATION [--reason TEXT] @@ -3312,7 +3313,36 @@ command cannot parse the config (then it sends no signal); 64 on wrong usage. A tool that applies config changes, such as from git, runs it after each change and undoes the change when it fails. -It stops on SIGTERM or SIGINT, also during the start, when the polling +`nodkey broker check` checks a config without a start, such as a new +config before it is applied (issue #173). It starts nothing, opens no +port, uses no network and needs no root. It parses the config with the +code of the start and of a reload (`config.ReadBrokerFiles`, the parser +of `LoadBroker`), with `known_hosts`, and then checks the files that the +config names with `CheckFilesAs`, for the user that runs it. `nodkey +doctor broker` uses the same two parts. It reads no credential: + +- A file in `${CREDENTIALS_DIRECTORY}/` is skipped, and the output says + so. With `--credentials DIR`, `${CREDENTIALS_DIRECTORY}` stands for + DIR, and the check only finds a regular file `NAME` or `NAME.cred` + there. It opens none of them. +- With `--files DIR`, `known_hosts` is read from DIR, by the base name of + its path in the config, and not from that path. So a new config is + checked with its own new `known_hosts`, also in CI. The files of the + broker host (`tls_key`, the token and key files, the store programs and + the audit log) are then not checked; the output says so. Without + `--config`, the config is `DIR/broker.toml`. + +So it does not find what only the content of a credential shows, such as +a TLS or SSH key that does not parse, or two `[key.*]` sections with the +same key in two files. The start and a reload still check these. A +`known_hosts` in `${CREDENTIALS_DIRECTORY}/` is not secret, and is the +one file there that the check reads: from the `--credentials` directory, +or from `--files`. A credential path with `..` in it is refused. Each line +of the output is cleaned with `claim.Line`, so text from the config +cannot add a line or change the terminal. It exits 0 when the config +passed, 1 with the reason when it did not, and 64 on wrong usage. + +The broker stops on SIGTERM or SIGINT, also during the start, when the polling stops for good (section 7), when its server fails, and when a write to stderr fails (a log line or an audit anchor), such as after the reader of stderr went away. The broker catches SIGPIPE with `signal.Notify`, so diff --git a/THREAT-MODEL.md b/THREAT-MODEL.md index 50c1881..d02b39a 100644 --- a/THREAT-MODEL.md +++ b/THREAT-MODEL.md @@ -1485,6 +1485,19 @@ signal another process of the broker's user, or report a false result; that user owns the broker already. The command cleans the text of the file before it prints it. +`nodkey broker check` (issue #173) checks a config before it is applied. +It reads the config and `known_hosts`, from the paths in the config or +from `--files DIR`, and runs as any user. It opens no credential and no +key file: with `--credentials DIR` it only looks for the names. So a +config from a branch or a pull request can be checked in CI without a +secret. (A `known_hosts` in the credentials directory is read: it is not +secret.) It cleans each line of its output (`claim.Line`), so text in a +config from a pull request, such as a line break in a path, cannot add +lines to a CI log. A config that passes the check can still fail at the reload, on +a check that needs a credential; the reload then keeps the old config. +The check is no part of what the broker trusts: the broker checks every +config again when it loads it. + ## 7. Assumptions - The broker host is patched, has no agent on it, and only the owner has diff --git a/cmd/nodkey/broker.go b/cmd/nodkey/broker.go index 5ed710d..67cb64e 100644 --- a/cmd/nodkey/broker.go +++ b/cmd/nodkey/broker.go @@ -106,6 +106,7 @@ var errPanicked = errors.New("it panicked; the panic value is not logged") const brokerUsage = `Usage: nodkey broker [--config FILE] nodkey broker reload [--config FILE] [--timeout DURATION] + nodkey broker check [--config FILE] [--files DIR] [--credentials DIR] Run the broker: the daemon that holds the SSH keys and the access to the secret stores. It asks the approver on Telegram before it hands out a @@ -115,9 +116,11 @@ unit such as contrib/systemd/nodkey.service. --config FILE the broker config (default /etc/nodkey/broker.toml) It logs to stderr, which systemd keeps in the journal, with the anchors -of the audit log. SIGTERM or SIGINT stops it. SIGHUP reloads the config -without a restart; see "nodkey broker reload --help". So does a failed write to +of the audit log. SIGTERM or SIGINT stops it. So does a failed write to stderr, such as after its reader is gone: it stops with exit code 1. +SIGHUP reloads the config without a restart; see "nodkey broker reload +--help". To check a config without a start, see "nodkey broker check +--help". Exit codes: 0 stopped by SIGTERM or SIGINT, 1 any other error, 64 wrong usage, 76 Telegram reports a polling conflict: the bot token may be @@ -131,6 +134,9 @@ func runBroker(args []string, stdout, stderr io.Writer) int { if len(args) > 0 && args[0] == "reload" { return runBrokerReload(args[1:], stdout, stderr) } + if len(args) > 0 && args[0] == "check" { + return runBrokerCheck(args[1:], stdout, stderr) + } // A broken stderr must not end the broker with SIGPIPE in the middle // of a line: the write fails instead, and the broker stops in its // order (issue #73). diff --git a/cmd/nodkey/brokercheck.go b/cmd/nodkey/brokercheck.go new file mode 100644 index 0000000..ab40c8e --- /dev/null +++ b/cmd/nodkey/brokercheck.go @@ -0,0 +1,176 @@ +package main + +import ( + "errors" + "flag" + "fmt" + "io" + "io/fs" + "os" + "path/filepath" + "strings" + + "github.com/code6x/nodkey/internal/claim" + "github.com/code6x/nodkey/internal/config" + "github.com/code6x/nodkey/internal/doctor" +) + +const brokerCheckUsage = `Usage: nodkey broker check [--config FILE] [--files DIR] [--credentials DIR] + +Check a broker config without starting the broker: the config file, and +the files that it names, get the same checks as at a start. It starts +nothing, opens no port, and uses no network. Run it as the broker's user +(on the broker host), or as any user with --files (such as in CI). + + --config FILE the broker config (default /etc/nodkey/broker.toml, + or DIR/broker.toml with --files DIR) + --files DIR read known_hosts from DIR, by the base name of its + path in the config, and not from that path; so a new + config is checked with its own known_hosts. The files + of the broker host (the TLS key, the token and key + files, the store programs, the audit log) are then + not checked + --credentials DIR check that each ${CREDENTIALS_DIRECTORY}/NAME of the + config has a file NAME or NAME.cred in DIR; nothing + in it is read. Without it, these files are skipped + +Exit codes: 0 the config is good, 1 it is not, 64 wrong usage. +` + +// checkLineMax is the most runes of one cleaned line of the output. +const checkLineMax = 2000 + +// runBrokerCheck runs nodkey broker check (DESIGN.md section 15). +func runBrokerCheck(args []string, stdout, stderr io.Writer) int { + fs := flag.NewFlagSet("nodkey broker check", flag.ContinueOnError) + fs.SetOutput(io.Discard) + path := fs.String("config", "", "the broker config") + files := fs.String("files", "", "the directory of known_hosts") + creds := fs.String("credentials", "", "the directory of the credentials") + if err := fs.Parse(args); err != nil { + if errors.Is(err, flag.ErrHelp) { + _, _ = io.WriteString(stdout, brokerCheckUsage) + return exitOK + } + return parseErrorCode(stderr, "broker check", err) + } + if fs.NArg() > 0 { + return usageFail(stderr, "broker check", fmt.Sprintf( + "unexpected argument %.64q; it takes only --config FILE, --files DIR and --credentials DIR", fs.Arg(0))) + } + for _, f := range []struct{ name, dir string }{{"--files", *files}, {"--credentials", *creds}} { + if f.dir == "" { + continue + } + if fi, err := os.Stat(f.dir); err != nil || !fi.IsDir() { + return usageFail(stderr, "broker check", f.name+" must name a directory that exists") + } + } + if *path == "" { + *path = defaultBrokerConfig + if *files != "" { + *path = filepath.Join(*files, "broker.toml") + } + } + res, err := checkBrokerConfig(*path, *files, *creds) + // A config from a pull request may hold any text, such as a line + // break in a path. Each line is cleaned, so that it cannot add lines + // to a CI log or change the terminal. + for _, s := range res.skipped { + _, _ = fmt.Fprintf(stdout, "skipped: %s\n", claim.Line(s, checkLineMax)) + } + if err != nil { + _, _ = fmt.Fprintf(stderr, "nodkey broker check: %s; fix it as the error says (docs/setup.md section 7), "+ + "then run nodkey broker check again\n", claim.Line(err.Error(), checkLineMax)) + return exitFailure + } + _, _ = fmt.Fprintf(stdout, "nodkey broker check: %s passed the checks of a start\n", claim.Line(*path, checkLineMax)) + return exitOK +} + +// checkResult is what checkBrokerConfig did not check, in plain words. +type checkResult struct { + skipped []string +} + +// checkBrokerConfig makes the config checks of a start on the config at +// path: config.ReadBrokerFiles parses it, as config.LoadBroker does for +// the start and a reload, and (*config.Broker).CheckFilesAs checks the +// files it names, as the user that runs this command. It reads no +// credential: a ${CREDENTIALS_DIRECTORY}/ file is skipped, or with +// credDir only found in credDir. With filesDir, known_hosts comes from +// filesDir, and the files of the broker host are not checked. +func checkBrokerConfig(path, filesDir, credDir string) (checkResult, error) { + var res checkResult + // ${CREDENTIALS_DIRECTORY} stands for credDir, or for the directory + // of the unit. Only this process sees the value; a value from the + // environment is not trusted (as in nodkey doctor broker). + dir := "/run/credentials/" + doctor.Unit + if credDir != "" { + abs, err := filepath.Abs(credDir) + if err != nil { + return res, fmt.Errorf("--credentials %s: %w", credDir, err) + } + dir = abs + } + if err := os.Setenv("CREDENTIALS_DIRECTORY", dir); err != nil { + return res, fmt.Errorf("cannot set CREDENTIALS_DIRECTORY: %w", err) + } + cfg, err := config.ReadBrokerFiles(path, filesDir) + if err != nil { + return res, err + } + private, err := cfg.PrivateFiles() + if err != nil { + return res, err + } + inCreds := func(p string) (string, bool) { return strings.CutPrefix(p, dir+"/") } + for _, f := range private { + name, ok := inCreds(f.Path) + switch { + case !ok: + if filesDir != "" { + res.skipped = append(res.skipped, f.Where+": a file of the broker host; --files checks only the "+ + "config and known_hosts") + } + case !filepath.IsLocal(name): + return res, fmt.Errorf("config %s: %s: the path leaves ${CREDENTIALS_DIRECTORY}; write it as "+ + "${CREDENTIALS_DIRECTORY}/NAME, with no \"..\"", path, f.Where) + case credDir == "": + res.skipped = append(res.skipped, fmt.Sprintf("%s: needs the credential %q; give --credentials DIR "+ + "to check that it is there", f.Where, name)) + default: + if err := credentialThere(dir, name); err != nil { + return res, fmt.Errorf("config %s: %s: %w", path, f.Where, err) + } + } + } + if filesDir != "" { + res.skipped = append(res.skipped, "the store programs and audit_log: files of the broker host; "+ + "--files checks only the config and known_hosts") + return res, nil + } + self := uint32(os.Getuid()) //nolint:gosec // G115: a user ID fits in 32 bits on Linux. + skip := func(p string) bool { _, ok := inCreds(p); return ok } + return res, cfg.CheckFilesAs(self, skip) +} + +// credentialThere checks that dir has a regular file name or name.cred. +// It reads nothing in it. name must pass filepath.IsLocal. +func credentialThere(dir, name string) error { + for _, n := range []string{name, name + ".cred"} { + fi, err := os.Stat(filepath.Join(dir, n)) + switch { + case err == nil && fi.Mode().IsRegular(): + return nil + case err == nil: + return fmt.Errorf("the credential %q in %s is not a regular file; put the encrypted credential there", n, dir) + case !errors.Is(err, fs.ErrNotExist): + return fmt.Errorf("cannot look for the credential %q in %s as this user (%w); give --credentials a "+ + "directory that this user can enter, or check the credentials with nodkey doctor broker, as root", + n, dir, errors.Unwrap(err)) + } + } + return fmt.Errorf("the credential %q is not in %s: there is no file %q or %q; make it as docs/setup.md "+ + "section 3 shows", name, dir, name, name+".cred") +} diff --git a/cmd/nodkey/brokercheck_linux_test.go b/cmd/nodkey/brokercheck_linux_test.go new file mode 100644 index 0000000..3b50a5d --- /dev/null +++ b/cmd/nodkey/brokercheck_linux_test.go @@ -0,0 +1,283 @@ +package main + +import ( + "bytes" + "net" + "os" + "path/filepath" + "strings" + "testing" +) + +// The tests of nodkey broker check run it in this process. It sets +// CREDENTIALS_DIRECTORY for the process, so these tests are not parallel, +// and each one gives the variable back with t.Setenv. + +func runCheck(t *testing.T, args ...string) (code int, stdout, stderr string) { + t.Helper() + var out, errOut bytes.Buffer + code = runBroker(append([]string{"check"}, args...), &out, &errOut) + return code, out.String(), errOut.String() +} + +// TestBrokerCheckRefusesWhatTheStartRefuses: for each config that the +// start of nodkey broker refuses, nodkey broker check exits 1 with the +// same reason. A good config passes both. +func TestBrokerCheckRefusesWhatTheStartRefuses(t *testing.T) { + t.Setenv("CREDENTIALS_DIRECTORY", "") + cases := []struct { + name string + change func(t *testing.T, e *brokerEnv) + reason string // in the log of the start and in the check's error + }{ + {"a bad pin", func(t *testing.T, e *brokerEnv) { + appendConfig(t, e, "\n[client.bad]\npin = \"not-a-pin\"\n") + }, "[client.bad] pin"}, + {"a host that known_hosts does not have", func(t *testing.T, e *brokerEnv) { + replaceConfig(t, e, `hosts = ["web-1"]`, `hosts = ["web-9"]`) + }, "[key.deploy] hosts: item 1 is not a host in known_hosts"}, + {"a store program that others can change", func(t *testing.T, e *brokerEnv) { + if err := os.Chmod(filepath.Join(e.dir, "bin", "bws"), 0o722); err != nil { //nolint:gosec // G302: the test makes a bad mode. + t.Fatal(err) + } + }, "[store.main] program"}, + {"a known_hosts that others can change", func(t *testing.T, e *brokerEnv) { + if err := os.Chmod(filepath.Join(e.dir, "etc", "known_hosts"), 0o622); err != nil { //nolint:gosec // G302: the test makes a bad mode. + t.Fatal(err) + } + }, "known_hosts"}, + {"an audit log that is a key file", func(t *testing.T, e *brokerEnv) { + replaceConfig(t, e, "audit_log = \""+e.auditPath+"\"", + "audit_log = \""+filepath.Join(e.dir, "bin", "bws-vault")+"\"") + }, "audit_log"}, + } + for _, c := range cases { + t.Run(c.name, func(t *testing.T) { + e := newBrokerEnv(t, brokerOptions{}) + c.change(t, e) + e.start() + e.mustExit(exitFailure) + if !e.stderr.has(c.reason) { + t.Fatalf("the start does not say %q; its log:\n%s", c.reason, e.stderr.text()) + } + code, out, errOut := runCheck(t, "--config", e.cfgPath, "--credentials", filepath.Join(e.dir, "creds")) + if code != exitFailure || out != "" || !strings.Contains(errOut, c.reason) || + strings.Count(errOut, "\n") != 1 || !strings.Contains(errOut, "docs/setup.md section 7") { + t.Fatalf("check: exit %d, stdout %q, stderr %q; want exit 1 with %q", code, out, errOut, c.reason) + } + }) + } + t.Run("a good config", func(t *testing.T) { + e := newBrokerEnv(t, brokerOptions{}) + code, out, errOut := runCheck(t, "--config", e.cfgPath, "--credentials", filepath.Join(e.dir, "creds")) + if code != exitOK || errOut != "" || strings.Contains(out, "skipped") || + !strings.Contains(out, "passed the checks of a start") { + t.Fatalf("check: exit %d, stdout %q, stderr %q", code, out, errOut) + } + }) +} + +// TestBrokerCheckFiles: with --files DIR, known_hosts comes from DIR, and +// the file at the path in the config is not read. +func TestBrokerCheckFiles(t *testing.T) { + t.Setenv("CREDENTIALS_DIRECTORY", "") + e := newBrokerEnv(t, brokerOptions{}) + files := filepath.Join(e.dir, "new") + if err := os.Mkdir(files, 0o700); err != nil { + t.Fatal(err) + } + cfg, err := os.ReadFile(e.cfgPath) + if err != nil { + t.Fatal(err) + } + knownHosts := filepath.Join(e.dir, "etc", "known_hosts") + good, err := os.ReadFile(knownHosts) //nolint:gosec // G304: the test's own file. + if err != nil { + t.Fatal(err) + } + writeTestFile(t, filepath.Join(files, "broker.toml"), cfg, 0o600) + writeTestFile(t, filepath.Join(files, "known_hosts"), good, 0o600) + // The file at the path in the config is gone: the check passes, so it + // did not read it. + if err := os.Remove(knownHosts); err != nil { + t.Fatal(err) + } + code, out, errOut := runCheck(t, "--files", files) + if code != exitOK || errOut != "" || !strings.Contains(out, filepath.Join(files, "broker.toml")+" passed") { + t.Fatalf("check --files: exit %d, stdout %q, stderr %q", code, out, errOut) + } + for _, want := range []string{"needs the credential \"telegram-token\"", "the store programs and audit_log"} { + if !strings.Contains(out, "skipped: ") || !strings.Contains(out, want) { + t.Errorf("stdout %q does not say %q", out, want) + } + } + // A good known_hosts at the path, and one in DIR without web-1: the + // check uses the one in DIR, and refuses the config. + writeTestFile(t, knownHosts, good, 0o600) + var noWeb []string + for line := range strings.Lines(string(good)) { + if !strings.HasPrefix(line, "web-1 ") { + noWeb = append(noWeb, line) + } + } + writeTestFile(t, filepath.Join(files, "known_hosts"), []byte(strings.Join(noWeb, "")), 0o600) + code, out, errOut = runCheck(t, "--files", files) + if code != exitFailure || !strings.Contains(errOut, "[key.deploy] hosts: item 1 is not a host") { + t.Fatalf("check --files with a known_hosts without web-1: exit %d, stdout %q, stderr %q", code, out, errOut) + } + // --config with --files: the config from --config, known_hosts from DIR. + code, _, errOut = runCheck(t, "--config", e.cfgPath, "--files", files) + if code != exitFailure || !strings.Contains(errOut, "[key.deploy] hosts: item 1 is not a host") { + t.Fatalf("check --config --files: exit %d, stderr %q", code, errOut) + } +} + +// TestBrokerCheckNeedsNoCredentials: the check runs as a user that is not +// root, does not read the credentials, and opens no port. +func TestBrokerCheckNeedsNoCredentials(t *testing.T) { + t.Setenv("CREDENTIALS_DIRECTORY", "") + if os.Getuid() == 0 { + t.Skip("runs as root; this test is for a user that is not root") + } + e := newBrokerEnv(t, brokerOptions{}) + // The test holds the listen address: a start would fail there. + ln, err := (&net.ListenConfig{}).Listen(t.Context(), "tcp", e.addr) + if err != nil { + t.Fatal(err) + } + defer func() { _ = ln.Close() }() + + // No --credentials: each credential is skipped, and the check passes. + code, out, errOut := runCheck(t, "--config", e.cfgPath) + if code != exitOK || errOut != "" { + t.Fatalf("check: exit %d, stdout %q, stderr %q", code, out, errOut) + } + for _, name := range []string{"broker-tls-key", "telegram-token", "bws-token", "bws-token-vault", "ssh-deploy"} { + if !strings.Contains(out, "needs the credential \""+name+"\";") { + t.Errorf("stdout %q does not skip %s", out, name) + } + } + + // --credentials with files that nobody may read: they are found, not + // read. NAME.cred counts too. + creds := filepath.Join(e.dir, "sealed") + if err := os.Mkdir(creds, 0o700); err != nil { + t.Fatal(err) + } + for _, name := range []string{"broker-tls-key", "telegram-token", "bws-token.cred", "bws-token-vault", "ssh-deploy.cred"} { + writeTestFile(t, filepath.Join(creds, name), []byte("sealed"), 0) + } + code, out, errOut = runCheck(t, "--config", e.cfgPath, "--credentials", creds) + if code != exitOK || errOut != "" || strings.Contains(out, "skipped") { + t.Fatalf("check --credentials: exit %d, stdout %q, stderr %q", code, out, errOut) + } + + // A missing credential: exit 1, and the error names it and its place. + if err := os.Remove(filepath.Join(creds, "ssh-deploy.cred")); err != nil { + t.Fatal(err) + } + code, out, errOut = runCheck(t, "--config", e.cfgPath, "--credentials", creds) + if code != exitFailure || out != "" || !strings.Contains(errOut, "[key.deploy] file: the credential \"ssh-deploy\" is not in") { + t.Fatalf("check without ssh-deploy: exit %d, stdout %q, stderr %q", code, out, errOut) + } + // A directory is not a credential. + if err := os.Mkdir(filepath.Join(creds, "ssh-deploy"), 0o700); err != nil { + t.Fatal(err) + } + if code, _, errOut = runCheck(t, "--config", e.cfgPath, "--credentials", creds); code != exitFailure || + !strings.Contains(errOut, "is not a regular file") { + t.Fatalf("check with a directory for ssh-deploy: exit %d, stderr %q", code, errOut) + } + // A directory that this user cannot enter: the error says so, and + // does not say that the credential is missing. + if err := os.Chmod(creds, 0); err != nil { + t.Fatal(err) + } + t.Cleanup(func() { _ = os.Chmod(creds, 0o700) }) //nolint:gosec // G302: the test's own directory. + code, _, errOut = runCheck(t, "--config", e.cfgPath, "--credentials", creds) + if code != exitFailure || !strings.Contains(errOut, "cannot look for the credential") || + strings.Contains(errOut, "is not in") { + t.Fatalf("check with a closed credentials directory: exit %d, stderr %q", code, errOut) + } + // A credential path with "..": refused, with a clear reason. + if err := os.Chmod(creds, 0o700); err != nil { //nolint:gosec // G302: the test's own directory. + t.Fatal(err) + } + replaceConfig(t, e, "${CREDENTIALS_DIRECTORY}/ssh-deploy", "${CREDENTIALS_DIRECTORY}/../ssh-deploy") + for _, args := range [][]string{{}, {"--credentials", creds}} { + code, _, errOut = runCheck(t, append([]string{"--config", e.cfgPath}, args...)...) + if code != exitFailure || !strings.Contains(errOut, "[key.deploy] file: the path leaves ${CREDENTIALS_DIRECTORY}") { + t.Fatalf("check %q with ../ssh-deploy: exit %d, stderr %q", args, code, errOut) + } + } +} + +// TestBrokerCheckCleansConfigText: text from the config, such as a line +// break in a path, cannot add a line to the output. +func TestBrokerCheckCleansConfigText(t *testing.T) { + t.Setenv("CREDENTIALS_DIRECTORY", "") + e := newBrokerEnv(t, brokerOptions{}) + replaceConfig(t, e, "known_hosts = \"", "known_hosts = \"/etc/a\\n::error::fake\\u001b[31m") + for _, args := range [][]string{{"--config", e.cfgPath}, {"--config", e.cfgPath, "--files", e.dir}} { + code, out, errOut := runCheck(t, args...) + if code != exitFailure || out != "" || strings.Count(errOut, "\n") != 1 || strings.ContainsRune(errOut, 0x1b) { + t.Errorf("check %q: exit %d, stdout %q, stderr %q; want exit 1 and one clean line", args, code, out, errOut) + } + } + // The same in a skipped line. + e = newBrokerEnv(t, brokerOptions{}) + replaceConfig(t, e, "${CREDENTIALS_DIRECTORY}/ssh-deploy", "${CREDENTIALS_DIRECTORY}/ssh\\n::error::x") + code, out, errOut := runCheck(t, "--config", e.cfgPath) + if code != exitOK || strings.Contains(out, "\n::error") { + t.Errorf("check: exit %d, stdout %q, stderr %q", code, out, errOut) + } +} + +// TestBrokerCheckUsage: wrong usage exits 64 with one line. +func TestBrokerCheckUsage(t *testing.T) { + t.Setenv("CREDENTIALS_DIRECTORY", "") + missing := filepath.Join(t.TempDir(), "missing") + for _, args := range [][]string{ + {"--nope"}, + {"extra"}, + {"--files", missing}, + {"--credentials", missing}, + {"--config"}, + } { + code, out, errOut := runCheck(t, args...) + if code != exitUsage || out != "" || strings.Count(errOut, "\n") != 1 || + !strings.HasPrefix(errOut, "nodkey broker check: ") { + t.Errorf("check %q: exit %d, stdout %q, stderr %q; want exit 64 and one line", args, code, out, errOut) + } + } + code, out, _ := runCheck(t, "--help") + if code != exitOK || !strings.HasPrefix(out, "Usage: nodkey broker check") { + t.Errorf("check --help: exit %d, stdout %q", code, out) + } + // A config that is not there: exit 1, with the path. + code, _, errOut := runCheck(t, "--config", missing) + if code != exitFailure || !strings.Contains(errOut, missing) { + t.Errorf("check of a missing config: exit %d, stderr %q", code, errOut) + } +} + +func appendConfig(t *testing.T, e *brokerEnv, extra string) { + t.Helper() + data, err := os.ReadFile(e.cfgPath) + if err != nil { + t.Fatal(err) + } + writeTestFile(t, e.cfgPath, append(data, extra...), 0o600) +} + +func replaceConfig(t *testing.T, e *brokerEnv, old, repl string) { + t.Helper() + data, err := os.ReadFile(e.cfgPath) + if err != nil { + t.Fatal(err) + } + if !bytes.Contains(data, []byte(old)) { + t.Fatalf("the config has no %q", old) + } + writeTestFile(t, e.cfgPath, bytes.Replace(data, []byte(old), []byte(repl), 1), 0o600) +} diff --git a/docs/setup.md b/docs/setup.md index 57eb4fd..811ac02 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1277,6 +1277,51 @@ The file holds no secret, but it lists your secret names, hosts and item IDs. To hide it from other users, use group `nodkey` and mode `0640` instead. +### Check a config before you use it + +`nodkey broker check` checks a config without a start. It makes the +checks of a start on the config file and on the files that it names. It +starts nothing, opens no port, uses no network, and needs no root. On +the broker host, run it as root like this, so that it runs as the +broker's user: + +```sh +runuser -u nodkey -- nodkey broker check --config /etc/nodkey/broker.toml +``` + +It exits with 0 when the config is good, 1 when it is not (it prints +why), and 64 on wrong usage. It never reads a credential. It skips each +`${CREDENTIALS_DIRECTORY}/` file and says so. `nodkey doctor broker` +([section 14](#14-when-something-does-not-work)) checks that the unit +has each of them. With `--credentials DIR`, the check looks for a file +with the name, or the name and `.cred`, in DIR. It opens none of them. +The user that runs the check must be able to enter DIR, and only root +can enter `/etc/nodkey/credentials`. + +To check a new config before you copy it to `/etc/nodkey/`, such as in +CI, put `broker.toml` and `known_hosts` in one directory and use +`--files`. It reads `known_hosts` from that directory, by the base name +of its path in the config, and not from `/etc/nodkey/`. It does not check the files of the broker host then: +the TLS key, the token and key files, the store programs and the audit +log. In CI, run it as the user of the job: + +```sh +nodkey broker check --files ./broker-config +``` + +The directory and the files must be owned by the user that runs the +check, or by root, and others must not be able to change them. On the +broker host, root can run it with `--files` too, on a directory that +root owns, such as `/etc/nodkey/new`. Then it can also look for the +credentials: + +```sh +nodkey broker check --files /etc/nodkey/new --credentials /etc/nodkey/credentials +``` + +A config that passes the check can still fail at a start or a reload, on +a check that needs a credential, such as a key file that does not parse. + ## 8. The systemd unit Copy the example unit @@ -1615,6 +1660,8 @@ nodkey broker reload It asks the broker to load the config again (with `SIGHUP`), and waits for the result. The broker checks the new config as at a start. +To check a config before you use it, run `nodkey broker check` +([section 7](#check-a-config-before-you-use-it)). - When the new config is good, the broker uses it at once, and the command exits with 0. Grants that the new config still allows stay, diff --git a/internal/config/broker.go b/internal/config/broker.go index 9961c4e..57f2547 100644 --- a/internal/config/broker.go +++ b/internal/config/broker.go @@ -387,7 +387,7 @@ func validField(f string) bool { // with ReadConfigFile. A config that LoadBroker returns has passed all // these checks; on any error it returns no config. func LoadBroker(path string) (*Broker, error) { - b, err := loadBroker(path) + b, err := loadBroker(path, "") if err != nil { return nil, err } @@ -399,10 +399,20 @@ func LoadBroker(path string) (*Broker, error) { // ReadBroker is LoadBroker without CheckFiles: nodkey doctor broker // checks the files itself, with CheckFilesAs. -func ReadBroker(path string) (*Broker, error) { return loadBroker(path) } - -// loadBroker is LoadBroker without CheckFiles. -func loadBroker(path string) (*Broker, error) { +func ReadBroker(path string) (*Broker, error) { return loadBroker(path, "") } + +// ReadBrokerFiles is ReadBroker, but it reads known_hosts from the +// directory dir, by the base name of the known_hosts path in the config, +// and not from that path (nodkey broker check --files). So a new config is +// checked with its own new known_hosts. The config keeps the path that it +// names in KnownHostsFile. An empty dir is ReadBroker. +func ReadBrokerFiles(path, dir string) (*Broker, error) { return loadBroker(path, dir) } + +// loadBroker is LoadBroker without CheckFiles. When filesDir is not +// empty, known_hosts is read from it (see ReadBrokerFiles). The start, +// a reload, nodkey doctor broker and nodkey broker check all parse the +// config here, so they make the same checks. +func loadBroker(path, filesDir string) (*Broker, error) { data, err := ReadConfigFile(path) if err != nil { // The error can name a directory on the way, so name the file too. @@ -412,7 +422,7 @@ func loadBroker(path string) (*Broker, error) { if err := decode(data, &f, "client", "store", "secret", "key"); err != nil { return nil, fmt.Errorf("config %s: %w", path, err) } - b, err := newBroker(&f) + b, err := newBroker(&f, filesDir) if err != nil { return nil, fmt.Errorf("config %s: %w", path, err) } @@ -422,7 +432,7 @@ func loadBroker(path string) (*Broker, error) { return b, nil } -func newBroker(f *brokerFile) (*Broker, error) { +func newBroker(f *brokerFile, filesDir string) (*Broker, error) { b := &Broker{ Clients: make(map[string]Client), Stores: make(map[string]Store), @@ -482,7 +492,11 @@ func newBroker(f *brokerFile) (*Broker, error) { if err := b.addSecrets(f.Secret); err != nil { return nil, err } - if b.KnownHosts, err = LoadKnownHosts(b.KnownHostsFile); err != nil { + knownHosts := b.KnownHostsFile + if filesDir != "" { + knownHosts = filepath.Join(filesDir, filepath.Base(knownHosts)) + } + if b.KnownHosts, err = LoadKnownHosts(knownHosts); err != nil { return nil, fmt.Errorf("known_hosts: %w", err) } if err := b.addKeys(f.Key); err != nil { @@ -1296,38 +1310,54 @@ func (b *Broker) approverTokenPlace() string { return place("[telegram]", "token_file") } -// CheckFilesAs is CheckFiles for the user ID self, the user that runs the -// broker, such as when root runs nodkey doctor broker. It skips each file -// that holds a key, a token or a password, and the config file and -// known_hosts, when skip reports true for its path: the credentials of -// the unit are there only while the service runs. -func (b *Broker) CheckFilesAs(self uint32, skip func(path string) bool) error { - if skip == nil { - skip = func(string) bool { return false } - } - type file struct { - where, path string - key bool - } - private := []file{ - {"tls_key", b.TLSKey, false}, - {b.approverTokenPlace(), b.ApproverTokenFile(), false}, +// PrivateFile is a file that holds a key, a token or a password, as the +// config names it. +type PrivateFile struct { + Where string // the place in the config, such as "[store.main] token_file" + Path string // the expanded path + Key bool // the file of a [key.*] section +} + +// PrivateFiles returns the files of the config that hold a key, a token or +// a password, in the order in which CheckFilesAs checks them: tls_key, the +// approver's token_file, the stores by name, and the keys by name. +func (b *Broker) PrivateFiles() ([]PrivateFile, error) { + private := []PrivateFile{ + {Where: "tls_key", Path: b.TLSKey}, + {Where: b.approverTokenPlace(), Path: b.ApproverTokenFile()}, } for _, name := range slices.Sorted(maps.Keys(b.Stores)) { s := b.Stores[name] + sec := sectionName("store", name) switch s.Type { case StoreBWS, StoreOnePassword: - private = append(private, file{place(sectionName("store", name), "token_file"), s.TokenFile, false}) + private = append(private, PrivateFile{Where: place(sec, "token_file"), Path: s.TokenFile}) case StoreBW: - private = append(private, file{place(sectionName("store", name), "password_file"), s.PasswordFile, false}) + private = append(private, PrivateFile{Where: place(sec, "password_file"), Path: s.PasswordFile}) case StoreInfisical: - private = append(private, file{place(sectionName("store", name), "client_secret_file"), s.ClientSecretFile, false}) + private = append(private, PrivateFile{Where: place(sec, "client_secret_file"), Path: s.ClientSecretFile}) default: - return fmt.Errorf("config %s: %s: unknown store type", b.Path, sectionName("store", name)) + return nil, fmt.Errorf("config %s: %s: unknown store type", b.Path, sec) } } for _, name := range slices.Sorted(maps.Keys(b.Keys)) { - private = append(private, file{place(sectionName("key", name), "file"), b.Keys[name].File, true}) + private = append(private, PrivateFile{Where: place(sectionName("key", name), "file"), Path: b.Keys[name].File, Key: true}) + } + return private, nil +} + +// CheckFilesAs is CheckFiles for the user ID self, the user that runs the +// broker, such as when root runs nodkey doctor broker. It skips each file +// that holds a key, a token or a password, and the config file and +// known_hosts, when skip reports true for its path: the credentials of +// the unit are there only while the service runs. +func (b *Broker) CheckFilesAs(self uint32, skip func(path string) bool) error { + if skip == nil { + skip = func(string) bool { return false } + } + private, err := b.PrivateFiles() + if err != nil { + return err } // checked holds every file that the broker reads or runs, to compare // it with the audit log. @@ -1338,20 +1368,20 @@ func (b *Broker) CheckFilesAs(self uint32, skip func(path string) bool) error { } var checked []checkedFile for _, f := range private { - if skip(f.path) { + if skip(f.Path) { continue } - fi, err := checkPrivateFileAs(f.path, self) + fi, err := checkPrivateFileAs(f.Path, self) if err != nil { - return fmt.Errorf("config %s: %s: %w", b.Path, f.where, err) + return fmt.Errorf("config %s: %s: %w", b.Path, f.Where, err) } for _, c := range checked { - if f.key && c.key && os.SameFile(c.fi, fi) { + if f.Key && c.key && os.SameFile(c.fi, fi) { return fmt.Errorf("config %s: %s: is the same file as %s; each key may have one section", - b.Path, f.where, c.where) + b.Path, f.Where, c.where) } } - checked = append(checked, checkedFile{f.where, fi, f.key}) + checked = append(checked, checkedFile{f.Where, fi, f.Key}) } for _, name := range slices.Sorted(maps.Keys(b.Stores)) { if t := b.Stores[name].Type; t == StoreOnePassword || t == StoreInfisical { diff --git a/internal/config/broker_test.go b/internal/config/broker_test.go index c98ec1c..b3adce3 100644 --- a/internal/config/broker_test.go +++ b/internal/config/broker_test.go @@ -997,7 +997,7 @@ func TestCheckFilesSameKeyFile(t *testing.T) { e := newBrokerEnv(t) path := e.write(t, edit{"[key.backup]", "[key.deploy-2]\nfile = \"" + tt.file(t, e) + "\"\nclients = [\"laptop\"]\nask = \"always\"\n\n[key.backup]"}) - if _, err := loadBroker(path); err != nil { + if _, err := loadBroker(path, ""); err != nil { t.Fatalf("loadBroker: %v", err) } b, err := LoadBroker(path) @@ -1036,7 +1036,7 @@ func TestLoadBrokerRunsCheckFiles(t *testing.T) { e := newBrokerEnv(t) path := e.write(t) tt.setup(t, e) - if _, err := loadBroker(path); err != nil { + if _, err := loadBroker(path, ""); err != nil { t.Fatalf("loadBroker: %v", err) } b, err := LoadBroker(path) @@ -1333,7 +1333,7 @@ func TestCheckFilesAuditLogIsAnotherFile(t *testing.T) { if tt.mode != 0 { chmod(t, audit, tt.mode) } - if _, err := loadBroker(path); err != nil { + if _, err := loadBroker(path, ""); err != nil { t.Fatalf("loadBroker: %v", err) } b, err := LoadBroker(path) diff --git a/internal/config/config_test.go b/internal/config/config_test.go index c4bef1b..6c1669c 100644 --- a/internal/config/config_test.go +++ b/internal/config/config_test.go @@ -567,7 +567,7 @@ func FuzzDecodeDoesNotRepeatText(f *testing.F) { err := decode([]byte(data), &b, "client", "store", "secret", "key") if err == nil { b.KnownHosts = knownHosts - _, err = newBroker(&b) + _, err = newBroker(&b, "") } if err != nil && strings.Contains(err.Error(), pasteMark) { t.Fatalf("broker config: the error shows the mark: %v", err)