I have mentioned my new app for adding zero-knowledge encryption to file sharing services that don’t have it natively in this and this other post. Right now I have a group of alpha testers uncovering bugs, and the first one coming in is that the instructions on the app itself are rather terse. This post hopefully will help users as well as group administrators.
The GroupEncrypt page is intentionally terse to avoid cluttering the interface with text. In other apps, I have added a button to open a full help page, but this time I thought the process would be so simple that this would not be necessary. It appears I was overly optimistic and I may still have to add a decent help page. In the meantime, this post might serve the purpose. It contains instructions both for a regular user and for a group Administrator.
Regular User Instructions
When the app loads, you’ll see some step 1 instructions and a box to enter a Password. Come up with a good one and enter it by clicking the Accept button or pressing the Enter key. The app will help you to make a good Password by displaying a score right above it, made by measuring its informational entropy, including a dictionary of the fifty thousand most common English words. You may want to stop for a second before submitting your Password to give time for a short “Hashili” word to appear right below the score. This word is meant as a reassurance that you have typed your Password correctly, even though it is not visible (there is an eye icon within the box, to toggle its visibility). You may want to write down the Hashili word to help you later if you have trouble remembering your Password exactly. If you forget the Password, the app won’t let you move beyond this screen.
You don’t have to enter a user name or ID. The app will recognize you through your Password alone, from which it derives a pair of private and public keys. The private key is kept in memory for five minutes and then it is deleted along with anything private that might still be loaded on the app. The public key is checked in order to give or deny access to you. The first time you enter your Password, you are going to be denied access because the app does not know you yet. To gain access, you must copy your public key or ID, which will be displayed above the Password, and send it to your group Administrator so it is included on a list that loads with the app.
You will know when you have been enrolled because the app will accept your Password and display the name given to you by the Administrator. The app will show instructions for step 2 along with a fairly large area below it (it turns blue when you pass the mouse over it) where you can drop files by clicking it or dragging the files from Explorer or Finder onto it. You encrypt or decrypt files simply by dropping them onto the large area. The resulting file, whether encrypted or decrypted, will appear in your Downloads folder, so this is a good moment to resize your browser window so it is easy to drag and drop files from Explorer (Finder, on a Mac) to the GroupEncrypt drop area.
GroupEncrypt has two encryption modes: Folder, and File by File. In Folder mode, which is the default, you must load an encrypted Folder Key file first, and then the file to be encrypted or decrypted. This makes it possible to add a new sharer easily without having to re-encrypt all the files in the shared folder. Anybody can update the Folder Key, but it is best to let the Administrator do it (instructions for this below). The default name for the Folder Key file is _FolderKey.crypt although the Administrator may have given it a different name. After the Folder Key loads successfully, as soon as you drop an encrypted file from that folder, it is decrypted and saved to Downloads. Typically you will have to download the encrypted file from the service first, so you will be dragging that from Downloads to the drop area in the GroupEncrypt app, and getting the decrypted result back in Downloads.
Let’s say you have worked on that file and now it’s ready to be put back in the file sharing service. Drag the edited file to the file drop area in GroupEncrypt and it will be encrypted and saved back to Downloads. Now take the encrypted file you just got and drag it to the file sharing window, or whatever method they want you to use for uploading files. You may want to make sure that only the latest version of the encrypted file is kept there. And that’s it! The Folder Key makes sure the file has been encrypted only for the group members who are supposed to have access to it. If you have more files to add to that folder, encrypt them by loading them on the app while the Folder Key is still loaded. You can even encrypt (or decrypt) several files at the same time.
The other mode is File by File, which is selected by clicking a checkbox next to the user selection list, within the “Administrator extra” area. In this mode, the group members who can decrypt an encrypted file are selected from a dialog rather than automatically with a Folder Key. The default is encrypting for all group members, but you can reduce access by selecting members or specific groups of members on that dialog. Do ctrl-click to select several members or groups. The names of the group members that will be able to decrypt the file will be displayed in blue near the top of the page. After selecting members, just drag the files to be encrypted to the drop area as in the other mode, and they will be encrypted and saved to Downloads, from where you can upload them to the service. Decryption is simpler, since you don’t have to make any selection of members, load any key file, or even tell the app that a particular file was encrypted in File by File mode before you drag it to the drop area so it is decrypted and saved to Downloads. The downside of File by File mode is that each encrypted file needs to be re-encrypted in order to change the members who will be able to decrypt it, whereas in Folder mode you only need to do this with the Folder Key file.
Administrator Instructions
GroupEncrypt manages to provide a fairly simple user experience by moving key management tasks to a group Administrator. This person is responsible for maintaining the collection of users’ public keys and groups of users that is loaded with the app through the GroupKeys.js file. The choice of a .js file over a more common .json or .txt file or a server-side database is so that users can load the app from file without being online. The app itself provides the structure and correct format of this file by clicking “view technical details”, so I will address other issues in this tutorial, such as the processes for making the app available, enrolling new group members, changing access to files, and removing members. I will be making a distinction between the super-Administrator with access to the Web server hosting the app, and other Administrators who don’t need access to the server.
Making the app available (super-Administrator)
Your users can run the app either from file or from a Web server. There are advantages and disadvantages for both. If from file, it is possible to keep the group members’ public keys away from prying eyes, but then the Administrator must provide the users a new GroupKeys.js file every time there is a change in the user base. If supplied from a Web server, users will get those updates automatically, but then other people who happen to learn the URL for the app will be able to see all your users’ public keys as well. Fortunately, public keys are okay to be seen by strangers because it is practically impossible to obtain the users’ Passwords and private keys from their public keys. One additional hitch is that you’ll need a new installation and URL for each new group of users if your don’t want them to get mixed with other groups, but the installation is only a couple hundred kilobytes after extraction; no big deal space-wise. Just get the zip from GitHub or from here and extract it to your preferred folder on the server. If your server uses caching, make sure the file GroupKeys.js is not subject to any long-term cache. Otherwise group members won’t be getting an up-to-date version of the member database when they load the app. For each installation, it is good to change the key listed as “GroupName” in GroupKeys.js to something distinctive for that group, since it is used to salt the user Passwords and thus provide some protection against rainbow table attack. You may want to change the content of the “HeadTag” key, but only if there are plain files to be encrypted that happen to begin with that byte sequence. A last step is to go to the Administrator page and enter a Password of your choice (better if different from your user Password, but it can be the same if you insist) and hit return. The server won’t know it and will reject it, but it will also display a salted hash that matches it. Edit the file admin.php on the server to include this string as part of the array named $acceptedHashes (remove the dummy entries as well) so it will recognize your Administrator password. Whenever you want to add another Administrator, this is where his/her hash, obtained exactly the same way as yours, needs to be written.
Enrolling new members (regular Administrator)
A new member will be denied access at first, and he/she will be instructed to send you the public key displayed on the app. This is where interlopers could get in most easily, so it is important that you authenticate each new member before entering the corresponding public key on the database. Then load the app and click the text where it says “click here for Administrator page”. A new page will appear containing two boxes: a small one for a special Administrator Password, which should be different from your Password as a user (though it can be the same if you insist), and a big one displaying the current content of the GroupKeys.js file. The text GroupKeys, “GroupName”, and “HeadTag” must be left intact so the code can function, but you can edit pretty much everything else. The first time you submit your Administrator password it will be rejected, but the page will display a hash that you must send to the super-Administrator in order to get Administrator access.
Enrolling a new member involves writing a new name for him/her in the big box (quotes around it are optional, but encouraged), a colon, and then this member’s public key between quotes. Make sure there is always a comma between entries. If this member is going to be part of some smaller group of members, as defined in the file, just add the new member’s name to the list for that group (inside the quotation marks, with commas separating names). When you are ready to make changes to the user database, enter your Administrator password in the small box and click Submit. The changes will be accepted if the password is accepted.
Changing access to files (regular Administrator)
I won’t go into the process to share a folder with certain users or remove them from sharing, which is controlled by the file sharing service’s code and can be different from one service to another. But encryption requires an additional step so that the new set of shared users are the ones who in fact can decrypt the files contained therein, and not other users. If the files in that folder are encrypted in Folder mode, which is the default, there will be a file named _FolderKey.crypt (or something else that group members can recognize). When the members who are supposed to be able to decrypt the files change, the Administrator should download this file and load it into GroupEncrypt. Then he or she will display the selection box in the “Administrator extra” area. The Administrator then selects the members of groups of members who are supposed to have access to the files in the folder and presses the Update Folder Key button. This will create an updated _FolderKey.crypt file that has been encrypted for the new set of members, but containing the same inner key as before, which is the one that decrypts the rest of the files in the folder. Although this encryption happens in File by File mode, it is not necessary to check the box that selects this mode. The new encrypted key ends up in the computer’s Downloads folder, from where it can be uploaded to the file server, replacing the previous folder key.
Sometimes the update involves the creation of a new folder rather than changing access to an existing folder. In this case, the Administrator should reload the app in order to clear any Folder Key data from memory, select the members that should have access to the content in the new folder, and press the New Folder Key button. This will generate a new encrypted Folder Key distinct from all the other Folder Keys, which will be saved to Downloads. Files to be placed in this folder can be dragged to the drop area next, and all will be encrypted with the new key and saved to Downloads. Then the Administrator uploads all the recently created files to the new folder.
Files encrypted in File by File mode need to be decrypted and re-encrypted anew, after having selected the members who should have access. Encryption of files in this mode is independent for each file. No Folder Key is necessary.
Removing members (regular Administrator)
The process for removing members, so that they are no longer able to encrypt or decrypt files in the shared folders, is similar to that of adding members, involving the special Administrator page and password. Rather than removing the entries corresponding to the members to be removed, however, it is best to change those members to Legacy status. If a member is kept on the database as a Legacy member, this user can no longer encrypt or decrypt files for the other members or even proceed beyond Password entry, but the files previously encrypted by him/her can still be decrypted by the others, which can be especially important for Folder Keys. If the outgoing member is removed outright, it will be impossible to decrypt anything encrypted by this member that is still in the shared folders. To turn a member into a Legacy member, simply prepend a dollar sign to his/her name on the GroupKeys.js entry where the public key is stored. Example: “Adam” becomes “$Adam”. The name can be simply removed from entries containing lists of members. If after some time there are no longer any Folder Key files or File by File items that have been encrypted by this member, the public key can be removed safely from GroupKeys.js.