gpgdir/gpgdir.1

   1 .\" Process this file with
   2 .\" groff -man -Tascii foo.1
   3 .\"
   4 .TH GPGDIR 1 "May, 2007" Linux
   5 .SH NAME
   6 .B gpgdir
   7 \- recursive directory encryption with GnuPG
   8 .SH SYNOPSIS
   9 .B gpgdir \-e|\-d <directory> [options]
  10 .SH DESCRIPTION
  11 .B gpgdir
  12 is a perl script that uses the CPAN GnuPG::Interface perl module to recursively
  13 encrypt and decrypt directories using gpg.
  14 .B gpgdir
  15 recursively descends through a directory in order to make sure it encrypts or
  16 decrypts every file in a directory and all of its subdirectories.  By default
  17 the mtime and atime values of all files will be preserved upon encryption and
  18 decryption (this can be disabled with the
  19 .B \-\-no-preserve-times
  20 option).  Note that in
  21 .B \-\-encrypt
  22 mode, gpgdir will delete the original files that
  23 it successfully encrypts (unless the
  24 .B \-\-no-delete
  25 option is given).  However,
  26 upon startup gpgdir first asks for a the decryption password to be sure that a
  27 dummy file can successfully be encrypted and decrypted.  The initial test can
  28 be disabled with the
  29 .B \-\-skip-test
  30 option so that a directory can easily be encrypted without having to also
  31 specify a password (this is consistent with
  32 .B gpg
  33 behavior).  Also, note that gpgdir is careful not encrypt hidden files and
  34 directories.  After all, you probably don't want your ~/.gnupg directory or
  35 ~/.bashrc file to be encrypted.  The key
  36 .B gpgdir
  37 uses to encrypt/decrypt a directory is specified in ~/.gpgdirrc.
  38
  39 Finally,
  40 .B gpgdir
  41 can use the
  42 .B wipe
  43 program with the
  44 .B \-\-Wipe
  45 command line option to securely delete the original unencrypted files after they
  46 have been successfully encrypted.  This elevates the security stance of gpgdir
  47 since it is more difficult to recover the unencrypted data associated with
  48 files from the filesystem after they are encrypted (unlink() does not erase data
  49 blocks even though a file is removed).
  50
  51 .SH OPTIONS
  52 .TP
  53 .BR \-e ", " \-\^\-encrypt\ \<directory>
  54 Recursively encrypt all files in the directory specified on the command line.
  55 All original files will be deleted (a password check is performed first to make
  56 sure that the correct password to unlock the private GnuPG key is known to the
  57 user).
  58 .TP
  59 .BR \-d ", " \-\^\-decrypt\ \<directory>
  60 Recursively decrypt all files in the directory specified on the command line.
  61 The encrypted .gpg version of each file will be deleted.
  62 .TP
  63 .BR \-\^\-sign\ \<directory>
  64 Recursively sign all files in the directory specified on the command line.  For
  65 each file, a detached .asc signature will be created.
  66 .TP
  67 .BR \-\^\-verify\ \<directory>
  68 Recursively verify all .asc signatures for files in the directory specified on the
  69 command line.
  70 .TP
  71 .BR \-g ", " \-\^\-gnupg-dir\ \<directory>
  72 Specify which .gnupg directory will be used to find GnuPG keys.  The default
  73 is ~/.gnupg if this option is not used.  This option allows gpgdir to be
  74 run as one user but use the keys of another user (assuming permissions are
  75 setup correctly, etc.).
  76 .TP
  77 .BR \-p ", " \-\^\-pw-file\ \<pw-file>
  78 Read decryption password from
  79 .B pw-file
  80 instead of typing it on the command line.
  81 .TP
  82 .BR \-t ", " \-\^\-test-mode
  83 Run an encryption and decryption test against a dummy file and exit.  This
  84 test is always run by default in both
  85 .B \-\-encrypt
  86 and
  87 .B \-\-decrypt
  88 mode.
  89 .TP
  90 .BR \-S ", " \-\^\-Symmetric
  91 Instruct
  92 .B gpgdir
  93 to encrypt to decrypt files using a symmetric cipher supported by GnuPG
  94 (CAST5 is commonly used).  This results in a significant speed up for the
  95 encryption/decryption process.
  96 .TP
  97 .BR \-T ", " \-\^\-Trial-run
  98 Show what encrypt/decrypt actions would take place without actually doing
  99 them.  The filesystem is not changed in any way in this mode.
 100 .TP
 101 .BR \-I ", " \-\^\-Interactive
 102 Prompt the user before actually encrypting or decrypting each file.  This
 103 is useful to have fine-grained control over
 104 .B gpgdir
 105 operations as it recurses through a directory structure.
 106 .TP
 107 .BR \-F ", " \-\^\-Force
 108 Tell
 109 .B gpgdir
 110 to ignore non-fatal error conditions, such as the inability to encrypt or
 111 decrypt individual files because of permissions errors.
 112 .TP
 113 .BR \-\^\-Exclude\ \<pattern>
 114 Instruct gpgdir to skip all files that match
 115 .B pattern
 116 as a regex match against each filename.  This is similar to the
 117 .B \-\-exclude
 118 option in the standard GNU tar command.
 119 .TP
 120 .BR \-\^\-Exclude-from\ \<file>
 121 Instruct gpgdir to exclude all files matched by patterns listed in
 122 .B file.
 123 This is similar to the
 124 .B \-\-exclude-from
 125 the GNU tar command.
 126 .TP
 127 .BR \-\^\-Include\ \<pattern>
 128 Instruct gpgdir to only include files that match
 129 .B pattern
 130 as a regex match against each filename.
 131 .TP
 132 .BR \-\^\-Include-from\ \<file>
 133 Instruct gpgdir to only include files matched by patterns listed in
 134 .B file.
 135 .TP
 136 .BR \-W ", " \-\^\-Wipe
 137 Use the
 138 .B wipe
 139 program to securely delete files after they have been successfully encrypted.
 140 .TP
 141 .BR \-O ", " \-\^\-Obfuscate-filename
 142 Tell
 143 .B gpgdir
 144 to obfuscate the file names of files that it encrypts (in \-e mode).  The
 145 names of each file are stored within the file .gpgdir_map_file for every
 146 sub-directory, and this file is itself encrypted.  In decryption mode (\-d),
 147 the \-O argument reverses the process so that the original files are
 148 restored.
 149 .TP
 150 .BR \-\^\-overwrite-encrypted
 151 Overwrite encrypted files even if a previous <file>.gpg file
 152 already exists.
 153 .TP
 154 .BR \-\^\-overwrite-decrypted
 155 Overwrite decrypted files even if the previous unencrypted file already exists.
 156 .TP
 157 .BR \-K ", " \-\^\-Key-id\ \<id>
 158 Manually specify a GnuPG key ID from the command line.  Because GnuPG
 159 supports matching keys with a string,
 160 .B id
 161 does not strictly have to be a key ID; it can be a string that uniquely
 162 matches a key in the GnuPG key ring.
 163 .TP
 164 .BR \-D ", " \-\^\-Default-key
 165 Use the key that GnuPG defines as the default, i.e. the key that is specified
 166 by the
 167 .B default-key
 168 variable in ~/.gnupg/options.  If the default-key variable is not defined
 169 within ~/.gnupg/options, then GnuPG tries to use the first suitable key on
 170 its key ring (the initial encrypt/decrypt test makes sure that the user
 171 knows the corresponding password for the key).
 172 .TP
 173 .BR \-a ", " " \-\^\-agent
 174 Instruct
 175 .B gpgdir
 176 to acquire gpg key password from a running
 177 .B gpg-agent
 178 instance.
 179 .TP
 180 .BR \-A ", " \-\^\-Agent-info\ \<connection\ \info>
 181 Specify the value of the GPG_AGENT_INFO environment variable as returned
 182 by the
 183 .B gpg-agent \-\-daemon
 184 command. If the
 185 .B gpgdir \-\-agent
 186 command line argument is used instead of
 187 .B \-\-Agent-info,
 188 then gpgdir assumes that the GPG_AGENT_INFO environment variable has already
 189 been set in the current shell.
 190 .TP
 191 .BR \-s ", " " \-\^\-skip-test
 192 Skip encryption and decryption test.  This will allow
 193 .B gpgdir
 194 to be used to encrypt a directory without specifying a password (which
 195 normally gets used in encryption mode to test to make sure decryption
 196 against a dummy file works properly).
 197 .TP
 198 .BR \-q ", " \-\^\-quiet
 199 Print as little as possible to the screen when encrypting or decrypting
 200 a directory.
 201 .TP
 202 .BR \-\^\-no-recurse
 203 Instruct gpgdir to not recurse through any subdirectories of the directory
 204 that is being encrypted or decrypted.
 205 .TP
 206 .BR \-\^\-no-password
 207 Instruct gpgdir to not ask the user for a password.  This is only useful
 208 when a gpg key literally has no associated password (this is not common).
 209 .TP
 210 .BR \-\^\-no-delete
 211 Instruct gpgdir to not delete original files at encrypt time.
 212 .TP
 213 .BR \-\^\-no-preserve times
 214 Instruct gpgdir to not preserve original file mtime and atime values
 215 upon encryption or decryption.
 216 .TP
 217 .BR \-l ", " " \-\^\-locale\ \<locale>
 218 Provide a locale setting other than the default "C" locale.
 219 .TP
 220 .BR \-\^\-no-locale
 221 Do not set the locale at all so that the default system locale will apply.
 222 .TP
 223 .BR \-v ", " \-\^\-verbose
 224 Run in verbose mode.
 225 .TP
 226 .BR \-V ", " \-\^\-Version
 227 Print version number and exit.
 228 .TP
 229 .BR \-h ", " \-\^\-help
 230 Print usage information and exit.
 231 .SH FILES
 232 .B ~/.gpgdirrc
 233 .RS
 234 Contains the key id of the user gpg key that will be used to encrypt
 235 or decrypt the files within a directory.
 236 .RE
 237 .PP
 238 .SH EXAMPLES
 239 The following examples illustrate the command line arguments that could
 240 be supplied to gpgdir in a few situations:
 241 .PP
 242 To encrypt a directory:
 243 .PP
 244 .B $ gpgdir \-e /some/dir
 245 .PP
 246 To encrypt a directory, and use the wipe command to securely delete the original
 247 unencrypted files:
 248 .PP
 249 .B $ gpgdir \-W \-e /some/dir
 250 .PP
 251 To encrypt a directory with the default GnuPG key defined in ~/.gnupg/options:
 252 .PP
 253 .B $ gpgdir \-e /some/dir \-\-Default-key
 254 .PP
 255 To decrypt a directory with a key specified in ~/.gpgdirrc:
 256 .PP
 257 .B $ gpgdir \-d /some/dir
 258 .PP
 259 To encrypt a directory but skip all filenames that contain the string "host":
 260 .PP
 261 .B $ gpgdir \-e /some/dir \-\-Exclude host
 262 .PP
 263 To encrypt a directory but only encrypt those files that contain the string "passwd":
 264 .PP
 265 .B $ gpgdir \-e /some/dir \-\-Include passwd
 266 .PP
 267 To acquire the GnuPG key password from a running gpg-agent daemon in order to decrypt
 268 a directory (this requires that gpg-agent has the password):
 269 .PP
 270 .B $ gpgdir \-A /tmp/gpg-H4DBhc/S.gpg-agent:7046:1 \-d /some/dir
 271 .PP
 272 To encrypt a directory but skip the encryption/decryption test (so you will
 273 not be prompted for a decryption password):
 274 .PP
 275 .B $ gpgdir \-e /some/dir \-s
 276 .PP
 277 To encrypt a directory and no subdirectories:
 278 .PP
 279 .B $ gpgdir \-e /some/dir \-\-no-recurse
 280 .PP
 281 To encrypt root's home directory, but use the GnuPG keys associated with the user "bob":
 282 .PP
 283 .B # gpgdir \-e /root \-g /home/bob/.gnupg
 284 .PP
 285 .SH DEPENDENCIES
 286 .B gpgdir
 287 requires that gpg, the Gnu Privacy Guard (http://www.gnupg.org) is installed.
 288 .B gpgdir
 289 also requires the GnuPG::Interface perl module from CPAN, but it is bundled with
 290 .B gpgdir
 291 and is installed in /usr/lib/gpgdir at install-time so it does not pollute the
 292 system perl library tree.
 293
 294 .SH "SEE ALSO"
 295 .BR gpg (1)
 296
 297 .SH AUTHOR
 298 Michael Rash <mbr@cipherdyne.org>
 299
 300 .SH CONTRIBUTORS
 301 Many people who are active in the open source community have contributed to gpgdir;
 302 see the
 303 .B CREDITS
 304 file in the gpgdir sources.
 305
 306
 307 .SH BUGS
 308 Send bug reports to mbr@cipherdyne.org. Suggestions and/or comments are
 309 always welcome as well.
 310
 311 .SH DISTRIBUTION
 312 .B gpgdir
 313 is distributed under the GNU General Public License (GPL), and the latest
 314 version may be downloaded from
 315 .B http://www.cipherdyne.org