Permalink
Fetching contributors…
Cannot retrieve contributors at this time
38 lines (20 sloc) 4.33 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 currently used as a means for storage service providers to send required account-related information to users (such as the address or "introducer fURL" of a storage grid and other important configuration information) without requiring those users to 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.

In the future, invite codes will be used by Gridsync for additional purposes (like pairing account information to other devices and sharing files and folders between computers or other users).

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.