summaryrefslogtreecommitdiffhomepage
path: root/doc/faq.mdwn
blob: f559d87734c8996220a4faa54fe0e324aaf01fa1 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
[[!meta title="debug-me Frequently Asked Questions"]]

[[!toc levels=2]]

### For Users

#### Should I let John Doe connect to my debug-me session? I don't know that guy.

When a developer connects to your debug-me session, debug-me will display
their GnuPG key, and information about it, including
the number of people who have signed it. It will also list the names
of some of those people (the best connected ones).

Suppose you're using Debian, and debug-me says "John Doe is a Debian
developer". Then it's probably safe to let this person connect,
because you already trust this guy implicitly, since you're using software
he develops.

How does debug-me know that John Doe is a Debian developer? It's checked
that his gpg key is in the keyring at
`/usr/share/debug-me/keyring/a_Debian_developer.gpg`, which is provided by
Debian. Other software projects that are installed on your computer can
also put keyrings in that directory, and then debug-me will be able to
tell then a developer of a project is connecting.

If debug-me says that "John Doe is probably a real person", it means
that he's connected to the strong set of the GnuPG web of trust. That
means: Other people, who certianly are real, have verified his identity.
So even if you don't know his name, it can be safe to let him connect,
but if in doubt, don't let him.

If debug-me says "identity cannot be verified!", it means that the GnuPG
key couldn't be downloaded at all, or the developer is not connected to the
strong set of the GnuPG web of trust. Be super wary in this case.

#### I don't feel comfortable letting someone run commands on my computer. Can I still use debug-me?

You can, just answer "n" when it asks if you want to let a developer
run commands. The developer who connected to your debug-me session will
still be able to see what you do in the session, so you can show them
what they need to see to understand the bug.

This is less efficient though. The developer will have to explain to you
what to do, instead of just doing it. It will probably be harder for them
to quickly get a grasp of the problem.

Also, this can be less secure than letting the developer type stuff!
Consider: The developer could ask you to run some complex command you've
never heard of. Maybe that command will do something bad. Then there's
no proof that the developer tricked you into doing that. If you use
debug-me to let them type, there would be a proof of anything bad they did.

#### How does debug-me prove when the developer uses it to do something bad?

The debug-me session log file records everything the developer saw and did
in a debug-me session. Each keystroke they sent is signed with their GnuPG
key, and is part of a signed chain of activities. By examining this
evidence, it can be cryptographically proven that the developer did what
they did.

For this to work, you have to have a copy of the session log file. This is
why the debug-me server will email it to you at the end of the session, to
make sure you get a copy.

To verify a session log file, run: `debug-me --verify debug-me.log`
That will display the gpg key of the developer who was active in
that session, and verify the integrety of the log file.

A debug-me log file can be replayed by running: `debug-me --reply debug-me.log`

### For Developers

#### What do I need to do to start using debug-me?

Here's a quick checklist:

* Make a GnuPG key, if you don't already have one.
* Get it signed by at least one person who's connected to the strong
  set of the GnuPG web of trust. The more signatures the better.
  Keysigning parties are great.
* Include your GnuPG key id in your project's documentation, so users
  will know which key is yours. It also helps to sign git tags,
  tarballs, git commits, etc with your key.
* Make your software package install a gpg keyring of its developers to
  /usr/share/debug-me/keyring/.
  
  A file there named "a_Foo_developer.gpg"
  will make debug-me tell the user that "Your Name is a Foo developer." 
  when you connect to their debug-me session, and so the user will be more
  likely to trust you and let you connect.

  For example:
  
  	gpg --export-options export-minimal --export C910D9222512E3C7 > a_Foo_developer.gpg

* When a user has a bug that you need more information to reproduce and
  understand, ask if they'll use debug-me.

#### What should I do and not do in a debug-me session?

You're a guest in the user's computer, and your every move is being
recorded as evidence. Act acordingly. Ask for permission, not forgiveness.

Avoid looking at personal files unncessarily, and ask permission if you
need to in order to investigate the bug.

Never delete or modify their personal files. 

Don't download software. Don't try to sudo to root, etc.

Don't share the log of your debug-me session without getting the user's
approval, as it might contain information they wish to remain private.

#### Seems some of my keystrokes are not getting through to the user?

Due to the way debug-me's proof chains work ([[details|protocol]]), this
will sometimes happen, when you are typing faster than the roundtrip latency
to the user. debug-me will beep when this happens (but a lot of modern
terminal emulators don't sound beeps).

This shouldn't be a problem, even at high latency, when you're typing
at the shell prompt, but it may make using editors etc hard when latency
is high.

If a keystroke doesn't get though, wait a second and try it again,
then it generally will.

#### Any other terminal related problems I might encounter?

If you're going to edit a file, etc it helps to have your terminal set to
the same (or larger) number of lines and columns as the user's terminal.
Run `echo $LINES $COLUMNS` in their shell to find the values there.

It can sometimes be useful to `export TERM=vt100` in the user's shell
to avoid any differences in terminal emulation.