diff --git a/CONFORMANCE.md b/CONFORMANCE.md index fd492ea..0692419 100644 --- a/CONFORMANCE.md +++ b/CONFORMANCE.md @@ -94,3 +94,7 @@ Pages avoid full-log/category/sales-history copies, but sparse filters can scan the remaining catalogue. Existing unpaged reads remain unbounded; in-memory, single-writer and witnessing limitations remain unchanged. See `docs/marketplace-browse.md` for query syntax and compatibility limits. + +### Witness key-file custody + +`witnessd -seed-file` checks regular-file type, effective-user ownership, owner-only permissions, and macOS extended ACLs on the opened file before reading a bounded hexadecimal seed. Unsupported platform/build access checks fail closed. `TestWitnessSeedFileIdentity`, `TestWitnessSeedFileRejectsUnsafeInput`, `TestWitnessSeedFileRejectsSymlink`, `TestWitnessSeedFileRejectsACL` (macOS), and `TestWitnessSeedCompatibility` bind stable public identity, startup refusal, private-material exclusion from diagnostics, and legacy/demo behavior. This persists key identity only: rollback memory remains ephemeral, trust on first checkpoint remains, and no federation or registry is introduced. diff --git a/README.md b/README.md index a0358b1..f3ebb05 100644 --- a/README.md +++ b/README.md @@ -165,3 +165,5 @@ independent witnessing. AGPL-3.0-or-later. *Network Theory Applied Research Institute, Inc. — 501(c)(3) — EIN 92-3047136 — info@ntari.org* + +Witness operators: use [`witnessd -seed-file`](docs/witness-seed-files.md) for persistent identity without placing private seed material in process arguments. diff --git a/cmd/witnessd/main.go b/cmd/witnessd/main.go index 37497be..6729d47 100644 --- a/cmd/witnessd/main.go +++ b/cmd/witnessd/main.go @@ -12,8 +12,6 @@ package main import ( - "crypto/ed25519" - "crypto/rand" "encoding/hex" "flag" "log" @@ -28,23 +26,24 @@ func main() { relayURL := flag.String("relay", "http://localhost:8090", "witness relay base URL") intakeAddr := flag.String("intake", ":8091", "listen address for the filing intake") interval := flag.Duration("interval", 30*time.Second, "poll interval") - seedHex := flag.String("seed", "", "hex ed25519 seed (32 bytes); ephemeral when empty — ephemeral witnesses forget, use a persistent seed in anything but a demo") + seedHex := flag.String("seed", "", "DEPRECATED: hex ed25519 seed; use -seed-file to keep secrets out of process arguments") + seedFile := flag.String("seed-file", "", "protected file containing 64 hex seed digits; Linux/macOS owner-only permissions required") flag.Parse() - - var priv ed25519.PrivateKey - if *seedHex == "" { - _, p, err := ed25519.GenerateKey(rand.Reader) - if err != nil { - log.Fatalf("witnessd: generating key: %v", err) - } - priv = p - log.Printf("witnessd: EPHEMERAL key (amnesia on restart is total); pass -seed for anything beyond a demo") - } else { - seed, err := hex.DecodeString(*seedHex) - if err != nil || len(seed) != ed25519.SeedSize { - log.Fatalf("witnessd: -seed must be %d hex bytes", ed25519.SeedSize) + flag.Visit(func(f *flag.Flag) { + if f.Name == "seed-file" && f.Value.String() == "" { + log.Fatal("witnessd: -seed-file must not be empty") } - priv = ed25519.NewKeyFromSeed(seed) + }) + + priv, err := witnessKey(*seedHex, *seedFile) + if err != nil { + log.Fatalf("witnessd: %v", err) + } + if *seedHex != "" { + log.Print("witnessd: -seed is deprecated; migrate to -seed-file to avoid process-argument and shell-history exposure") + } + if *seedHex == "" && *seedFile == "" { + log.Print("witnessd: EPHEMERAL key (amnesia on restart is total); use -seed-file for a persistent identity beyond a demo") } w := witnesskit.NewWorker(priv, *relayURL) diff --git a/cmd/witnessd/seed.go b/cmd/witnessd/seed.go new file mode 100644 index 0000000..5b68ee5 --- /dev/null +++ b/cmd/witnessd/seed.go @@ -0,0 +1,50 @@ +package main + +import ( + "crypto/ed25519" + "crypto/rand" + "encoding/hex" + "errors" + "io" + "strings" +) + +// witnessKey never includes input bytes or paths in diagnostics. +func witnessKey(seedHex, seedPath string) (ed25519.PrivateKey, error) { + if seedHex != "" && seedPath != "" { + return nil, errors.New("-seed and -seed-file are mutually exclusive") + } + if seedPath != "" { + var err error + seedHex, err = readSeedHex(seedPath) + if err != nil { + return nil, err + } + } + + if seedHex == "" && seedPath == "" { + _, priv, err := ed25519.GenerateKey(rand.Reader) + return priv, err + } + seed, err := hex.DecodeString(seedHex) + if err != nil || len(seed) != ed25519.SeedSize { + return nil, errors.New("seed must contain exactly 64 hex digits") + } + return ed25519.NewKeyFromSeed(seed), nil +} + +func readSeedHex(path string) (string, error) { + file, err := openSeedFile(path) + if err != nil { + return "", err + } + defer func() { _ = file.Close() }() + data, err := io.ReadAll(io.LimitReader(file, 67)) + if err != nil { + return "", errors.New("cannot read -seed-file") + } + if len(data) > 66 { + return "", errors.New("-seed-file must contain 64 hex digits with optional newline") + } + return strings.TrimSuffix(strings.TrimSuffix(string(data), "\n"), "\r"), nil +} diff --git a/cmd/witnessd/seed_acl_darwin.go b/cmd/witnessd/seed_acl_darwin.go new file mode 100644 index 0000000..c732b09 --- /dev/null +++ b/cmd/witnessd/seed_acl_darwin.go @@ -0,0 +1,38 @@ +//go:build cgo + +package main + +/* +#include +*/ +import "C" + +import ( + "errors" + "os" + "syscall" + "unsafe" +) + +// Darwin mode bits omit ACL read grants. Query the opened descriptor directly; +// reject all extended ACLs rather than interpret inherited grants. +func checkSeedACL(file *os.File) error { + + acl, err := C.acl_get_fd_np(C.int(file.Fd()), C.ACL_TYPE_EXTENDED) + if acl == nil { + if errors.Is(err, syscall.ENOENT) { + return nil + } + return errors.New("cannot verify -seed-file macOS ACL") + } + defer func() { _, _ = C.acl_free(unsafe.Pointer(acl)) }() + var entry C.acl_entry_t + status, err := C.acl_get_entry(acl, C.ACL_FIRST_ENTRY, &entry) + if status == 0 { + return errors.New("-seed-file must have no extended ACL; remove grants with chmod -N") + } + if errors.Is(err, syscall.EINVAL) { + return nil + } // Valid ACL with no first entry. + return errors.New("cannot inspect -seed-file macOS ACL") +} diff --git a/cmd/witnessd/seed_acl_darwin_test.go b/cmd/witnessd/seed_acl_darwin_test.go new file mode 100644 index 0000000..26b7898 --- /dev/null +++ b/cmd/witnessd/seed_acl_darwin_test.go @@ -0,0 +1,19 @@ +package main + +import ( + "os/exec" + "strings" + "testing" +) + +// macOS ACL read grants are not reflected in mode bits. +func TestWitnessSeedFileRejectsACL(t *testing.T) { + path := writeSeed(t, testSeed, 0600) + if out, err := exec.Command("/bin/chmod", "+a", "everyone allow read", path).CombinedOutput(); err != nil { + t.Fatalf("set fixture ACL: %v %s", err, out) + } + out := startup(t, seedDaemon(t), "-seed-file", path) + if strings.Contains(out, "witness key ") || !strings.Contains(out, "ACL") { + t.Fatalf("readable ACL accepted: %s", out) + } +} diff --git a/cmd/witnessd/seed_acl_linux.go b/cmd/witnessd/seed_acl_linux.go new file mode 100644 index 0000000..39d07f3 --- /dev/null +++ b/cmd/witnessd/seed_acl_linux.go @@ -0,0 +1,7 @@ +package main + +import "os" + +// Linux POSIX ACL permissions are bounded by the group-class mode mask, +// already required to be zero by openSeedFile. +func checkSeedACL(_ *os.File) error { return nil } diff --git a/cmd/witnessd/seed_acl_nocgo_darwin.go b/cmd/witnessd/seed_acl_nocgo_darwin.go new file mode 100644 index 0000000..9e79e25 --- /dev/null +++ b/cmd/witnessd/seed_acl_nocgo_darwin.go @@ -0,0 +1,12 @@ +//go:build !cgo + +package main + +import ( + "errors" + "os" +) + +func checkSeedACL(_ *os.File) error { + return errors.New("-seed-file requires a cgo-enabled macOS build to check ACLs; refusing unchecked access") +} diff --git a/cmd/witnessd/seed_other.go b/cmd/witnessd/seed_other.go new file mode 100644 index 0000000..7e6972d --- /dev/null +++ b/cmd/witnessd/seed_other.go @@ -0,0 +1,12 @@ +//go:build !darwin && !linux + +package main + +import ( + "errors" + "os" +) + +func openSeedFile(_ string) (*os.File, error) { + return nil, errors.New("-seed-file permission checks are supported only on Linux and macOS; refusing unchecked access") +} diff --git a/cmd/witnessd/seed_startup_test.go b/cmd/witnessd/seed_startup_test.go new file mode 100644 index 0000000..e3ed2fe --- /dev/null +++ b/cmd/witnessd/seed_startup_test.go @@ -0,0 +1,139 @@ +package main + +import ( + "context" + "os" + "os/exec" + "path/filepath" + "runtime" + "strings" + "testing" + "time" +) + +const seedFileFlag = "-seed-file" +const keyLogPrefix = "witness key " +const daemonErrorPrefix = "witnessd:" + +const testSeed = "9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60" +const testPublicKey = "d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a" + +func seedDaemon(t *testing.T) string { + t.Helper() + binary := filepath.Join(t.TempDir(), "witnessd") + if runtime.GOOS == "windows" { + binary += ".exe" + } + if out, err := exec.Command("go", "build", "-o", binary, ".").CombinedOutput(); err != nil { + t.Fatalf("build: %v: %s", err, out) + } + return binary +} + +func startup(t *testing.T, binary string, args ...string) string { + t.Helper() + ctx, cancel := context.WithTimeout(context.Background(), time.Second) + defer cancel() + args = append([]string{"-relay", "http://127.0.0.1:1", "-intake", "127.0.0.1:0", "-interval", "1h"}, args...) + out, _ := exec.CommandContext(ctx, binary, args...).CombinedOutput() + return string(out) +} + +func writeSeed(t *testing.T, content string, mode os.FileMode) string { + t.Helper() + path := filepath.Join(t.TempDir(), "witness.seed") + if err := os.WriteFile(path, []byte(content), mode); err != nil { + t.Fatal(err) + } + return path +} + +// Catches ignored file input, unstable identity, and secret disclosure at startup. +func TestWitnessSeedFileIdentity(t *testing.T) { + if runtime.GOOS != "darwin" && runtime.GOOS != "linux" { + t.Skip("protected files supported on Linux and macOS") + } + binary := seedDaemon(t) + path := writeSeed(t, testSeed+"\n", 0600) + for i := 0; i < 2; i++ { + out := startup(t, binary, seedFileFlag, path) + if !strings.Contains(out, keyLogPrefix+testPublicKey) { + t.Fatalf("persistent identity missing: %s", out) + } + if strings.Contains(out, testSeed) || strings.Contains(out, "EPHEMERAL") { + t.Fatal("secret leaked or persistent input ignored") + } + } +} + +// Catches falling back to an ephemeral key after an invalid persistent input. +func TestWitnessSeedFileRejectsUnsafeInput(t *testing.T) { + binary := seedDaemon(t) + cases := []struct { + name, content string + mode os.FileMode + }{ + {"bad hex", strings.Repeat("z", 64), 0600}, + {"short", "ab", 0600}, + {"oversized", strings.Repeat("a", 4096), 0600}, + {"group readable", testSeed, 0640}, + {"world readable", testSeed, 0604}, + } + for _, tc := range cases { + t.Run(tc.name, func(t *testing.T) { + out := startup(t, binary, seedFileFlag, writeSeed(t, tc.content, tc.mode)) + if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) || strings.Contains(out, "EPHEMERAL") { + t.Fatalf("expected startup rejection: %s", out) + } + if strings.Contains(out, tc.content) { + t.Fatal("seed content leaked") + } + }) + } + for name, path := range map[string]string{"missing": filepath.Join(t.TempDir(), "absent"), "directory": t.TempDir()} { + t.Run(name, func(t *testing.T) { + out := startup(t, binary, seedFileFlag, path) + if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) { + t.Fatalf("expected rejection: %s", out) + } + }) + } +} + +func TestWitnessSeedFileRejectsSymlink(t *testing.T) { + if runtime.GOOS != "darwin" && runtime.GOOS != "linux" { + t.Skip("Unix symlink policy") + } + binary := seedDaemon(t) + path := writeSeed(t, testSeed, 0600) + link := filepath.Join(t.TempDir(), "link") + if err := os.Symlink(path, link); err != nil { + t.Fatal(err) + } + out := startup(t, binary, seedFileFlag, link) + if !strings.Contains(out, daemonErrorPrefix) || strings.Contains(out, keyLogPrefix) { + t.Fatalf("expected symlink rejection: %s", out) + } +} + +func TestWitnessSeedCompatibility(t *testing.T) { + binary := seedDaemon(t) + t.Run("legacy", func(t *testing.T) { + out := startup(t, binary, "-seed", testSeed) + if !strings.Contains(out, keyLogPrefix+testPublicKey) || !strings.Contains(out, "deprecated") || strings.Contains(out, testSeed) { + t.Fatalf("legacy migration behavior incorrect: %s", out) + } + }) + t.Run("demo", func(t *testing.T) { + out := startup(t, binary) + if !strings.Contains(out, "EPHEMERAL") || !strings.Contains(out, keyLogPrefix) { + t.Fatalf("demo key missing: %s", out) + } + }) + t.Run("conflict", func(t *testing.T) { + out := startup(t, binary, "-seed", testSeed, seedFileFlag, writeSeed(t, testSeed, 0600)) + if !strings.Contains(out, "mutually exclusive") || strings.Contains(out, testSeed) || strings.Contains(out, keyLogPrefix) { + t.Fatalf("conflicting options accepted: %s", out) + } + }) +} diff --git a/cmd/witnessd/seed_unix.go b/cmd/witnessd/seed_unix.go new file mode 100644 index 0000000..12533da --- /dev/null +++ b/cmd/witnessd/seed_unix.go @@ -0,0 +1,33 @@ +//go:build darwin || linux + +package main + +import ( + "errors" + "os" + "syscall" +) + +// Inspect the opened descriptor so permission checks and reads name the same +// file. Nonblocking/no-follow opens reject FIFOs and final-component symlinks. +func openSeedFile(path string) (*os.File, error) { + file, err := os.OpenFile(path, os.O_RDONLY|syscall.O_NOFOLLOW|syscall.O_NONBLOCK, 0) + if err != nil { + return nil, errors.New("cannot open -seed-file (regular file required; symlinks refused)") + } + info, err := file.Stat() + if err != nil || !info.Mode().IsRegular() || info.Mode().Perm()&0077 != 0 { + _ = file.Close() + return nil, errors.New("-seed-file must be a regular owner-only file (chmod 600)") + } + stat, ok := info.Sys().(*syscall.Stat_t) + if !ok || stat.Uid != uint32(os.Geteuid()) { + _ = file.Close() + return nil, errors.New("-seed-file must be owned by the current user") + } + if err := checkSeedACL(file); err != nil { + _ = file.Close() + return nil, err + } + return file, nil +} diff --git a/docs/witness-seed-files.md b/docs/witness-seed-files.md new file mode 100644 index 0000000..59b2dcb --- /dev/null +++ b/docs/witness-seed-files.md @@ -0,0 +1,13 @@ +# Persistent witness identity without secret command arguments + +Run `witnessd -seed-file /protected/path/witness.seed`. The file must contain exactly 64 hexadecimal digits encoding a 32-byte Ed25519 seed, optionally followed by LF or CRLF. Provision it through a protected editor or secret-management tool; never paste its contents into a shell command. Keep its directory protected as well. + +On Linux and macOS the file must be regular, owned by the effective user, and have no group or other permission bits (`chmod 600`). A read-only owner file (`400`) also works. Final-component symlinks and non-regular files are refused. Validation and bounded reading use the same opened descriptor. Files with malformed or oversized contents fail startup instead of generating a replacement identity. Diagnostics omit both seed contents and paths. + +Linux POSIX ACL grants are bounded by the group-class mode mask, which must be zero. On macOS, mode bits alone do not cover extended ACL grants: the daemon queries the native descriptor ACL and rejects any extended ACL. Remove unwanted grants with `chmod -N /protected/path/witness.seed` and recheck permissions. macOS protected loading requires a cgo-enabled build; a build without cgo fails closed. Other operating systems also refuse `-seed-file` until their access-control checks are implemented. No permission changes are made by the daemon. + +Loading the same file retains the same public witness identity across restarts. The public key can still appear in startup logs; seed bytes do not. + +`-seed` remains available for compatibility but prints a deprecation warning; migrate persistent deployments to `-seed-file`. There is no scheduled removal in this change. Passing both nonempty options is rejected. An explicitly empty `-seed-file` is also rejected. With neither option, the daemon retains its explicitly logged **EPHEMERAL** demo behavior. + +Persistent key identity does **not** persist rollback memory or filing records, repair witness amnesia, create federation, or establish a key registry. The existing trust-on-first-checkpoint and single-witness limitations remain.