gpgdir.1

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH GPGDIR 1 "May, 2007" Linux
.SH NAME
.B gpgdir
\- recursive directory encryption with GnuPG
.SH SYNOPSIS
.B gpgdir \-e|\-d <directory> [options]
.SH DESCRIPTION
.B gpgdir
is a perl script that uses the CPAN GnuPG::Interface perl module to recursively
encrypt and decrypt directories using gpg.
.B gpgdir
recursively descends through a directory in order to encrypt, decrypt, sign, or
verify every file in a directory and all of its subdirectories.  By default,
the mtime and atime values of all files will be preserved upon encryption and
decryption (this can be disabled with the
.B \-\-no-preserve-times
option).  Note that in
.B \-\-encrypt
mode, gpgdir will delete the original files that
it successfully encrypts (unless the
.B \-\-no-delete
option is given).  However,
upon startup gpgdir first asks for a the decryption password to be sure that a
dummy file can successfully be encrypted and decrypted.  The initial test can
be disabled with the
.B \-\-skip-test
option so that a directory can easily be encrypted without having to also
specify a password (this is consistent with
.B gpg
behavior).  Also, note that gpgdir is careful not encrypt hidden files and
directories.  After all, you probably don't want your ~/.gnupg directory or
~/.bashrc file to be encrypted.  The GnuPG key
.B gpgdir
uses to encrypt/decrypt a directory is specified in ~/.gpgdirrc.  Also,
.B gpgdir
can use the
.B wipe
program with the
.B \-\-Wipe
command line option to securely delete the original unencrypted files after they
have been successfully encrypted.  This elevates the security stance of gpgdir
since it is more difficult to recover the unencrypted data associated with
files from the filesystem after they are encrypted (unlink() does not erase data
blocks even though a file is removed).

Note that
.B gpgdir
is not designed to be a replacement for an encrypted filesystem solution like
.B encfs
or
.B ecryptfs.
Rather, it is an alternative that allows one to take advantage of the cryptographic
properties offered by GnuPG in a recursive manner across an existing filesystem.

