From 03ec9e7a2aa7e577fdf96d14ba753aefbccd37c0 Mon Sep 17 00:00:00 2001 From: Joey Hess Date: Sun, 30 Apr 2017 20:16:51 -0400 Subject: add --- doc/faq.mdwn | 104 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 doc/faq.mdwn diff --git a/doc/faq.mdwn b/doc/faq.mdwn new file mode 100644 index 0000000..b819332 --- /dev/null +++ b/doc/faq.mdwn @@ -0,0 +1,104 @@ +[[!toc]] + +### 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, it will display +their Gnupg key, and the number of people who have signed it. It will +also list the names of some of those people (the best connected ones). + +If the developer of software you use is connecting to debug-me, +their software documentation might say what their Gnupg key is. Then you +can simply check that the Gnupg key ids match. + +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. +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 it's a gut call. If in doubt, don't let the developer connect. + +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. + +### 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. +* 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. + +#### 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. -- cgit v1.2.3