How exactly does bytejail work?

Jails, identities, connection files - sounds complicated, but it's not!


We define the term identity as a cryptographic key pair generated locally in the bytejail client.
This key pair consists of a private and a public key.

Basic Concepts

  • Persons in possession of the public key can lock something (encrypt).
  • Persons in possession of the private key can unlock something (decrypt).
You as the customer have both the private and the public key.
This procedure is termed an asymmetric encryption system or Public-key cryptography [Wikipedia] and in our case enables us to encrypt something only you (the customer) are then able to decrypt.

Generating the Key Pair

A key pair is derived from two freely selectable inputs of the customers.
The input fields, which serve as a basis for the computation, are designated key password 1 and key password 2.

Any text character from the UTF-8 character set is allowed as input. Example: あ, ょ, ㇴ, |, ², %, A, ä, #, (space)
A maximum length of 1024 characters applies to both fields.

As a rule, it is best to use a password manager, for example, KeePass [http], to generate and save the passwords.
A password manager makes it easy to use long and complex passwords without having to remember them.

Meaningful input (summarized):

  • Long passwords generated and saved using a password manager
  • Sentences split across both input fields
  • Email address and password as additional input
  Important: In any case, make sure that you do not lose or forget your passwords!
Since only you have knowledge about the defined passwords, a bytejail recovery is not possible!

With the help of the open source (MIT) library NaclKeys, the actual computation is carried out.

At the end of the computation, you will receive your public key (encoded as a Base58 string) and can now store this key in the bytejail console.
With the stored public key, bytejail can now encrypt your jails and connection files asymmetrically.

The identity data must be entered again with each connection from the bytejail client. The bytejail client re-calculates your private key from the input data to decrypt the connection and then establishes a connection.

Examples for Key Password
Key password 1: Franz jagt im komplett verwahrlosten Taxi quer durch Bayern.
Key password 2: d16bfee7cc0d3f28090d0f0557efc08abef847a8995ba327298772cf874fd39b

Yields: 2PzYqs39t1PH42iY8y2A5gpTptueKyzpxEjo7JSmAH1gcUfmrZZ (public key will be stored in the bytejail console)

Key password 1: 4ËââÁ87"¶7DÑ×eÖt@ðµæ(20ÀbÏÙ±1dËJ!¹¬æ<û$@¯`ì`*q÷bx¨Þð:é%ð:úu{
Key password 2: .-ÇGjjÏzT? ÖÌáC˹¹ÐÐEÈà2Os^#^^äDzøR»+Z@é7èócZz¼ìlÀÁÿ¹M)ýUý,ò

Yields: 2NwtskxFhhDW6er7Q4VCWz8MwpoJ9heVKMC2uRFDZSEv8yMCEbc (public key will be stored in the bytejail console)

Key password 1: [email protected]
Key password 2: v5UN@9Ch@*z+X@^VN43E3M p1

Yields: 2PCzZqjnGCifhoawgATzp4pc1brvv8TrZLTGTNymCw7Df5jcVNz (public key will be stored in the bytejail console)

Using the public key, an asymmetrically encrypted connection file is created when creating a jail, which can be opened again only by knowledge of both key password.

FAQ: Generating an Identity

Connection Files

What are connection files?
When creating a jail in the bytejail console with a previously stored identity, this is applied to the bytejail servers.

Several processes are triggered here in the background (simplified process):

  1. Storage space with a unique address is reserved at the chosen location
  2. The created address is repeatedly asymmetrically encrypted (2-person rule)
  3. A client certificate is generated for subsequent authentication with the bytejail system
  4. Signatures are generated to authenticate the server connection
  5. All information is summarized in an encrypted connection file (only accessible by the customer)
  6. A minisign signature is generated for the connection file previously encrypted
  7. The connection file and the associated signature are made available to the customer for download in the bytejail console

Generated connection files are stored by bytejail and can be downloaded again at any time from the bytejail console.
As a rule, a connection file can only be opened/decrypted using a private key, which means the key passwords must be known.
This means a connection file does not have to be kept secret and can be stored anywhere.

bytejail cannot read/decrypt connection files.

Library used for the encryption: StreamCryptor

Details about the 2-Person Rule

As mentioned previously, store space with a unique address is reserved when creating a jail.
Without the knowledge of this address, it is impossible (by bytejail) to determine which jail or which jail contents belong to which customer.

Since the address is asymmetrically encrypted repeatedly, multiple private keys and signatures are required for the decryption.

Some of the required information is stored by bytejail; the remaining information can be found in the connection file of the customer. Once both parts are in place, the unique address can be reconstructed, enabling access to the jail.

By using this process and splitting up information, bytejail guarantees information is protected and access is impossible by unauthorized (third) parties.


Data in Jails
In the bytejail universe, all of the data you transfer to bytejail from your local hard drive is stored in so-called jails..

As a general rule: All files and filenames are end-to-end locally encrypted on your system, removing META data, before being transmitted (uploaded).

This means unencrypted data will never leave your computer!
Local Encryption

To ensure safe and modern end-to-end encryption, bytejail relies on modern cryptography. Even if AES is still considered extremely secure, bytejail decided not to use this algorithm and instead employ libsodium-based encryption. The open source (MIT) library StreamCryptor thus was established during the planning and development of bytejail. StreamCryptor can be used freely and is publicly available for everyone. A security audit was performed by the company Cure53 from Berlin as well, which is also accessible by the public (English).

Uploading Local Data to a Jail

If you use the bytejail client to upload files to a jail, each of these files is encrypted locally end to-end before the upload. After the encryption of file and file name, the file is transferred to the bytejail server via a TLS 1.2 secured channel.

We use several Tahoe-LAFS grids as storage technology at all locations.

The Advantages of Tahoe-LAFS:

  • Decentralized storage of data (reliability)
  • Built-in Erasure coding [Wikipedia] (automatic recovery of corrupted file parts)
  • Extremely high level of data protection
Library used for local encryption: StreamCryptor

Downloading Data from a Jail

All files are listed in the bytejail client with your original unencrypted file name.
After a connection is successfully established, the bytejail client calls a list of the end-to-end encrypted files contained in the jail and decrypts them locally so that they are readable for the user in the bytejail client.

If the user decides to download a file to his or her local system, the bytejail client requests this file with the encrypted file name.
After successfully downloading the file, it is decrypted locally and is available to the user for further use.

Removing Data from a Jail

  Deleting or removing data from a jail is final. Deleted data cannot be recovered.