Document the "bin/auth revoke" tool

Summary: Depends on D18910. Ref T13043. Provides reasonable user-facing documentation about the general role and utility of this tool.

Test Plan: Read document.

Reviewers: amckinley

Reviewed By: amckinley

Maniphest Tasks: T13043

Differential Revision: https://secure.phabricator.com/D18911

src/docs/user/field/revoking_credentials.diviner

@@ -0,0 +1,101 @@
+@title Revoking Credentials
+@group fieldmanual
+
+Revoking credentials, tokens, and sessions.
+
+Overview
+========
+
+If you've become aware of a security breach that affects you, you may want to
+revoke or cycle credentials in case anything was leaked.
+
+You can revoke credentials with the `bin/auth revoke` tool. This document
+describes how to use the tool and how revocation works.
+
+
+bin/auth revoke
+===============
+
+The `bin/auth revoke` tool revokes specified sets of credentials from
+specified targets. For example, if you believe `@alice` may have had her SSH
+key compromised, you can revoke her keys like this:
+
+```
+phabricator/ $ ./bin/auth revoke --type ssh --from @alice
+```
+
+The flag `--everything` revokes all credential types.
+
+The flag `--everywhere` revokes credentials from all objects. For most
+credential types this means "all users", but some credentials (like SSH keys)
+can also be associated with other kinds of objects.
+
+Note that revocation can be disruptive (users must choose new passwords,
+generate new API tokens, configure new SSH keys, etc) and can not be easily
+undone if you perform an excessively broad revocation.
+
+You can use the `--list` flag to get a list of available credential types
+which can be revoked. This includes upstream credential types, and may include
+third-party credential types if you have extensions installed.
+
+To list all revokable credential types:
+
+```
+phabricator/ $ ./bin/auth revoke --list
+```
+
+To get details about exactly how a specific revoker works:
+
+```
+phabricator/ $ ./bin/auth revoke --list --type ssh
+```
+
+
+Revocation vs Removal
+=====================
+
+Generally, `bin/auth revoke` **revokes** credentials, rather than just deleting
+or removing them. That is, the credentials are moved to a permanent revocation
+list of invalid credentials.
+
+For example, revoking an SSH key prevents users from adding that key back to
+their account: they must generate and add a new, unique key. Likewise, revoked
+passwords can not be reused.
+
+Although it is technically possible to reinstate credentials by removing them
+from revocation lists, there are no tools available for this and you should
+treat revocation lists as permanent.
+
+
+Scenarios
+=========
+
+**Network Compromise**: If you believe you may have been affected by a network
+compromise (where an attacker may have observed data transmitted over the
+network), you should revoke the `password`, `conduit`, `session`, and
+`temporary` credentials for all users. This will revoke all credentials which
+are normally sent over the network.
+
+You can revoke these credentials by running these commands:
+
+```
+phabricator/ $ ./bin/auth revoke --type password --everywhere
+phabricator/ $ ./bin/auth revoke --type conduit --everywhere
+phabricator/ $ ./bin/auth revoke --type session --everywhere
+phabricator/ $ ./bin/auth revoke --type temporary --everywhere
+```
+
+Depending on the nature of the compromise you may also consider revoking `ssh`
+credentials, although these are usually not sent over the network because
+they are asymmetric.
+
+**User Compromise**: If you believe a user's credentials have been compromised
+(for example, maybe they lost a phone or laptop) you should revoke
+`--everything` from their account. This will revoke all of their outstanding
+credentials without affecting other users.
+
+You can revoke all credentials for a user by running this command:
+
+```
+phabricator/ $ ./bin/auth revoke --everything --from @alice
+```