diff --git a/docs/encryption.md b/docs/encryption.md index c4bbc0e2..146bd2a8 100644 --- a/docs/encryption.md +++ b/docs/encryption.md @@ -49,17 +49,40 @@ same password again. This will trigger the keychain storage prompt. ## Manual Decryption -The easiest way to decrypt your journal is with `jrnl --decrypt`, but -if you would like 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 1** (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 @@ -90,17 +113,15 @@ key = base64.urlsafe_b64encode(kdf.derive(password)) print(Fernet(key).decrypt(ciphertext).decode('utf-8')) ``` -To run the above script, you'll need [`cryptography`](https://pypi.org/project/cryptography/), which you can install with `pip`: - -``` sh -pip3 install cryptography -``` - -If you're still using `jrnl` version 1.X, the following script serves the same -purpose: - +**Example 1** (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 @@ -124,10 +145,3 @@ plain = plain.strip(plain[-1:]) plain = plain.decode("utf-8") print(plain) ``` - -This script requires -[`pycrypto`](https://pypi.org/project/pycrypto/): - -```sh -pip3 install pycrypto -``` diff --git a/docs/export.md b/docs/export.md deleted file mode 100644 index 464dd550..00000000 --- a/docs/export.md +++ /dev/null @@ -1,76 +0,0 @@ -# Import and Export - -## Tag export - -With - -``` sh -jrnl --tags -``` - -you'll get a list of all tags you used in your journal, sorted by most -frequent. Tags occurring several times in the same entry are only -counted as one. - -## List of all entries - -``` sh -jrnl --short -``` - -Will only display the date and title of each entry. - -## JSON export - -Can do - -``` sh -jrnl --export json -``` - -Why not create a [beautiful timeline](http://timeline.knightlab.com/) of -your journal? - -## Markdown export - -Use - -``` sh -jrnl --export markdown -``` - -Markdown is a simple markup language that is human readable and can be -used to be rendered to other formats (html, pdf). This README for -example is formatted in markdown and github makes it look nice. - -## Text export - -``` sh -jrnl --export text -``` - -Pretty-prints your entire journal. - -## Export to files - -You can specify the output file of your exported journal using the -`-o` argument - -``` sh -jrnl --export md -o journal.md -``` - -The above command will generate a file named `journal.md`. If the`-o` argument is a directory, jrnl will export each entry into an individual file - -``` sh -jrnl --export json -o my_entries/ -``` - -The contents of `my\_entries/` will then look like this: - -``` output -my_entries/ -|- 2013_06_03_a-beautiful-day.json -|- 2013_06_07_dinner-with-gabriel.json -|- ... -``` diff --git a/docs/formats.md b/docs/formats.md new file mode 100644 index 00000000..4ced10e4 --- /dev/null +++ b/docs/formats.md @@ -0,0 +1,327 @@ +# Formats + +`jrnl` supports a variety of alternate formats. These can be used to display your +journal in a different manner than the `jrnl` default, and can even be used to pipe data +from your journal for use in another program to create reports, or do whatever you want +with your `jrnl` data. + +Any of these formats can be used with a search (e.g. `jrnl -contains "lorem ipsum" +--format json`) to display the results of that search in the given format, or can be +used alone (e.g. `jrnl --format json`) to display all entries from the selected journal. + +This page shows examples of all the built-in formats, but since `jrnl` supports adding +more formats through plugins, you may have more available on your system. Please see +`jrnl --help` for a list of which formats are available on your system. + +Any of these formats can be used interchangeably, and are only grouped into "display", +"data", and "report" formats below for convenience. + +## Display Formats +These formats are mainly intended for displaying your journal in the terminal. Even so, +they can still be used in the same way as any other format (like written to a file, if +you choose). + +### Pretty +``` sh +jrnl --format pretty +# or +jrnl -1 # any search +``` + +This is the default format in `jrnl`. If no `--format` is given, `pretty` will be used. + +It displays the timestamp of each entry formatted to by the user config followed by the +title on the same line. Then the body of the entry is shown below. + +This format is configurable through these values from your config file (see +[config](./config.md) for more details): + +- `colors` + - `body` + - `date` + - `tags` + - `title` +- `indent_character` +- `linewrap` +- `timeformat` + +**Example output**: +``` sh +2020-06-28 18:22 This is the first sample entry +| This is the sample body text of the first sample entry. + +2020-07-01 20:00 This is the second sample entry +| This is the sample body text of the second sample entry, but this one has a @tag. + +2020-07-02 09:00 This is the third sample entry +| This is the sample body text of the third sample entry. +``` + +### Short + +``` sh +jrnl --format short +# or +jrnl --short +``` + +This will shorten entries to display only the date and title. It is essentially the +`pretty` format but without the body of each entry. This can be useful if you have long +journal entries and only want to see a list of entries that match your search. + +**Example output**: +``` sh +2020-06-28 18:22 This is the first sample entry +2020-07-01 20:00 This is the second sample entry +2020-07-02 09:00 This is the third sample entry +``` + +### Fancy (or Boxed) +``` sh +jrnl --format fancy +# or +jrnl --format boxed +``` + +This format outlines each entry with a border. This makes it much easier to tell where +each entry starts and ends. It's an example of how free-form the formats can be, and also +just looks kinda ~*~fancy~*~, if you're into that kind of thing. + +**Example output**: +``` sh +┎──────────────────────────────────────────────────────────────────────╮2020-06-28 18:22 +┃ This is the first sample entry ╘═══════════════╕ +┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +┃ This is the sample body text of the first sample entry. │ +┖──────────────────────────────────────────────────────────────────────────────────────┘ +┎──────────────────────────────────────────────────────────────────────╮2020-07-01 20:00 +┃ This is the second sample entry ╘═══════════════╕ +┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +┃ This is the sample body text of the second sample entry, but this one has a @tag. │ +┖──────────────────────────────────────────────────────────────────────────────────────┘ +┎──────────────────────────────────────────────────────────────────────╮2020-07-02 09:00 +┃ This is the third sample entry ╘═══════════════╕ +┠╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌┤ +┃ This is the sample body text of the third sample entry. │ +┖──────────────────────────────────────────────────────────────────────────────────────┘ +``` + +## Data Formats +These formats are mainly intended for piping or exporting your journal to other +programs. Even so, they can still be used in the same way as any other format (like +written to a file, or displayed in your terminal, if you want). + +### JSON + +``` sh +jrnl --format json +``` + +JSON is a very handy format used by many programs and has support in nearly every +programming language. There are many things you could do with JSON data. Maybe you could +use [`jq`](https://github.com/stedolan/jq) to filter through the fields in your journal. +Like this: + +``` sh +$ j -3 --format json | jq '.entries[].date' jrnl-GFqVlfgP-py3.8  +"2020-06-28" +"2020-07-01" +"2020-07-02" +``` + +Or why not create a [beautiful timeline](http://timeline.knightlab.com/) of your journal? + +**Example output**: +``` json +{ + "tags": { + "@tag": 1 + }, + "entries": [ + { + "title": "This is the first sample entry", + "body": "This is the sample body text of the first sample entry.", + "date": "2020-06-28", + "time": "18:22", + "tags": [], + "starred": false + }, + { + "title": "This is the second sample entry", + "body": "This is the sample body text of the second sample entry, but this one has a @tag.", + "date": "2020-07-01", + "time": "20:00", + "tags": [ + "@tag" + ], + "starred": false + }, + { + "title": "This is the third sample entry", + "body": "This is the sample body text of the third sample entry.", + "date": "2020-07-02", + "time": "09:00", + "tags": [], + "starred": false + } + ] +} +``` + +### Markdown + +``` sh +jrnl --format markdown +# or +jrnl --format md +``` + +Markdown is a simple markup language that is human readable and can be used to be +rendered to other formats (html, pdf). `jrnl`'s +[README](https://github.com/jrnl-org/jrnl/blob/develop/README.md) for example is +formatted in markdown, then Github adds some formatting to make it look nice. + +The markdown format groups entries by date (first by year, then by month), and adds +header markings as needed (e.g. `#`, `##`, etc). If you already have markdown header +markings in your journal, they will be incremented as necessary to make them fit under +these new headers (i.e. `#` will become `##`). + +This format can be very useful, for example, to export a journal to a program that +converts markdown to html to make a website or a blog from your journal. + +**Example output**: +``` markdown +# 2020 + +## June + +### 2020-06-28 18:22 This is the first sample entry + +This is the sample body text of the first sample entry. + +## July + +### 2020-07-01 20:00 This is the second sample entry + +This is the sample body text of the second sample entry, but this one has a @tag. + +### 2020-07-02 09:00 This is the third sample entry + +This is the sample body text of the third sample entry. +``` + +### Plain Text + +``` sh +jrnl --format text +# or +jrnl --format txt +``` + +This outputs your journal in the same plain-text format that `jrnl` uses to store your +journal on disk. This format is particularly useful for importing and exporting journals +within `jrnl`. + +You can use it, for example, to move entries from one journal to another, or to create a +new journal with search results from another journal (see [Import and +Export](./import-and-export.md) for more details). + +**Example output**: +``` sh +[2020-06-28 18:22] This is the first sample entry +This is the sample body text of the first sample entry. + +[2020-07-01 20:00] This is the second sample entry +This is the sample body text of the second sample entry, but this one has a @tag. + +[2020-07-02 09:00] This is the third sample entry +This is the sample body text of the third sample entry. +``` + +### XML +``` sh +jrnl --format xml +``` + +This outputs your journal into XML format. XML is a commonly used data format and is +supported by many programs and programming languages. + +**Example output**: +``` xml + + + + This is the first sample entry This is the sample body text of the first sample entry. + + + This is the second sample entry This is the sample body text of the second sample entry, but this one has a @tag. + + *This is the third sample entry, and is starred This is the sample body text of the third sample entry. + + + 1 + + +``` + +### YAML +``` sh +jrnl --format yaml +``` + +This outputs your journal into YAML format. YAML is a commonly used data format and is +supported by many programs and programming languages. + +**Example output**: +``` yaml +title: This is the second sample entry +date: 2020-07-01 20:00 +starred: False +tags: tag + +This is the sample body text of the second sample entry, but this one has a @tag. +``` + +## Report formats +Since formats use your journal data and display it in different ways, they can also be +used to create reports. + +### Tags + +``` sh +jrnl --format tags +# or +jrnl --tags +``` + +This format is a simple example of how formats can be used to create reports. It +displays each tag, and a count of how many entries in which tag appears in your journal +(or in the search results), sorted by most frequent. + +Example output: +``` sh +@one : 32 +@two : 17 +@three : 4 +``` + +## Options + +### `--file` + +Example: `jrnl --format json --file /some/path/to/a/file.txt` + +By default, `jrnl` will output entries to your terminal. But if you provide the `--file` +along with a filename, the same output that would have been to your terminal will be +written to the file instead. This is the same as piping the output to a file. + +So, in bash for example, the following two statements are equivalent: + +``` sh +jrnl --format json --file myjournal.json +``` + +``` sh +jrnl --format json > myjournal.json +``` + diff --git a/docs/import-and-export.md b/docs/import-and-export.md new file mode 100644 index 00000000..07ed9b09 --- /dev/null +++ b/docs/import-and-export.md @@ -0,0 +1,28 @@ + + +## Export to files + +You can specify the output file of your exported journal using the +`-o` argument + +``` sh +jrnl --format md -o journal.md +``` + +The above command will generate a file named `journal.md`. If the`-o` argument is a +directory, jrnl will export each entry into an individual file + +``` sh +jrnl --format json -o my_entries/ +``` + +The contents of `my\_entries/` will then look like this: + +``` output +my_entries/ +|- 2013_06_03_a-beautiful-day.json +|- 2013_06_07_dinner-with-gabriel.json +|- ... +``` diff --git a/docs/security.md b/docs/security.md index e8525b78..ff0d0f06 100644 --- a/docs/security.md +++ b/docs/security.md @@ -1,65 +1,80 @@ # Privacy and Security -`jrnl` is designed with privacy and security in mind, but there are some -limitations to be aware of. +`jrnl` is designed with privacy and security in mind, but like any other +program 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. +passwords can be easily circumvented by someone with basic security skills +to 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. +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`: +You can disable history logging for jrnl by adding this line into your +`~/.bashrc` file: ``` sh HISTIGNORE="$HISTIGNORE:jrnl *" ``` +To delete existing `jrnl` commands from `bash` history, simply delete them from +your bash history file. The default location of this file is `~/.bash_history`, +but you can run `echo "$HISTFILE"` to find it if needed. Also, you can run +`history -c` to delete all commands from your history. + ### zsh -Disable history logging by adding this to your `zshrc`: +You can disable history logging for jnrl by adding this to your `~/.zshrc` +file: ``` sh setopt HIST_IGNORE_SPACE alias jrnl=" jrnl" ``` +To delete existing `jrnl` commands from `zsh` history, simply remove them from +your zsh history file. The default location of this file is `~/.zsh_history`, +but you can run `echo "$HISTFILE"` to find it if needed. Also, you can run +`history -c` to delete all commands from your history. + ### fish -Add this abbreviation to your `fish` configuration to run jrnl with -a space before it, which prevents `fish` from logging it: +By default `fish` will not log any command that starts with a space. If you +want to always run jrnl with a space before it, then you can add this to your +`~/.config/fish/config.fish` file: ``` sh abbr --add jrnl " jrnl" ``` -To delete existing `jrnl` commands from `fish`’s history, run -`history delete --prefix 'jrnl '`. +To delete existing jrnl commands from `fish` 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. +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 your 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. +When creating or editing an entry, `jrnl` uses a unencrypted temporary file on +disk in order to give your editor access to your journal. After you close your +editor, `jrnl` then deletes this temporary file. -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. +So, if you have saved a journal entry but haven't closed your editor yet, the +unencrypted temporary remains on your disk. If your computer were to shut off +during this time, or the `jrnl` process were killed unexpectedly, then the +unencrypted temporary file will remain on your disk. You can mitigate this +issue by only saving with your editor right before closing it. You can also +manually delete these files (i.e. files named `jrnl_*.txt`) from your temporary +folder. ## Plausible deniability @@ -71,4 +86,4 @@ 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 +Please let the maintainers know by [filing an issue on GitHub](https://github.com/jrnl-org/jrnl/issues). diff --git a/mkdocs.yml b/mkdocs.yml index 409bbd83..bf12faf8 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -19,6 +19,7 @@ nav: - Basic Usage: usage.md - Encryption: encryption.md - Privacy and Security: security.md - - Import and Export: export.md + - Formats: formats.md + - Import and Export: import-and-export.md - Advanced Usage: advanced.md - Recipes: recipes.md