Skip to content
Go to file
Cannot retrieve contributors at this time
35 lines (19 sloc) 4.13 KB

Invite codes

What is an invite code?

An invite code is a short combination of numbers and words (e.g., 9-hamburger-chairlift, 1-forever-alone) that allows two computers to communicate safely with one another. By knowing and using the same shared "invite code," any two parties can quickly and easily establish a secure connection through which additional sensitive information (like passwords or other credentials) can be transmitted.

What are invite codes used for?

In Gridsync, invite codes are used as a means of securely transferring credentials to users (such as Tahoe-LAFS storage fURLs or the capabilities needed to join a magic-folder) without requiring users to handle or enter this information manually. Knowing and entering an invite code is thus typically sufficient – and is usually the only step required – to configure Gridsync "from scratch" after installation or to access a folder shared by another device or user.

Why use invite codes (instead of, e.g., passwords or email)?

Since invite codes are short, human-pronounceable, and comprised from a known list of phonetically distinct words, they are generally easier to memorize, communicate, and type than other forms of credententials (e.g., username/password combinations with specific requirements for length or complexity). Accordingly, the use of invite codes can help to drastically reduce the chances of user-error and subsequent frustration (e.g., from making typos, forgetting one's password and requiring a reset, and so forth).

In addition to the obvious usability improvements, because invite codes can only be used a single time before expiring, their usage helps to protect against certain classes of all-too-common attacks: when credentials are delivered over email, for example, your email provider necessarily gains access to that information (as does anybody else who might access your email account later on). By using invite codes to receive or exchange credentials in a more direct fashion, any such third parties are naturally excluded from knowing the content – or even the existence – of the information being exchanged.

How are invite codes secure?

As mentioned above, invite codes can only be used once before expiring. In addition, any code which is entered only partially correctly (e.g., typing in 7-pacific-candidate instead of the correct code of 7-pacific-capricorn) will become immediately invalidated at both ends, thereby preventing the subsequent exchange of sensitive information from occuring. Because of this, an attacker only has a single chance to correctly guess the full contents of any given invite code (realistically, a 1 in 65536 chance), as any failed attempts will notify both parties that the code has been invalidated.

Under the hood, the secure communication channels opened by the use of invite codes derive their security properties from the SPAKE2 cryptographic algorithm as implemented by Brian Warner's excellent magic-wormhole and python-spake2 libraries (upon which Gridsync depends). Any persons interested in learning more about the finer details of these libraries (and hence the security properties of Gridsync's "invite codes" themselves) are invited to read the accompanying documentation of both projects (or watch this video from Brian Warner's magic-wormhole presentation at PyCon 2016).

My invite code expired (or was invalidated by an attacker)! What do I do?

Because invite codes are one-time use and are generated by other parties (i.e., not the Gridsync project itself), you will need to contact the organization or person(s) that originally provided your invite code to request a new one in the event that yours expires. Usually storage service providers will have a contact address or some other method of getting in touch (e.g., a web form or "get new code" button) should you run into such issues.