.TH pass-tomb 1 "June 2019" "pass-tomb"

.SH NAME
pass-tomb \- A \fBpass\fP(1) extension that helps to keep the whole tree of
password encrypted inside a \fBtomb\fP(1).

.SH SYNOPSIS
\fBpass tomb\fP [args] gpgid...
.br
\fBpass open \fP [args]
.br
\fBpass close\fP [args]

.SH DESCRIPTION
Due to the structure of \fBpass\fP(1), file- and directory names are not encrypted
in the password store. \fBpass tomb\fP provides a convenient solution to put your
password store in a \fBtomb\fP(1) and then keep your password tree encrypted
when you are not using it.

It uses the same GPG key to encrypt passwords and tomb, therefore you don't need
to manage more key or secret. Moreover, you can ask pass-tomb to automatically
close your store after a given time.

.TP
.B The new workflow is the following:
.IP
1. Create a password tomb with \fBpass tomb\fP. It creates a new tomb and opens it
in ~/.password-store. Then it initialises the password repository with the same
GPG key.
.IP
2. Use tomb as usual.
.IP
3. When finished close the password tomb: \fBpass close\fP.
.IP
4. To use pass again, you need to open the password tomb: \fBpass open\fP.


.SH COMMAND

.TP
\fBpass tomb\fP [ \fI--no-init\fP, \fI-n\fP ] [\fI--timer=time\fP, \fI-t time\fP]
   [ \fI--path=subfolder\fP, \fI-p subfolder\fP ] [\fI--force\fP, \fI-f\fP] \fIgpg-id...\fP

Create and initialise a new password tomb. This command must be run first,
before a password store can be used.

Use
.I gpg-id
for encryption of both passwords and tomb. Multiple gpg-ids may be specified,
in order to encrypt the tomb and each password with multiple ids.

If \fI--path\fP or \fI-p\fP is specified, along with an argument,
a specific password tomb using gpg-id or a set of gpg-ids is assigned for that
specific subfolder of the password store.

If \fI--no-init\fP, \fI-n\fP is specified, do not initialise the password store.
By default, pass-tomb initialises the password store with the same key(s) it
generated the tomb. The purpose of this option is to let the user free to
initialise the password store with a different key or set of keys.

If \fI--timer\fP, \fI-t\fP is specified, along with an argument, the password
store will be automatically closed using a systemd timer after a given time. This
time will be saved in the .timer file present in the store.

If \fI--force\fP is specified, the password store will create or mount the
password store even if a plain text swap is present. Make sure you know what you
are doing if you force an operation.

.TP
\fBpass open\fP [\fI--timer=time\fP, \fI-t time\fP] [\fI--force\fP, \fI-f\fP] [\fIsubfolder\fP]
Open a password tomb. If a .timer file is present in the store, a systemd timer
will be initialized.

If \fI--timer\fP, \fI-t\fP is specified, along with an argument, the password
store will be automatically closed using a systemd timer after a given time.
If a '.time' file was already present in the store, this time will be updated.
Multiple timer can be used in the same time.

If \fI--force\fP is specified, the password store will create or mount the
password store even if a plain text swap is present. Make sure you know what you
are doing if you force an operation.

If \fIsubfolder\fP is specified, the password store will be opened in the subfolder.

.TP
\fBpass close\fP [\fIstore\fP]
Close a password tomb.

If \fIstore\fP is specified, pass close will try to close this store.

.SH OPTIONS
.TP
\fB\-n\fB, \-\-no-init\fR
Do not initialise the password store

.TP
\fB\-t\fB, \-\-timer\fR
Close the store after a given time

.TP
\fB\-p\fB, \-\-path\fR
Create the store for that specific subfolder

.TP
\fB\-f\fB, \-\-force\fR
Force the tomb operations (i.e. even if swap is active)

.TP
\fB\-q\fB, \-\-quiet\fR
Be quiet

.TP
\fB\-v\fB, \-\-verbose\fR
Be verbose

.TP
\fB\-d\fB, \-\-debug\fR
Print tomb debug messages

.TP
\fB\-\-unsafe\fR
Speed up tomb creation (for testing purposes only)

.TP
\fB\-V\fB, \-\-version\fR
Show version information

.TP
\fB\-h\fB, \-\-help\fR
Show usage message


.SH EXAMPLES
.TP
Create a new password tomb
.B zx2c4@laptop ~ $ pass tomb Jason@zx2c4.com
.br
 (*) Your password tomb has been created and opened in ~/.password-store.
.br
 (*) Password store initialised for Jason@zx2c4.com.
.br
  .  Your tomb is: ~/.password.tomb
.br
  .  Your tomb key is: ~/.password.key.tomb
.br
  .  You can now use pass as usual.
.br
  .  When finished, close the password tomb using 'pass close'.

.TP
Open a password tomb
.B zx2c4@laptop ~ $ pass open
.br
 (*) Your password tomb has been opened in ~/.password-store.
.br
  .  You can now use pass as usual.
.br
  .  When finished, close the password tomb using 'pass close'.

.TP
Close a password tomb
.B zx2c4@laptop ~ $ pass close
.br
 (*) Your password tomb has been closed.
.br
  .  Your passwords remain present in ~/.password.tomb.

.TP
Create a new password tomb and set a timer
.B zx2c4@laptop ~ $ pass tomb Jason@zx2c4.com --timer=1h
.br
 (*) Your password tomb has been created and opened in ~/.password-store.
.br
 (*) Password store initialised for Jason@zx2c4.com.
.br
  .  Your tomb is: ~/.password.tomb
.br
  .  Your tomb key is: ~/.password.key.tomb
.br
  .  You can now use pass as usual.
.br
  .  This password store will be closed in 1h
.br
.B zx2c4@laptop ~ $ pass open
.br
 (*) Your password tomb has been opened in ~/.password-store.
.br
  .  You can now use pass as usual.
.br
  .  This password store will be closed in 1h

.TP
Open a password tomb and set a timer
.B zx2c4@laptop ~ $ pass open
.br
 (*) Your password tomb has been opened in ~/.password-store.
.br
  .  You can now use pass as usual.
.br
  .  This password store will be closed in 10min



.SH ENVIRONMENT VARIABLES
.TP
.I PASSWORD_STORE_TOMB
Path to tomb executable
.TP
.I PASSWORD_STORE_TOMB_FILE
Path to the password tomb, by default \fI~/.password.tomb\fP
.TP
.I PASSWORD_STORE_TOMB_KEY
Path to the password tomb key file by default \fI~/.password.key.tomb\fP
.TP
.I PASSWORD_STORE_TOMB_SIZE
Password tomb size in MB, by default \fI10\fP


.SH SEE ALSO
.BR pass(1),
.BR tomb(1),
.BR pass-import(1),
.BR pass-update(1),
.BR pass-audit(1),
.BR pass-otp(1)


.SH AUTHORS
.B pass tomb
was written by
.MT alexandre@pujol.io
Alexandre Pujol
.ME .


.SH COPYING
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.