Page MenuHomePhabricator
Files F14756066

D18911.id45329.diff
No OneTemporary
Actions

D18911.id45329.diff
View Options

diff --git a/src/docs/user/field/revoking_credentials.diviner b/src/docs/user/field/revoking_credentials.diviner
new file mode 100644
--- /dev/null
+++ b/src/docs/user/field/revoking_credentials.diviner
@@ -0,0 +1,92 @@
+@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 extension installed.
+
+
+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 removal is technically possible, there is no toolset available for
+removing credentials from revocation lists.
+
+
+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 may want to revoke the `password`, `conduit`, `session`, and
+`temporary` credentials for all users. This will revoke all credentials which
+are normally sent over the network.
+
+Depending on the nature of the compromise you may consider revoking `ssh`
+credentials, although these are usually not sent over the network because
+they are asymmetric.
+
+You might do this with 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
+```
+
+**User Compromise**: If you believe a user may have been affected by a
+compromise (for example, maybe they lost a phone or laptop) you may want to
+revoke `--everything` from their account. This will revoke all of their
+outstanding credentials without affecting other users.
+
+You might do this with this command:
+
+```
+phabricator/ $ ./bin/auth revoke --everything --from @alice
+```
+
+**I Am The Law**: If you want to impress users with your powerful security
+policy, routinely revoke `--everything --everywhere` to keep everyone on their
+toes.

File Metadata

Mime Type
text/plain
Expires
Wed, Jan 22, 7:05 PM (2 h, 5 m)
Storage Engine
blob
Storage Format
Encrypted (AES-256-CBC)
Storage Handle
7035142
Default Alt Text
D18911.id45329.diff (3 KB)

Event Timeline

Phabricator · Built by Phacility