stash.1

.\"t
.\" Automatically generated by Pandoc 2.9.2
.\"
.TH "" "" "" "" ""
.hy
.SH stash
.PP
\f[C]stash\f[R] is a command line program for storing text data in
encrypted form.
.PP
All user data is encrypted using AES
256 (https://en.wikipedia.org/wiki/Advanced_Encryption_Standard) cipher.
.PP
Data is hashed for indexing purposes using a good random salt +
SHA512 (https://en.wikipedia.org/wiki/SHA-2).
.PP
.PP
\f[B]Table of Contents\f[R]
.IP \[bu] 2
stash
.RS 2
.IP \[bu] 2
Rationale
.IP \[bu] 2
Installation
.RS 2
.IP \[bu] 2
Linux and Mac
.IP \[bu] 2
Others
.RE
.IP \[bu] 2
Getting Started
.IP \[bu] 2
Browsing
.RS 2
.IP \[bu] 2
Terminal user interface (default)
.IP \[bu] 2
As Org text
.IP \[bu] 2
As Markdown text
.RE
.IP \[bu] 2
Dumping contents to stdout
.RS 2
.IP \[bu] 2
As Org text (default)
.IP \[bu] 2
As Markdown text
.IP \[bu] 2
As JSON text
.RE
.IP \[bu] 2
Backing up data
.IP \[bu] 2
Importing text
.IP \[bu] 2
Babashka pod support
.IP \[bu] 2
Customization
.IP \[bu] 2
Shell Autocompletion
.RS 2
.IP \[bu] 2
bash
.IP \[bu] 2
zsh
.IP \[bu] 2
fish
.RE
.IP \[bu] 2
Credits
.RE
.SS Rationale
.PP
All of us need to store sensitive information.
At the very least, we need to keep passwords and keys to numerous online
services we use.
Storing them in plain-text is risky.
So is not keeping backups in multiple locations.
.PP
\f[C]stash\f[R] is an open-source tool to store text in encrypted form.
The encrypted data can be stored in untrusted locations without
compromising it, granted the encryption-key is unguessable.
.SS Installation
.SS Linux and Mac
.PP
Install:
.IP
.nf
\f[C]
brew install rorokimdim/brew/stash
\f[R]
.fi
.PP
Upgrade:
.IP
.nf
\f[C]
brew upgrade stash
\f[R]
.fi
.PP
Uninstall:
.IP
.nf
\f[C]
brew uninstall stash
\f[R]
.fi
.PP
Binaries are available at
releases (https://github.com/rorokimdim/stash/releases).
.SS Others
.PP
No pre-built binaries available at this time.
We will need to build from source using \f[C]stack install\f[R] or
\f[C]cabal install\f[R].
.PP
Install stack (https://docs.haskellstack.org/en/stable/README/), clone
this repository and run the following in repository directory.
.IP
.nf
\f[C]
stack install
\f[R]
.fi
.SS Getting Started
.PP
Create a stash file.
.IP
.nf
\f[C]
stash create {path-to-stash-file}
\f[R]
.fi
.PP
Replace \f[C]{path-to-stash-file}\f[R] with path to the stash file.
For example \f[C]\[ti]/Dropbox/secret.stash\f[R].
.PP
Stash will prompt for the encryption-key (password) to use for the file.
The key is not saved anywhere, but a salted hash (good random salt +
SHA512) of the key and the salt is saved.
.PP
When we run a stash command, we will be prompted for our encryption key.
It is checked against the hash stored during \f[C]stash create\f[R].
For the duration of the command, the encryption key will be used for
encrypting/decrypting data.
.PP
The salt stored during \f[C]stash create\f[R] is also used for hashing
any data for indexing purposes.
.SS Browsing
.PP
This feature does not currently work on windows.
.SS Terminal user interface (default)
.IP
.nf
\f[C]
stash browse {path-to-stash-file}
\f[R]
.fi
.PP
.TS
tab(@);
l l.
T{
Shortcuts
T}@T{
Description
T}
_
T{
ESC (q)
T}@T{
Quit
T}
T{
?
T}@T{
Show this help
T}
T{
+
T}@T{
Add a new key
T}
T{
>
T}@T{
Add a child key to selected key
T}
T{
-
T}@T{
Delete selected key
T}
T{
, (r)
T}@T{
Rename selected key
T}
T{
/
T}@T{
Search and sort by pattern
T}
T{
y
T}@T{
Copy value of selected key into system clipboard
T}
T{
Enter
T}@T{
Set value of selected key
T}
T{
H
T}@T{
See history of values of selected key
T}
T{
Left arrow (h)
T}@T{
Move to parent of selected key
T}
T{
Right arrow (l)
T}@T{
Move to child of selected key
T}
T{
Up arrow (k, Ctrl-p)
T}@T{
Select above
T}
T{
Down arrow (j, Ctrl-n)
T}@T{
Select below
T}
T{
g, G
T}@T{
Move to top, Move to bottom
T}
T{
Ctrl-u, Ctrl-d
T}@T{
Scroll keys half page up / down
T}
T{
Ctrl-b, Ctrl-f
T}@T{
Scroll keys one page up / down
T}
.TE
.SS As Org text
.IP
.nf
\f[C]
stash browse -f org {path-to-stash-file}
\f[R]
.fi
.PP
Opens as Org text in default editor.
Set EDITOR environment variable to your editor command.
Defaults to vim.
.SS As Markdown text
.IP
.nf
\f[C]
stash browse -f markdown {path-to-stash-file}
\f[R]
.fi
.PP
Opens as markdown text in default editor.
Set EDITOR environment variable to your editor command.
Defaults to vim.
.SS Dumping contents to stdout
.SS As Org text (default)
.IP
.nf
\f[C]
stash dump -f org {path-to-stash-file}
\f[R]
.fi
.SS As Markdown text
.IP
.nf
\f[C]
stash dump -f markdown {path-to-stash-file}
\f[R]
.fi
.SS As JSON text
.IP
.nf
\f[C]
stash dump -f json {path-to-stash-file}
\f[R]
.fi
.SS Backing up data
.IP
.nf
\f[C]
stash backup {path-to-stash-file}
\f[R]
.fi
.PP
Creates a timestamped copy of stash file in the same directory as the
original file.
.SS Importing text
.PP
We can import \f[C]org\f[R] and \f[C]markdown\f[R] text into stash.
This feature is only available in version 0.2.0+.
.IP
.nf
\f[C]
cat {path-to-text-file} | stash import {path-to-stash-file}
\f[R]
.fi
.PP
\f[C]stash import\f[R] will assume text is in \f[C]org\f[R] format by
default, but \f[C]markdown\f[R] is supported too:
.IP
.nf
\f[C]
cat {path-to-text-file} | stash import -f markdown {path-to-stash-file}
\f[R]
.fi
.PP
We can import from another stash file similarly:
.IP
.nf
\f[C]
stash dump {path-to-source-stash-file} | stash import {path-to-destination-stash-file}
\f[R]
.fi
.PP
We will need to first enter encryption-key for the source stash-file
followed by encryption-key for the destination stash file.
.SS Babashka pod support
.PP
\f[C]stash\f[R] exposes a
bencode (https://en.wikipedia.org/wiki/Bencode) interface using Babashka
Pod Protocol (https://github.com/babashka/pods#the-protocol).
.PP
If you are familiar with clojure (https://clojure.org/) or
babashka (https://github.com/borkdude/babashka), see
clojure-example (https://github.com/rorokimdim/stash/tree/master/scripting-examples/clojure).
.PP
Common-lisp folks see
common-lisp-example (https://github.com/rorokimdim/stash/tree/master/scripting-examples/common-lisp).
.PP
Python folks see
python-example (https://github.com/rorokimdim/stash/tree/master/scripting-examples/python).
.SS Customization
.PP
A few things in stash can be customized via environment variables.
.PP
.TS
tab(@);
l l l l.
T{
Name
T}@T{
Description
T}@T{
Possible Values
T}@T{
Default
T}
_
T{
\f[C]STASH_ENCRYPTION_KEY\f[R]
T}@T{
encryption key
T}@T{
-
T}@T{
prompt as needed
T}
T{
\f[C]STASH_WIPE_CLIPBOARD_AFTER_BROWSE\f[R]
T}@T{
wipe clipboard after browse
T}@T{
true, false
T}@T{
false
T}
T{
\f[C]STASH_LOG_LEVEL\f[R]
T}@T{
logging level
T}@T{
DEBUG, INFO, WARN, ERROR
T}@T{
INFO
T}
T{
\f[C]STASH_TUI_COLOR_SELECTED\f[R]
T}@T{
color of selected item
T}@T{
see below
T}@T{
cyan
T}
T{
\f[C]STASH_TUI_COLOR_CURRENT_PATH\f[R]
T}@T{
color of current path
T}@T{
see below
T}@T{
white
T}
T{
\f[C]STASH_TUI_COLOR_SORT_PATTERN\f[R]
T}@T{
color of sort/search text
T}@T{
see below
T}@T{
white
T}
T{
\f[C]BABASHKA_POD\f[R]
T}@T{
start as
babashka-pod (https://github.com/rorokimdim/stash#babashka-pod-support)
T}@T{
true, false
T}@T{
false
T}
T{
\f[C]EDITOR\f[R]
T}@T{
command for editing text
T}@T{
-
T}@T{
vim
T}
.TE
.PP
Color values can be one of \f[C]black\f[R], \f[C]red\f[R],
\f[C]green\f[R], \f[C]yellow\f[R], \f[C]blue\f[R], \f[C]magenta\f[R],
\f[C]cyan\f[R], \f[C]white\f[R], \f[C]brightBlack\f[R],
\f[C]brightRed\f[R], \f[C]brightGreen\f[R], \f[C]brightYellow\f[R],
\f[C]brightBlue\f[R], \f[C]brightMagenta\f[R], \f[C]brightCyan\f[R] and
\f[C]brightWhite\f[R].
.SS Shell Autocompletion
.SS bash
.PP
\f[C]source\f[R] output from following command
.IP
.nf
\f[C]
stash --bash-completion-script \[ga]which stash\[ga]
\f[R]
.fi
.SS zsh
.PP
Create a \f[C]_stash\f[R] in your $FPATH (try
\f[C]\[ti]/.zsh/_stash\f[R]) with contents from following command
.IP
.nf
\f[C]
stash --zsh-completion-script \[ga]which stash\[ga]
\f[R]
.fi
.SS fish
.PP
\f[C]source\f[R] output from following command
.IP
.nf
\f[C]
stash --fish-completion-script \[ga]which stash\[ga]
\f[R]
.fi
.SS Credits
.IP "1." 3
Haskell (https://www.haskell.org/)
.IP "2." 3
cryptonite (https://github.com/haskell-crypto/cryptonite) and
crypto-simple (https://github.com/Risto-Stevcev/haskell-crypto-simple)
.IP "3." 3
brick (https://hackage.haskell.org/package/brick) and
optparse-applicative (https://github.com/pcapriotti/optparse-applicative)
.IP "4." 3
All of these
libraries (https://github.com/rorokimdim/stash/blob/master/package.yaml#L20)
and all the things they depend on
.IP "5." 3
Every stash file is a sqlite (https://sqlite.org/) file
.IP "6." 3
Scriping support via clojure (https://clojure.org/) and
babashka (https://github.com/borkdude/babashka)