.SH OPTIONS
.TP
.BR \-e ", " \-\^\-encrypt\ \<directory>
Recursively encrypt all files in the directory specified on the command line.
All original files will be deleted (a password check is performed first to make
sure that the correct password to unlock the private GnuPG key is known to the
user).
.TP
.BR \-d ", " \-\^\-decrypt\ \<directory>
Recursively decrypt all files in the directory specified on the command line.
The encrypted .gpg version of each file will be deleted.
.TP
.BR \-\^\-sign\ \<directory>
Recursively sign all files in the directory specified on the command line.  For
each file, a detached .asc signature will be created.
.TP
.BR \-\^\-verify\ \<directory>
Recursively verify all .asc signatures for files in the directory specified on the
command line.
.TP
.BR \-g ", " \-\^\-gnupg-dir\ \<directory>
Specify which .gnupg directory will be used to find GnuPG keys.  The default
is ~/.gnupg if this option is not used.  This option allows gpgdir to be
run as one user but use the keys of another user (assuming permissions are
setup correctly, etc.).
.TP
.BR \-p ", " \-\^\-pw-file\ \<pw-file>
Read decryption password from
.B pw-file
instead of typing it on the command line.
.TP
.BR \-t ", " \-\^\-test-mode
Run an encryption and decryption test against a dummy file and exit.  This
test is always run by default in both
.B \-\-encrypt
and
.B \-\-decrypt
mode.
.TP
.BR \-S ", " \-\^\-Symmetric
Instruct
.B gpgdir
to encrypt to decrypt files using a symmetric cipher supported by GnuPG
(CAST5 is commonly used).  This results in a significant speed up for the
encryption/decryption process.
.TP
.BR \-T ", " \-\^\-Trial-run
Show what encrypt/decrypt actions would take place without actually doing
them.  The filesystem is not changed in any way in this mode.
.TP
.BR \-I ", " \-\^\-Interactive
Prompt the user before actually encrypting or decrypting each file.  This
is useful to have fine-grained control over
.B gpgdir
operations as it recurses through a directory structure.
.TP
.BR \-F ", " \-\^\-Force
Tell
.B gpgdir
to ignore non-fatal error conditions, such as the inability to encrypt or
decrypt individual files because of permissions errors.
.TP
.BR \-\^\-Exclude\ \<pattern>
Instruct gpgdir to skip all files that match
.B pattern
as a regex match against each filename.  This is similar to the
.B \-\-exclude
option in the standard GNU tar command.
.TP
.BR \-\^\-Exclude-from\ \<file>
Instruct gpgdir to exclude all files matched by patterns listed in
.B file.
This is similar to the
.B \-\-exclude-from
the GNU tar command.
.TP
.BR \-\^\-Include\ \<pattern>
Instruct gpgdir to only include files that match
.B pattern
as a regex match against each filename.
.TP
.BR \-\^\-Include-from\ \<file>
Instruct gpgdir to only include files matched by patterns listed in
.B file.
.TP
.BR \-W ", " \-\^\-Wipe
Use the
.B wipe
program to securely delete files after they have been successfully encrypted.
.TP
.BR \-O ", " \-\^\-Obfuscate-filenames
Tell
.B gpgdir
to obfuscate the file names of files that it encrypts (in \-e mode).  The
names of each file are stored within the file .gpgdir_map_file for every
sub-directory, and this file is itself encrypted.  In decryption mode (\-d),
the \-O argument reverses the process so that the original files are
restored.  Directory names are also obfuscated (except for the top level
directory), and stored within the .gpgdir_dir_map_file, and this file itself
is also encrypted/decrypted respectively in \-e and \-d mode.
.TP
.BR \-\^\-overwrite-encrypted
Overwrite encrypted files even if a previous <file>.gpg file
already exists.
.TP
.BR \-\^\-overwrite-decrypted
Overwrite decrypted files even if the previous unencrypted file already exists.
.TP
.BR \-K ", " \-\^\-Key-id\ \<id>
Manually specify a GnuPG key ID from the command line.  Because GnuPG
supports matching keys with a string,
.B id
does not strictly have to be a key ID; it can be a string that uniquely
matches a key in the GnuPG key ring.
.TP
.BR \-D ", " \-\^\-Default-key
Use the key that GnuPG defines as the default, i.e. the key that is specified
by the
.B default-key
variable in ~/.gnupg/options.  If the default-key variable is not defined
within ~/.gnupg/options, then GnuPG tries to use the first suitable key on
its key ring (the initial encrypt/decrypt test makes sure that the user
knows the corresponding password for the key).
.TP
.BR \-a ", " " \-\^\-agent
Instruct
.B gpgdir
to acquire gpg key password from a running
.B gpg-agent
instance.
.TP
.BR \-A ", " \-\^\-Agent-info\ \<connection\ \info>
Specify the value of the GPG_AGENT_INFO environment variable as returned
by the
.B gpg-agent \-\-daemon
command. If the
.B gpgdir \-\-agent
command line argument is used instead of
.B \-\-Agent-info,
then gpgdir assumes that the GPG_AGENT_INFO environment variable has already
been set in the current shell.
.TP
.BR \-s ", " " \-\^\-skip-test
Skip encryption and decryption test.  This will allow
.B gpgdir
to be used to encrypt a directory without specifying a password (which
normally gets used in encryption mode to test to make sure decryption
against a dummy file works properly).
.TP
.BR \-q ", " \-\^\-quiet
Print as little as possible to the screen when encrypting or decrypting
a directory.
.TP
.BR \-\^\-no-recurse
Instruct gpgdir to not recurse through any subdirectories of the directory
that is being encrypted or decrypted.
.TP
.BR \-\^\-no-password
Instruct gpgdir to not ask the user for a password.  This is only useful
when a gpg key literally has no associated password (this is not common).
.TP
.BR \-\^\-no-delete
Instruct gpgdir to not delete original files at encrypt time.
.TP
.BR \-\^\-no-preserve times
Instruct gpgdir to not preserve original file mtime and atime values
upon encryption or decryption.
.TP
.BR \-l ", " " \-\^\-locale\ \<locale>
Provide a locale setting other than the default "C" locale.
.TP
.BR \-\^\-no-locale
Do not set the locale at all so that the default system locale will apply.
.TP
.BR \-v ", " \-\^\-verbose
Run in verbose mode.
.TP
.BR \-V ", " \-\^\-Version
Print version number and exit.
.TP
.BR \-h ", " \-\^\-help
Print usage information and exit.
.SH FILES
.B ~/.gpgdirrc
.RS
Contains the key id of the user gpg key that will be used to encrypt
or decrypt the files within a directory.
.RE
.PP
.SH EXAMPLES
The following examples illustrate the command line arguments that could
be supplied to gpgdir in a few situations:
.PP
To encrypt a directory:
.PP
.B $ gpgdir \-e /some/dir
.PP
To encrypt a directory, and use the wipe command to securely delete the original
unencrypted files:
.PP
.B $ gpgdir \-W \-e /some/dir
.PP
To encrypt a directory with the default GnuPG key defined in ~/.gnupg/options:
.PP
.B $ gpgdir \-e /some/dir \-\-Default-key
.PP
To decrypt a directory with a key specified in ~/.gpgdirrc:
.PP
.B $ gpgdir \-d /some/dir
.PP
To encrypt a directory but skip all filenames that contain the string "host":
.PP
.B $ gpgdir \-e /some/dir \-\-Exclude host
.PP
To encrypt a directory but only encrypt those files that contain the string "passwd":
.PP
.B $ gpgdir \-e /some/dir \-\-Include passwd
.PP
To acquire the GnuPG key password from a running gpg-agent daemon in order to decrypt
a directory (this requires that gpg-agent has the password):
.PP
.B $ gpgdir \-A /tmp/gpg-H4DBhc/S.gpg-agent:7046:1 \-d /some/dir
.PP
To encrypt a directory but skip the encryption/decryption test (so you will
not be prompted for a decryption password):
.PP
.B $ gpgdir \-e /some/dir \-s
.PP
To encrypt a directory and no subdirectories:
.PP
.B $ gpgdir \-e /some/dir \-\-no-recurse
.PP
To encrypt root's home directory, but use the GnuPG keys associated with the user "bob":
.PP
.B # gpgdir \-e /root \-g /home/bob/.gnupg
.PP
.SH DEPENDENCIES
.B gpgdir
requires that gpg, the Gnu Privacy Guard (http://www.gnupg.org) is installed.
.B gpgdir
also requires the GnuPG::Interface perl module from CPAN, but it is bundled with
.B gpgdir
and is installed in /usr/lib/gpgdir at install-time so it does not pollute the
system perl library tree.

.SH "SEE ALSO"
.BR gpg (1)

.SH AUTHOR
Michael Rash <mbr@cipherdyne.org>

.SH CONTRIBUTORS
Many people who are active in the open source community have contributed to gpgdir;
see the
.B CREDITS
file in the gpgdir sources.


.SH BUGS
Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments are
always welcome as well.

.SH DISTRIBUTION
.B gpgdir
is distributed under the GNU General Public License (GPL), and the latest
version may be downloaded from
.B http://www.cipherdyne.org