From 4df4e56a96cc1f5c554094193c0cbbb1d1b31eaa Mon Sep 17 00:00:00 2001
From: Micah Jerome Ellison <micah.jerome.ellison@gmail.com>
Date: Wed, 6 May 2020 18:14:44 -0700
Subject: [PATCH] Improve privacy, security, and encryption documentation #896
 (#925)

* Improve privacy, security, and encryption documentation #896
* Use gentler language and ensuring documentation does not read like legal advice
---
 docs/encryption.md | 36 +++++-----------------
 docs/security.md   | 74 ++++++++++++++++++++++++++++++++++++++++++++++
 mkdocs.yml         |  1 +
 3 files changed, 83 insertions(+), 28 deletions(-)
 create mode 100644 docs/security.md

diff --git a/docs/encryption.md b/docs/encryption.md
index 9909af67..806064b3 100644
--- a/docs/encryption.md
+++ b/docs/encryption.md
@@ -31,40 +31,20 @@ your journal.
 
 If you don’t initially store the password in the keychain but decide to
 do so at a later point – or maybe want to store it on one computer but
-not on another – you can simply run `jrnl --encrypt` on an encrypted
+not on another – you can run `jrnl --encrypt` on an encrypted
 journal and use the same password again.
 
 ## A note on security
 
-While jrnl follows best practises, true security is an illusion.
-Specifically, jrnl will leave traces in your memory and your shell
-history – it’s meant to keep journals secure in transit, for example
-when storing it on an
-[untrusted](http://techcrunch.com/2014/04/09/condoleezza-rice-joins-dropboxs-board/)
-services such as Dropbox. If you’re concerned about security, disable
-history logging for journal in your `.bashrc`:
+While `jrnl` follows best practices, total security is an illusion.
+There are a number of ways that people can at least partially
+compromise your `jrnl` data. See the [Privacy and Security](./security.md)
+documentation for more information.
 
-``` sh
-HISTIGNORE="$HISTIGNORE:jrnl *"
-```
+## No password recovery
 
-If you are using zsh instead of bash, you can get the same behaviour by
-adding this to your `zshrc`:
-
-``` sh
-setopt HIST_IGNORE_SPACE
-alias jrnl=" jrnl"
-```
-
-If you are using `fish` instead of `bash` or `zsh`, you can get the same behaviour by
-adding this to your `fish` configuration:
-
-``` sh
-abbr --add jrnl " jrnl"
-```
-
-To delete existing `jrnl` commands from `fish`’s history, run
-`history delete --prefix 'jrnl '`.
+There is no method to recover or reset your `jrnl` password. If you lose it,
+your data is inaccessible.
 
 ## Manual decryption
 
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 00000000..e8525b78
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,74 @@
+# Privacy and Security
+
+`jrnl` is designed with privacy and security in mind, but there are some
+limitations to be aware of.
+
+## Password strength
+
+`jrnl` doesn't enforce password strength requirements. Short or commonly-used
+passwords can easily be circumvented by someone with basic security skills
+and access to your encrypted `jrnl` file.
+
+## Shell history
+
+Since you can enter entries from the command line, any tool
+that logs command line actions is a potential security risk. See
+below for how to deal with this problem in various shells.
+
+### bash
+
+You can disable history logging for jrnl in your `.bashrc`:
+
+``` sh
+HISTIGNORE="$HISTIGNORE:jrnl *"
+```
+
+### zsh
+
+Disable history logging by adding this to your `zshrc`:
+
+``` sh
+setopt HIST_IGNORE_SPACE
+alias jrnl=" jrnl"
+```
+
+### fish
+
+Add this abbreviation to your `fish` configuration to run jrnl with
+a space before it, which prevents `fish` from logging it:
+
+``` sh
+abbr --add jrnl " jrnl"
+```
+
+To delete existing `jrnl` commands from `fish`’s history, run
+`history delete --prefix 'jrnl '`.
+
+### Windows Command Prompt
+
+Windows doesn't log history to disk, but it does keep it in your command
+prompt session. Close the command prompt or press Alt+F7 to clear its
+history after journaling.
+
+## Files in transit from editor to jrnl
+
+When creating or editing an entry, `jrnl` uses a plain text temporary file on disk
+to give your editor access to it. `jrnl` deletes the temporary file when it
+saves the entry back to your journal.
+
+If you save an entry but haven't closed your editor yet, and your computer shuts
+off or the `jrnl` process is killed, the entry remains on your disk as a
+temporary file. You can mitigate this issue by only saving with your editor
+right before closing it.
+
+## Plausible deniability
+
+You may be able to hide the contents of your journal behind a layer of encryption,
+but if someone has access to your configuration file, then they can figure out that
+you have a journal, where that journal file is, and when you last edited it.
+With a sufficient power imbalance, someone may be able to force you to unencrypt
+it through non-technical means.
+
+## Notice any other risks?
+
+Please let the maintainers know by [filing an issue on GitHub](https://github.com/jrnl-org/jrnl/issues).
\ No newline at end of file
diff --git a/mkdocs.yml b/mkdocs.yml
index 4c56567b..409bbd83 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -18,6 +18,7 @@ nav:
   - Quickstart: installation.md
   - Basic Usage: usage.md
   - Encryption: encryption.md
+  - Privacy and Security: security.md
   - Import and Export: export.md
   - Advanced Usage: advanced.md
   - Recipes: recipes.md