Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
40 changes: 40 additions & 0 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
70 changes: 70 additions & 0 deletions docs/setup.md
Original file line number Diff line number Diff line change
Expand Up @@ -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: <reason> (exit <code>)`: 77 when the request was denied or
Expand Down Expand Up @@ -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
Expand Down
Loading