Team Invites and TOFU

Overview, proof-based invites

A team invite is a signed statement ¹ in a team sigchain saying that a user presenting a specific proof should be added to the team. After a Keybase user sets the particular proof up, team admin's client will be notified and it can process the invite during background operations.

The following invite types are available:

• Social networks with built-in proof support: Twitter, Reddit, Hacker News, Github.
• Social networks that integrate with Keybase.
• Seitan Tokens: invites based by EdDSA keypairs.
• HTTPS and DNS proofs.
• PGP key proofs.

The invites above are not TOFU ("Trust On First Use"). The Keybase client only gets a "hint" from the server, that invite X may be resolved by adding user Y. The client then verifies that information by checking the proof ².

You can take a peek into how it works by using the id ("identify") CLI command. For example, if the server said user max is an owner of maxtaco@twitter account and therefore should be added to your team, your client will do something similar to:

$ keybase id max+maxtaco@twitter
▶ INFO Identifying max
✔ public key fingerprint: 8EFB E2E4 DD56 B352 7363 4E8F 6052 B2AD 31A6 631C
... // NOTE: Some proofs and keys are omitted in this example.
✔ "maxtaco" on twitter: https://twitter.com/maxtaco/status/433688676975927296
...

✔ "maxtaco" on twitter means that the client has locally checked and verified the Twitter proof that exists in maxtaco on Twitter's tweet. It did not just take the server's word for it.

"Trust On First Use" (TOFU) invites

However, there are two types of invites that Keybase chooses to support because they are convenient for users, with certain security trade-offs: phone number invites and email address invites. There is no feasible way of doing phone number or email proofs that would be verifiable by the clients. Hence when creating an @phone or @email invite, you are trusting Keybase's server to give you the right user when it tells you how to resolve the invite.

After that invite is resolved, it is set in stone (signed in sigchain). That is, the Keybase server cannot "swap" the user for someone else. Nor can it give you another user to add, because the team invites described here are always one time use. This single-use property is also enforced by the sigchain reader in the Keybase client.

The global Merkle tree ensures that only your Keybase username has to be exchanged out-of-band in order to be sure you are talking to the right person.

Phone numbers and email invites are processed automatically when a user who added the phone number or email address has both:

• verified it: using a code sent by Keybase via SMS for phone number, or link inside of an email message for email,
• and marked it searchable.

Phone numbers and email addresses that are not searchable will not be automatically resolved for team invites (or new chats). They will only be used for things like security notifications. We have also described privacy considerations regarding adding phone numbers and email addresses here

With email invites, there is also an additional method of accepting the invite, other than adding and verifying the email address: Keybase will also send a one-time code to that address. By using that code you let the server know that it is you who is the recipient of email invite, and the server then notifies one of team admins' client. Server-trust email invite tokens were introduced to Keybase when teams were first implemented, and we continue to support this method for now. Note that the code is one-time use, and is also expired if the email invite is resolved using "add + verify + make searchable" mechanism described above.

Footnotes

1. See an example of "team invite" sigchain link.
2. Client-side go code of invite handler and checker.