new(project): Ciphey

content/projects/ciphey/index.md

@@ -1,6 +1,268 @@
 +++
-title = "Ciphey"
+title = "ciphey"
 weight = 1
 [taxonomies]
 tags = []
 +++
+
+Simply put, `ciphey` is a password and secret manager that is like
+[`pass`](https://passwordstore.org) if it used
+[`age`](https://age-encryption.org) instead of PGP. More than anything, it is
+an experiment to determine how cryptography can be combined in a minimalist
+manner to protect passwords in a way that accounts for the most realistic
+threats to their confidentiality, reliability, usability, and resiliency. It
+takes many of the database and key management ideas from
+[1Password](https://1password.com) and [Bitwarden](https://bitwarden.com) and
+combines them with the Unix-like philosophy of `pass`.
+
+To be clear, `ciphey` is still in development. [The remaining work is outlined
+below](#remaining-work). While I will be using it as my actual password manager,
+I strongly recommend that you only experiment with it and not rely on it for any
+actual passwords.
+
+*NOTE: This page is a work in progress.*
+
+## The Basics
+
+My goal is for `ciphey` to be simple enough that someone with a bit of knowledge
+about cryptography who wants to understand how their passwords are protected can
+do so after a short explanation. This sections aims to be that explanation.
+
+### Entries
+
+Everything you store in `ciphey` goes into an entry. Generally, you'll have one
+`entry` per password. However, passwords come in many different forms: as a
+result, entries are plaintext, which means any file can be used as an entry.
+
+This doesn't mean there is no structure to entries. For example, take a look at
+the entry for a hypothetical [`xkcd.com`](https://xkcd.com) account below:
+
+```
+correct horse battery staple
+name: xkcd.com
+tag: comics
+username: Tr0ub4dor&3
+url: https://xkcd.com/936
+
+To anyone who understands information theory and security and is in an
+infuriating argument with someone who does not (possibly involving mixed case),
+I sincerely apologize.
+```
+
+The first line of every entry is interpreted as the entry's "secret."  In this
+case, the secret is `correct horse battery staple`, the password for the
+account. This is usually a password or private key, but can be any value that
+you might want to access by default.  If this doesn't work for you for some
+reason, no worries; just leave the line blank.
+
+The secret is followed by any number of optional field-value pairs. Every
+field-value pair lives on its own line and can contain any information you want,
+so long as it follows the format `FIELD: VALUE`. Fields can be repeated and in
+any order. The only limitation is that your `FIELD` cannot contain a `: ` (`:`
+followed by a space), but the `VALUE` can.
+
+There are no `FIELD`s with any special meaning (yet), but keeping them
+consistent will help you find entries more quickly. I strongly recommend giving
+each entry a `name` field, as this is what `ciphey` uses to search for entries
+by default.
+
+Finally, the contents of the file from the first line that doesn't match the
+pattern `FIELD: VALUE` down to the end of the file is left uninterpreted,
+meaning that you can save any text that you'd like there. This is called the
+"note." In the example above, the "note" is the caption text from
+[xkcd.com/936](https://xkcd.com/936). Separate the notes and the preceding
+section with a newline.
+
+### The Entries
+
+Your `ciphey` database is a folder of files that can live on any filesystem.
+This folder is completely encrypted, and thus can safely be backed up, shared,
+or otherwise accessed without any unauthorized party gaining access to the
+contents of the file.
+
+```
+ciphey/
+└── entries/
+    ├── age1sdnql3ksstj7krh7azddygh860f6uttus5t3e9j52t4k5z34kutqyzgr4e.age
+    ├── age1ryutmsg486w4y06kq7w0rqm2s08r3sgzlwcl9p9p00jducedevvqkgrvyw.age
+    ├── age1mqr5htmadgzlmcdjks79d6ucfe5k46ruavnaxm08m64lpl6h5udqhkwwvp.age
+    └── age1r908d20yj3ntp9q8g0448kwflfgf3au2qmhkkx7zp8xnesfdjfhqpd3r2d.age
+```
+
+Each file in the "entries" folder contains a single "entry." The name of each
+file is the `age` public key the entry is encrypted to. Every entry into your
+database is encrypted to a unique public key. Without that public key's
+corresponding private key, the contents of the entry cannot be accessed.
+
+However, keep in mind that some metadata does leak. Namely, any data associated
+with the filesystem (date created, date last modified, owner/group, etc.) is NOT
+protected by `ciphey` by default. It's still a good idea to keep your database
+away from any curious eyes when it's avoidable.
+
+### Your Keys
+
+Every time you unlock your `ciphey` database, you must have two things:
+
+1. Your `Primary Passphrase` (something you know)
+2. A `Device Key` (something you have)
+
+Every "device" you have (i.e. your desktop, laptop, and phone) has its own
+`Device Key`. This key is generated and stored as a normal file when you first
+set up `ciphey` on the device, and never leaves it.
+
+Each `Device Key` is encrypted with your `Primary Passphrase`. Without your
+`Primary Passphrase`, the `Device Key` cannot be used.
+
+Alternatively, you can use a `Device Key` stored on a hardware token, such as a
+Yubikey or OnlyKey. This has the added benefit that the key material never
+leaves the hardware token, protecting against attacks that can steal key
+material from your computer's local disk. In order to decrypt your entries, an
+attacker would have to physically have access your hardware token, in addition
+to learning your `Primary Passphrase`.
+
+### Entry Keys
+
+Every entry in your database is encrypted to a specific `Entry Key`. These entry
+keys are stored next to the `database` directory in the `keys` directory. Every
+entry gets its own key so that access can be cryptographically restricted on an
+entry-by-entry basis.
+
+The keys stored on the filesystem are encrypted to every `Device Key` that
+you've given access to the entry.
+
+### Disaster Recovery
+
+When you set up your `ciphey` database for the first time, you'll be prompted to
+create a `Recovery Key`, which is an `age` key encrypted with your `Recovery
+Passphrase` (By default, your `Primary Passphrase`, but this can optionally be
+changed). This key should be written down and stored in a safe place, such as in
+a safe. This way, if you lose all of your devices, you can still regain access
+to your passwords.
+
+You can also give a copy of this key and your `Recovery Passphrase` to anybody
+else who should have access to your accounts in case of an emergency. This way,
+you can be sure that you're unlikely to ever lose access to your `ciphey` keys.
+
+### Summary
+
+Every entry is encrypted with its own unique `Entry Key`.
+
+`Entry Key`s are encrypted to each `Device Key` that is granted access to the
+entry. They can be encrypted to other people's `Device Key`s to share an entry
+with them.
+
+`Device Key`s are encrypted with your `Primary Passphrase`. They can either live
+on your filesystem or on a hardware token, like a Yubikey.
+
+When you first set up `ciphey`, you also create a `Recovery Key`, which every
+`Entry Key` is encrypted to by default. This `Recovery Key` is encrypted with
+your `Recovery Passphrase`, which are to be stored offline in a safe place
+and/or given to trusted individuals so they can be used in case of an emergency.
+
+### Usage
+
+## Implementation
+
+### Entry Parsing
+
+The entry format was designed to be easy to parse for both humans and programs.
+The following Rust snippet is a (simplified) example of parsing an Entry from a
+String `s`:
+
+```rust
+// The entry's secret
+let mut secret: String;
+// A vector of key/value pairs
+let mut fields: (String, String) = Vec::new();
+// The entry's notes
+let mut notes: Option<String> = None;
+
+// An iterator over the decrypted lines of the entry file
+let mut lines = s.lines();
+
+// The first line contains the secret
+secret = lines.next();
+
+while let Some(line) = lines.by_ref().next() {
+	if let Some((key, value)) = line.split_once(": ") {
+		// Add the key and value to fields
+		fields.push((key, value));
+	} else {
+		// Take the rest of the lines and put them into notes
+		notes = Some(
+			std::iter::once(line)
+				.chain(lines.by_ref())
+				.collect::<Vec<String>>()
+				.join("\n"),
+		);
+	}
+}
+```
+
+This particular implementation has a lot of room for improvement. The biggest
+issue adding complexity is that Rust's `take_while` iterator method is
+consuming, not peekable, meaning that ownership of the lines it checks is passed
+to its closure. Thus, the following snippet, which is much easier to
+read, would not work:
+
+```rust
+// An iterator over the decrypted lines of the entry file
+let mut lines = s.lines();
+
+// The first line contains the secret
+secret = lines.next();
+
+// Take lines while they can be parsed as key/value pairs split by ": "
+fields = lines.take_while(line.split_once(": ")).map(...);
+// first line failing take_while is incorrectly dropped here
+
+// Join the remaining lines as notes
+notes = lines.collect::<Vec<String>>().join("\n");
+```
+
+This is because even though the first line that fails the conditional is
+consumed by `take_while`, it would neither be added to the fields (as it cannot
+be parsed as one) nor collected into the vector over the lines of notes, instead
+being dropped, causing data loss.
+
+There are a few Rust crates that provide a peekable `take_while`, but they're
+too big to justify as adding as dependencies for just this feature. It's
+possible that a simpler approach is possible using an iterative method, but I
+have not been able to come up with one yet.
+
+## Remaining Work
+
+### Password History
+
+At the moment, there is no built-in support for keeping track of entry changes
+over time. `pass` uses git to keep track of changes at the filesystem level,
+while password managers like Bitwarden have built-in support for storing the
+history of passwords over time.
+
+Currently, there is nothing stopping someone from manually checking entries into
+git or another backup solution. However, one way to provide better integration
+into `ciphey` would be to allow for `pre-hooks` and `post-hooks`.  These hooks
+are scripts that are run before or after specific actions are taken by `ciphey`.
+This would allow, for example, automatically committing the changes to a git
+repository and pushing those changes to a remote server after every change made
+by `ciphey`.
+
+### File storage
+
+For the moment, entries must be plaintext files. If you want to encrypt an
+arbitrary file with `ciphey`, you have to manually create an encryption key,
+store that key as an entry in `ciphey`, and then manually encrypt said file with
+the newly-created key.
+
+It would be beneficial to devise a way to treat encrypted files just like any
+entry so that the key material for other files can be automatically managed in
+the same way.
+
+### Backup
+
+While `ciphey` makes sure that you don't lose your secret key material through
+the use of `Recovery Key`s, `ciphey` does not have any built-in backup system
+for the encrypted `ciphey` database. Of course, you can still back up `ciphey`
+like any other directory (which is a benefit of it living as just a plain
+directory), but it may be useful to consider ways that `ciphey` can better
+integrate or accomodate backups.