Developing on the BitTorrent Sync API? Our developer evangelist is here to work with you.
The most common question I field from developers building on the Sync API involves the various types of keys you can generate and how they differ. Keys were formerly called “Secrets”. Today, we take a closer look at this topic.
Let’s start with the basics. Keys are Sync’s way of connecting different devices and joining them together. You’ll first encounter a key when adding a new folder in BitTorrent Sync.
The key is randomly generated to ensure its uniqueness and is generally safer than the traditional login/password combination, where some users will invariably use a permutation of their name, pet’s name, birthdate, etc. – a combination that a good dictionary file or Rainbow Tables can compromise. These user-chosen credentials essentially provide a false sense of security. Sync gets a stream of bytes from the random number generator on your device, which are then converted into an alphanumeric format (33 characters in length) to create the folder’s key (e.g. BJKEDO89DK8EJG3KD7GID35KDOBY70DK2 – note that this and all subsequent keys are not working keys).
So how does Sync ingest these keys? When the client reads in a key, it looks at the first character to determine what type of key it is dealing with and how to proceed. The data used by Sync is comprised of everything following the first character.
Initially, keys were creating according to this pattern:
The examples below intentionally use the same letter for demonstration purposes.
Read/Write keys begin with A
Example: AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA
Read Only keys begin with B
Example: BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB
One-Time keys begin with C
Example: CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
After adding encryption support, we added:
Read/Write keys begin with D
Example: DDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDDD
Read Only keys begin with E
Example: EFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFZZZZZZZZZZZZZZZZZZZZZZZZZZ
Encrypted Read Only keys begin with F
Example: FFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFFF
One-Time keys begin with C (no change)
Example: CCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCCC
Note: Keys with encryption support are only available through the developer API.
Do you see a pattern/similarity between any of those keys? Curious about why the Encrypted Read Only key is almost the same as the first half of the Read Only key? Here’s how that works:
Encrypted Read Only key + Unlock Key = Read Only key FWX2ZZNRTHKJOFAZ6WY7SSOHZUF4WRGRD + 6627O7M6NXN6T2WAL5ZO2VVKKI = EWX2ZZNRTHKJOFAZ6WY7SSOHZUF4WRGRD6627O7M6NXN6T2WAL5ZO2VVKKI
This ‘unlock key’ consists of the last 26 characters of the Read Only key – denoted with Z’s above.
With both the Read Only and Encrypted keys, peers are always handling encrypted versions of the files – the difference is that the Read Only peers are able to decrypt the files because they have the requisite token for decryption. Encrypted keys don’t have this unlock token.
One-Time keys are a bit more interesting. The process for using a One-Time key looks like this:
- Client generates a One-Time use key
- User then sends the key off to the recipient
- Recipient’s client discovers the host client using the key
- The two peers set up a secure channel
- Host client sends over the real Read/Write or Read-Only key through that channel
One-Time keys therefore aren’t tied cryptographically in any way to the Read/Write, Read-Only or Encrypted keys – they simply act as the “token” that can be redeemed for one of the real keys. This is why it is necessary for the host to be online.
This should be a good overview of the different types of keys in the Sync ecosystem. What questions do you have about keys and how they work? What Sync technologies would you like to see covered next? Let us know in the comments section!
