Skip to content
Draft
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
39 changes: 35 additions & 4 deletions DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ One static Go binary holds all parts. The subcommand picks the role:
| `nodkey run` | agent machine | Get secrets, then start one command with them. |
| `nodkey ssh-agent` | agent machine | Serve an SSH agent socket. Send each signature request to the broker. |
| `nodkey ssh-grant` | agent machine | Ask once for SSH logins to a list of hosts for N minutes (see [decision 4](#13-decision-4-ssh-approval-scope)). |
| `nodkey try` | one machine | A trial with fake secrets and approval in its own terminal, for a first look. It is not a setup (section 15). |
| `nodkey try` | one machine | A trial with fake secrets and approval in its own terminal, or with `--telegram` on the phone, for a first look. It is not a setup (section 15). |
| `nodkey keygen` | both | Make a TLS key pair for the broker or a client. Print its pin. |
| `nodkey audit verify` | trusted machine | Check the hash chain of an audit log. |
| `nodkey update` | both, as root | Install a release in place of this binary, with the install script that is built into it (section 18). |
Expand All @@ -108,7 +108,9 @@ One static Go binary holds all parts. The subcommand picks the role:

`nodkey try` runs the real broker parts on `127.0.0.1` of one machine,
but with its own approver (the terminal) and its own store (three fake
values). Both live only in the code of `nodkey try`. `nodkey broker`
values). Both live only in the code of `nodkey try`. With `--telegram`
it uses the Telegram approver instead, with a new bot that the person
makes for the trial. `nodkey broker`
cannot use them: no flag, config key or variable turns them on
(THREAT-MODEL.md, T38).

Expand Down Expand Up @@ -3346,7 +3348,7 @@ nodkey preapprove --secret NAME... (--daily HH:MM-HH:MM | --weekly DAYS HH:MM-HH
nodkey preapprove --cancel ID
nodkey preapprove --login ITEM --url URL [--reason TEXT]
nodkey agent-browser-plugin
nodkey try
nodkey try [--telegram]
nodkey try run [--secret VAR=NAME]... [--reason TEXT] -- COMMAND [ARGS...]
nodkey keygen --out FILE
nodkey audit verify FILE [--anchor SEQ:HASH]... [--anchors FILE|-]
Expand Down Expand Up @@ -3771,7 +3773,8 @@ credentials. Its one client is `try-client`.
Its one store holds three secrets, `demo-token`, `demo-password` and
`demo-api-key`, with random values that start with `TRY-`, made at the
start. Their rule is `ask = "window"` with a 5 minute window. It has no
SSH keys, no Telegram and no check for a newer release.
SSH keys and no check for a newer release. Without `--telegram` it has
no Telegram.

nodkey try shows each request in its own terminal, with the lines of the
message and the choices: `1` Approve once, `2` Approve 5 min, `3` Deny.
Expand All @@ -3786,6 +3789,34 @@ SIGQUIT stops the trial with exit code 0: it ends the parts in the order of
`nodkey broker`, removes the directory, and prints what a real setup
adds, with a pointer to docs/setup.md.

With `--telegram`, the requests go to Telegram instead of the terminal,
before the directory is made:

1. When a trial runs already, nodkey try stops with exit code 1: a
second poller would stop the first trial. Then it asks the person to
make a new bot with @BotFather, never the bot of a real broker, and to
paste its token. When stdin is a
terminal, its echo is off while the token is typed. The token is kept
only in memory, never in a file or a log.
2. It calls `getMe` for the bot's user name, makes a random code (16
bytes, base64url), and prints the link `https://t.me/BOT?start=CODE`.
3. It polls the bot until the message `/start CODE` comes in a private
chat with its sender. Every other message is skipped. The sender's
user ID becomes the one approver and the notice chat. No one has to
look up the ID with `getUpdates`.
4. It shows the sender's name and ID, and starts only when the person
types `yes`.

Then the trial runs as above, but with the Telegram approver of
`nodkey broker`: the same messages and buttons, with `TRY MODE · ` before
the text of every message and every edit. The terminal shows only the
intro and the notices. When Telegram answers a poll with a conflict
(another program polls the bot, such as a real broker), nodkey try stops
with exit code 1 and says to use a new bot. A token that Telegram does
not accept stops it with 1 too. A signal during the setup stops it with
exit code 0; nothing was made. `Options.Prefix` of the Telegram approver
is at most 32 characters, and every message keeps room for it.

`nodkey try run` is `nodkey run` with the client config of the trial,
`client.toml` in that directory. It never reads
`~/.config/nodkey/client.toml`. In `nodkey try run`, each line that nodkey
Expand Down
5 changes: 5 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -120,6 +120,11 @@ command. So you read the command before you tap.
Press Ctrl-C in the first terminal to end the trial; it removes its
files.

To answer on your phone instead, run `nodkey try --telegram`. It asks you
to make a new bot with @BotFather (never the bot of a real broker), to
paste its token, and to open a link on your phone. Then each request
comes to Telegram, with `TRY MODE` on each message.

Try mode is not a setup. The agent could type the answer in that
terminal, so the trial has only fake values (they start with `TRY-`) and
can never reach a real secret. A real setup adds a separate broker host,
Expand Down
24 changes: 22 additions & 2 deletions THREAT-MODEL.md
Original file line number Diff line number Diff line change
Expand Up @@ -1296,7 +1296,8 @@ must never take answers from a terminal.
made in memory, with one store that has no type, so no `[store.*]`
section can name it, and `store.New` cannot make it. It never starts
`bws` or `bw`. Its only values are random, made at the start, and start
with `TRY-`. It has no SSH key and no bot token.
with `TRY-`. It has no SSH key. Only with `--telegram` does it have a
bot token, which the person types and which stays in memory.
- `nodkey try run` reads only the client config of the trial, never
`~/.config/nodkey/client.toml`, and it pins the trial's broker key. So
it cannot send a request to a real broker by mistake, and a real
Expand All @@ -1307,8 +1308,27 @@ must never take answers from a terminal.
`nodkey try run` prints starts with `TRY MODE`, so a person does not take
the trial for a setup. The trial allows no scheduled and no standing grant.

- With `--telegram`, the token is typed on this machine, which may be an
agent machine (docs/setup.md, "Where you do the setup"). The guide and
the prompt say: make a new bot for the trial, never use the broker's
bot. If the broker's bot is used anyway, both poll, and Telegram
answers one of them with a conflict: either the real broker stops with
exit code 76 (T6), or nodkey try stops and says to use a new bot. While
both poll, the trial can take button presses meant for the broker;
those requests get no answer and are denied, and the trial removes the
buttons of the broker's message. A second trial checks first that no
trial runs, so it does not poll the bot of the first one. If the
broker's token was pasted, the agent may now have it: with it, it can
poll the bot and stop the broker, or send messages that look like the
broker's (T6). Make a new token (docs/setup.md section 13, "A new bot
token"). The approver's
user ID comes only from the `/start CODE` message with a random code,
and the person must confirm the name.

Risk that remains: the agent on the same machine can answer a request of
the trial, or read its fake values. That is fine: they open nothing. A
the trial, or read its fake values. With `--telegram`, it can also read
the token of the trial's bot from the terminal or the memory of the
process; that bot opens nothing, and the person can delete it. That is fine: they open nothing. A
person who copies the trial's way of working to a real setup loses the
phone. The last lines of `nodkey try` and the guides say what a real setup
adds: a separate broker host, a store, Telegram and the rules.
Expand Down
24 changes: 24 additions & 0 deletions cmd/nodkey/brokerfake_linux_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,8 @@ func (f *fakeTelegram) ServeHTTP(w http.ResponseWriter, r *http.Request) {
writeTelegram(w, http.StatusOK, message(p.MessageID))
case "answerCallbackQuery":
writeTelegram(w, http.StatusOK, `{"ok":true,"result":true}`)
case "getMe":
writeTelegram(w, http.StatusOK, `{"ok":true,"result":{"id":1,"is_bot":true,"username":"try_test_bot"}}`)
default:
writeTelegram(w, http.StatusNotFound, `{"ok":false,"error_code":404,"description":"Not Found"}`)
}
Expand Down Expand Up @@ -609,6 +611,28 @@ func (f *fakeTelegram) tap(msgID int64, data string) string {
return id
}

// sendStart queues the message "/start code" from the approver, in a
// private chat with the bot.
func (f *fakeTelegram) sendStart(code string) {
f.t.Helper()
f.mu.Lock()
defer f.mu.Unlock()
f.nextUpdate++
raw, err := json.Marshal(map[string]any{
"update_id": f.nextUpdate,
"message": map[string]any{
"message_id": 1, "date": 1, "text": "/start " + code,
"chat": map[string]any{"id": approverID, "type": "private"},
"from": map[string]any{"id": approverID, "is_bot": false, "first_name": "Test", "username": "test_user"},
},
})
if err != nil {
f.t.Fatal(err)
}
f.updates = append(f.updates, tgUpdate{id: f.nextUpdate, raw: raw})
f.notifyLocked()
}

// waitTapAnswer waits for the answer to the press id
// (answerCallbackQuery), and returns the text that the phone shows.
func (f *fakeTelegram) waitTapAnswer(id string) string {
Expand Down
34 changes: 34 additions & 0 deletions cmd/nodkey/terminal_linux.go
Original file line number Diff line number Diff line change
Expand Up @@ -30,3 +30,37 @@ func isTerminal(w io.Writer) bool {
}
return terminal
}

// echoOff turns off the echo of the terminal f, so that what the person
// types is not shown. restore turns it back on. It fails when f is not a
// terminal.
func echoOff(f *os.File) (restore func(), err error) {
rc, err := f.SyscallConn()
if err != nil {
return nil, err
}
var old syscall.Termios
var errno syscall.Errno
if err := rc.Control(func(fd uintptr) {
//nolint:gosec // G103: TCGETS writes a Termios, and the pointer lives only in this call.
_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, fd, syscall.TCGETS, uintptr(unsafe.Pointer(&old)))
if errno != 0 {
return
}
t := old
t.Lflag &^= syscall.ECHO
//nolint:gosec // G103: TCSETS reads a Termios, and the pointer lives only in this call.
_, _, errno = syscall.Syscall(syscall.SYS_IOCTL, fd, syscall.TCSETS, uintptr(unsafe.Pointer(&t)))
}); err != nil {
return nil, err
}
if errno != 0 {
return nil, errno
}
return func() {
_ = rc.Control(func(fd uintptr) {
//nolint:gosec // G103: TCSETS reads a Termios, and the pointer lives only in this call.
_, _, _ = syscall.Syscall(syscall.SYS_IOCTL, fd, syscall.TCSETS, uintptr(unsafe.Pointer(&old)))
})
}, nil
}
9 changes: 8 additions & 1 deletion cmd/nodkey/terminal_other.go
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,15 @@

package main

import "io"
import (
"errors"
"io"
"os"
)

// isTerminal reports false: nodkey version 1 runs on Linux only, so
// nodkey version asks GitHub only there.
func isTerminal(io.Writer) bool { return false }

// echoOff fails: hidden input needs Linux.
func echoOff(*os.File) (func(), error) { return nil, errors.New("hidden input works only on Linux") }
Loading
Loading