diff --git a/DESIGN.md b/DESIGN.md index a95f9ac..2515aae 100644 --- a/DESIGN.md +++ b/DESIGN.md @@ -308,6 +308,46 @@ nodkey run --secret GH_TOKEN=github-token \ ended, these signals end the client again. The command sees pipes, not a terminal, so some programs print without colors or buffer their output. + + **What the command gets** (#191). In both forms it gets the same + argument list, the same environment with the fetched values, and the + same working directory. + - **`execve` (`--no-mask`, or stdout and stderr both a terminal):** + the command replaces nodkey in the same process. Its process ID is + the one that `nodkey run` had, and its parent is the caller of + `nodkey run`. It gets every file descriptor of nodkey that is not + close-on-exec: stdin, stdout, stderr and each descriptor that + nodkey inherited. Every signal goes to the command; its exit code + or its signal is the end of the run. + - **Masked (the default when stdout or stderr is not a terminal, or + `--mask`):** the command is a child of nodkey. Its parent is a + process named `nodkey` (the name in `/proc/PID/stat`), whose parent + is the caller. nodkey is not dumpable, so another process of the + same user without `CAP_SYS_PTRACE` cannot read its `/proc/PID/exe` + or its environment (root can). The command gets + nodkey's stdin; its stdout and stderr are two pipes to nodkey. It is + in the same process group and session as nodkey. nodkey makes no + other file descriptor for it, but it does not close inherited ones: + Go closes only close-on-exec descriptors, so a descriptor that the + caller passed to `nodkey run` (such as fd 3) reaches the command + too. nodkey passes `SIGTERM` and `SIGHUP` on; it catches `SIGINT` + and `SIGQUIT` and does not pass them on (a terminal sends them to + the whole process group). It passes no other signal on. The Go + runtime catches most of them and does nothing, so `SIGUSR1`, + `SIGUSR2` or `SIGALRM` reach neither nodkey nor the command. + `SIGSTOP`, `SIGTSTP`, `SIGTTIN` and `SIGTTOU` stop only nodkey, and + `SIGKILL` ends it. When nodkey dies of `SIGKILL`, the command goes + on running: its next write to stdout or stderr gets `SIGPIPE` (or + `EPIPE`), and a command that writes nothing runs on. The exit code is as + above: the command's code, the same signal for `SIGINT`, + `SIGTERM`, `SIGHUP` and `SIGKILL`, else 128 and the number. + - So a program that reads the output of `nodkey run` through a pipe + (a password command) gets `***` in place of the value, and a script + that checks that its parent is its caller sees `nodkey` in a masked + run. docs/setup.md, section 11, shows how to keep the mask on in + both cases. `--no-mask` is the last resort: with it, even a plain + `printenv` or a debug line shows the value (the mask stops only a + value printed as it is). 8. On deny, timeout or error, the client prints one line to stderr, without any value, and exits: with 77 when the broker denies the request, and with 69 when it cannot reach the broker or gets another answer diff --git a/docs/setup.md b/docs/setup.md index 112016f..c0d7acb 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1969,6 +1969,68 @@ terminal, and editors, `ssh` and prompts work. `--mask` masks also on a terminal. `--no-mask` turns masking off, for a value that is also a common word, for example: then normal output would show `***`. +#### Keep the mask on: password commands and wrappers + +Since nodkey 0.6.0, masking is the default whenever stdout or stderr is +not a terminal. Two kinds of setup need a change for it. Keep the mask +on in both: with `--no-mask`, even a plain `printenv` or a debug line +shows the value. (The mask only stops a value that is printed as it is, +not one in another form such as base64.) + +**A password command that prints the secret.** Some programs read a +password from a command, such as a mail client with +`password.cmd = "nodkey run --secret P=mail-read -- printenv P"`. The +program reads that output through a pipe, so with the mask it gets +`***`, and the login fails. Instead, run the program itself inside +`nodkey run`, and let its password command read the value from the +program's own environment: + +```sh +nodkey run --secret MAIL_READ=mail-read --reason "read the mail" -- mail-client sync +``` + +with `password.cmd = "printenv MAIL_READ"` in the program's config. The +value then goes only from the program to its own child. It never goes +through the output of `nodkey run`, and the output of the program to the +agent stays masked. A small wrapper script can choose the secrets for +each command: for example, a read-only secret for `sync` and a +send-only secret for `send`. Note: the program, and every process that +it starts, now has the value in its environment for as long as the +program runs, not only for one `printenv` +([THREAT-MODEL.md section 5](../THREAT-MODEL.md#5-what-nodkey-does-not-promise)). Keep such runs +short. + +**A wrapper that checks its parent.** With the mask, nodkey does not +replace itself with the command: it stays as the command's parent +([DESIGN.md section 5](../DESIGN.md#5-flow-secrets-for-one-command), "What +the command gets"). A script that checks that its parent is the process +that started `nodkey run` must accept a parent named `nodkey` and look +at that process's parent. nodkey is not dumpable, so `/proc/PID/exe` +cannot be read; read the name and the parent's process ID from +`/proc/PID/stat`: + +```sh +parent=$PPID +name=$(sed 's/^[0-9]* (\(.*\)) .*/\1/' "/proc/$parent/stat") +if [ "$name" = nodkey ]; then + parent=$(awk '{print $4}' "/proc/$parent/stat") +fi +``` + +A process name is not proof: any program of the same user can take the +name `nodkey`. Use this only where the parent check is a convenience, +not a security boundary. + +A masked command gets nodkey's stdin, and its stdout and stderr are +pipes to nodkey. nodkey opens no other file descriptor for it, but it +does not close the ones that it got: a descriptor that you pass to +`nodkey run`, such as fd 3, reaches the command too. + +**`--no-mask` is the last resort**, for a case that the two ways above +do not cover, or for a short value that is also a common word. It costs +the mask: the command replaces nodkey, and even a plain `printenv` or a +debug line of the command then shows the value. + `nodkey run` exits with the exit code of the command. When nodkey itself stops, its last line on stderr is `nodkey: (exit )`: 77 when the request was denied or @@ -2476,6 +2538,14 @@ what the client says: the broker allows and denies nothing because of it. A build from the source, such as one with the version `dev` or a commit, gets no warning and no notice. +**An update from nodkey 0.5.0 or older.** Since 0.6.0, `nodkey run` +masks the output by default when stdout or stderr is not a terminal, and +then it stays as the parent of the command. Before you update the agent +machines, check each `nodkey run` whose output another program reads, +such as a password command, and each script that checks its parent. +[Section 11, "Keep the mask on"](#keep-the-mask-on-password-commands-and-wrappers) +shows how to change them, with the mask still on. + ### New versions of bws and bw Install them in the same way as the first time