website/docs/Cold Storage.md

70 lines
3.7 KiB
Markdown
Raw Permalink Normal View History

# Cold Storage
One of the security features of the website is **cold storage** which implements a "one way" encryption process for archiving sensitive files on the site.
The first use case is to archive secondary photo IDs: if a user was requested to provide a scan of their government issued photo ID for approval, the site can archive the original copy to cold storage when approved in case of any future inquiry.
The cold storage feature works by encrypting the file using an RSA public key, and relies on the matching private key to be **removed** from the web server and kept offline; so in case of a hack or data breach, the key that can decrypt the cold storage files will **NOT** be kept on the same web server.
This document explains how this feature works and how to configure it.
## Initialization
When the server starts up and there is not a cold storage RSA key configured, the feature will be initialized by generating new RSA encryption keys:
* The directory `./coldstorage/keys` is created and the RSA keys will be written in files named **private.pem** and **public.pem**.
* The RSA public key is _also_ written into the **settings.json** file for the server, at the Encryption / ColdStorageRSAPublicKey property.
You should **move the keys OFF of your web server machine** and keep them safe for your bookkeeping. Notably, the `private.pem` key is the sensitive file that should be removed.
The app does not need either of these keys to remain on the server: the settings.json has a copy of the RSA public key which the app uses to create cold storage encrypted files.
### Admin Dashboard Warning
As a safety precaution: if the private.pem key remains on disk, a warning is shown at the top of the Admin Dashboard page of the website to remind you that the key should be removed and stored safely offline.
## Recovering from Cold Storage
Should you need to recover an encrypted file from cold storage, the `nonshy coldstorage decrypt` command built into the Go server binary has the function to decrypt the files.
Every item that is moved into cold storage generates two files: an encrypted AES key file (`.aes`) and the encrypted data file itself (with a `.enc` extension). For example, a "photo.jpg" might go into cold storage as two files: "photo.jpg.aes" and "photo.jpg.enc"
You will need the following three files to decrypt from cold storage:
1. The RSA private key file (private.pem)
2. The encrypted AES key file (.aes extension)
3. The encrypted cold storage data file (.enc extension)
The command to decrypt them is thus like:
```bash
# command example
nonshy coldstorage decrypt \
--key private.pem \
--aes photo.jpg.aes \
--input photo.jpg.enc \
--output photo.jpg
# short command line flags work too
nonshy coldstorage decrypt -k private.pem \
-a photo.jpg.aes -i photo.jpg.enc \
-o photo.jpg
```
The `--output` file is where the decrypted file will be written to.
## Encryption Algorithms
When a file is moved into cold storage:
1. A fresh new AES symmetric key is generated from scratch.
2. The AES key is encrypted using the **RSA public key** and written to the ".aes" file in the coldstorage/ folder.
3. The original file is encrypted using that AES symmetric key and written to the ".enc" file in the coldstorage/ folder.
At the end of the encrypt function: the web server no longer has the AES key and is _unable_ to decrypt it because the private key is not available (as it should be kept offline for security).
Decrypting a file out of cold storage is done like so:
1. The encrypted AES key is unlocked using the **RSA private key**.
2. The encrypted cold storage file (.enc) is decrypted with that AES key.
3. The cleartext data is written to the output file.