Documentation updates (#1032)

* Applying doc changes based on reviews of past several documentation PRs
* Update docs
  Clean up encryption docs
  Clean up security docs
  Delete export.md
  Make new formats.md and add to sidebar. Also add all of the built-in formats, and examples for each.
  Update mkdocs config for new files

* Fix broken docs links
* Correct incomplete sentences and markdown formatting issues
* Make overview a little more concise
* Update some command line arguments to latest version and make it a bit more concise
* Clean up unneeded TOML modifications and other scaffolding not needed for 3.9
* Revert "Clean up unneeded TOML modifications and other scaffolding not needed for 3.9"
  This reverts commit 13b4266ed1.
* Specify that brew is also the easiest way to install jrnl on Linux
* Update docs/security.md
* Update docs/recipes.md
* Doc updates:
- Remove import/export page, fold it into formats
- Rename security to privacy-and-security.md to avoid conflation w/ github security issues
- Various small cleanup and edits from PR review

Co-authored-by: Jonathan Wren <jonathan@nowandwren.com>
This commit is contained in:
Micah Jerome Ellison 2020-10-24 15:41:58 -07:00 committed by GitHub
parent 4ee4f388f4
commit 5b029e6117
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
11 changed files with 537 additions and 238 deletions

View file

@ -4,26 +4,9 @@
While `jrnl` follows best practices, total security is never possible in the
real world. There are a number of ways that people can at least partially
compromise your `jrnl` data. See the [Privacy and Security](./security.md) page
compromise your `jrnl` data. See the [Privacy and Security](./privacy-and-security.md) page
for more information.
## Dependencies
As of version 2.0, `jrnl`'s encryption functions require
[`cryptography`](https://pypi.org/project/cryptography/), which is available in
the Python Package Index (PyPI) and can be installed using `pip`:
``` sh
pip3 install cryptography
```
Previous versions of `jrnl` require
[`pycrypto`](https://pypi.org/project/pycrypto/):
```sh
pip3 install pycrypto
```
## Encrypting and Decrypting
Existing plain text journal files can be encrypted using the `--encrypt`
@ -52,7 +35,7 @@ encrypted file untouched and create a new plain text file next to it.
## Storing Passwords in Your Keychain
There is no method to recover or reset your `jrnl` password. If you lose it,
Nobody can recover or reset your `jrnl` password. If you lose it,
your data will be inaccessible forever.
For this reason, when encrypting a journal, `jrnl` asks whether you would like
@ -66,16 +49,40 @@ same password again. This will trigger the keychain storage prompt.
## Manual Decryption
Should you ever want to decrypt your journal manually, you can do so with any
program that supports the AES algorithm in CBC. The key used for encryption is
the SHA-256 hash of your password. The IV (initialization vector) is stored in
the first 16 bytes of the encrypted file. The plain text is encoded in UTF-8 and
padded according to PKCS\#7 before being encrypted.
The easiest way to decrypt your journal is with `jrnl --decrypt`, but you could
also decrypt your journal manually if needed. To do this, you can use any
program that supports the AES algorithm (specifically AES-CBC), and you'll need
the following relevant information for decryption:
Here is a Python script that you can use to decrypt your journal:
- **Key:** The key used for encryption is the
[SHA-256](https://en.wikipedia.org/wiki/SHA-2) hash of your password.
- **Initialization vector (IV):** The IV is stored in the first 16 bytes of
your encrypted journal file.
- **The actual text of the journal** (everything after the first 16 bytes in
the encrypted journal file) is encoded in
[UTF-8](https://en.wikipedia.org/wiki/UTF-8) and padded according to
[PKCS\#7](https://en.wikipedia.org/wiki/PKCS_7) before being encrypted.
If you'd like an example of what this might look like in script form, please
see below for some examples of Python scripts that you could use to manually
decrypt your journal.
!!! note
These are only examples, and are only here to illustrate that your journal files
will still be recoverable even if `jrnl` isn't around anymore. Please use
`jrnl --decrypt` if available.
**Example for jrnl v2 files**:
``` python
#!/usr/bin/env python3
"""
Decrypt a jrnl v2 encrypted journal.
Note: the `cryptography` module must be installed (you can do this with
something like `pip3 install crytography`)
"""
import base64
import getpass
@ -106,11 +113,15 @@ key = base64.urlsafe_b64encode(kdf.derive(password))
print(Fernet(key).decrypt(ciphertext).decode('utf-8'))
```
If you're still using `jrnl` version 1.X, the following script serves the same
purpose:
**Example for jrnl v1 files**:
``` python
#!/usr/bin/env python3
"""
Decrypt a jrnl v1 encrypted journal.
Note: the `pycrypto` module must be installed (you can do this with something
like `pip3 install pycrypto`)
"""
import argparse
from Crypto.Cipher import AES