--- /dev/null
+.\" 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 make sure it encrypts or
+decrypts 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 key
+.B gpgdir
+uses to encrypt/decrypt a directory is specified in ~/.gpgdirrc.
+
+Finally,
+.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).
+
+.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-filename
+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.
+.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
projects / pgp-tools.git / blobdiff