gpgwrap/doc/gpgwrap.1

   1 .ds Q" ""
   2 .de Vb
   3 .ft CW
   4 .nf
   5 .ne \\$1
   6 ..
   7 .de Ve
   8 .ft R
   9
  10 .fi
  11 ..
  12
  13 .TH gpgwrap 1 "gpgwrap 0.04"
  14
  15 .SH NAME
  16 gpgwrap \- a small wrapper for gpg
  17
  18 .SH SYNOPSIS
  19 .B gpgwrap
  20 \-V
  21
  22 .B gpgwrap
  23 \-P
  24 [\-v]
  25 [\-i]
  26 [\-a]
  27 [\-p \fI<file>\fR]
  28
  29 .B gpgwrap
  30 \-F
  31 [\-v]
  32 [\-i]
  33 [\-a]
  34 [\-c]
  35 [\-p \fI<file>\fR]
  36 [\-o \fI<name>\fR]
  37 [\-\-]
  38 \fI<file>\fR [\fI<file>\fR ... ]
  39
  40 .B gpgwrap
  41 [\-v]
  42 [\-i]
  43 [\-a]
  44 [\-p \fI<file>\fR]
  45 [\-o \fI<name>\fR]
  46 [\-\-]
  47 \fBgpg\fR [gpg options]
  48
  49 .SH DESCRIPTION
  50 .PP
  51 The GNU Privacy Guard (\fBgpg\fR) supplies the option \-\-passphrase\-fd. This instructs \fBgpg\fR to read the passphrase from the given file descriptor. Usually this file descriptor is opened before \fBgpg\fR is executed via \fBexecvp(3)\fR. Exactly that is what \fBgpgwrap\fR is doing. The passphrase may be passed to \fBgpgwrap\fR in 4 ways:
  52 .RS
  53 .IP * 2
  54 as file path, whereat the passphrase is stored as plain text in the file
  55 .IP * 2
  56 it is piped from another program to the stdin of \fBgpgwrap\fR
  57 .IP * 2
  58 through the \fBGPGWRAP_PASSPHRASE\fR environment variable
  59 .IP * 2
  60 \fBgpgwrap\fR prompts for it
  61 .RE
  62
  63 With no precautions the first point undermines the secure infrastructure \fBgpg\fR provides. But in pure batch oriented environments this may be what you want. Otherwise if you are willing to enter passphrases once and don't want them to be stored as plain text in a file \fBgpg\-agent\fR is what you are looking for. Another security objection could be the use of the environment variable \fBGPGWRAP_PASSPHRASE\fR which contains the passphrase and may be read by other processes of the same user.
  64
  65 .SH OPTIONS
  66 .IP "\-V, \-\-version" 8
  67 Print out version and exit.
  68 .IP "\-P, \-\-print" 8
  69 Get the passphrase and print it mangled to stdout.
  70 .IP "\-F, \-\-file" 8
  71 Read \fBgpg\fR commands from the given files. If \fI<file>\fR is \- it is read from stdin. Exactly one command per line is expected. The given line is handled in the following way:
  72 .RS
  73 .IP * 2
  74 In the first place the passphrase is mangled. This means that unusual characters are replaced by their backslash escaped octal numbers.
  75 .IP * 2
  76 Secondly the mangled passphrase is stored in the environment variable \fBGPGWRAP_PASSPHRASE\fR.
  77 .IP * 2
  78 \*(Q"exec gpgwrap \-\- \*(Q" is prepended to each line, before the result is passed as argument to \*(Q"sh \-c\*(Q".
  79 .RE
  80 .IP "\-h, \-\-help" 8
  81 Print out usage information.
  82 .IP "\-v, \-\-verbose" 8
  83 Increase verbosity level.
  84 .IP "\-i, \-\-interactive" 8
  85 Always prompt for passphrase (ignores \-p and the environment variable).
  86 .IP "\-a, \-\-ask\-twice" 8
  87 Ask twice if prompting for a passphrase.
  88 .IP "\-c, \-\-check\-exit\-code" 8
  89 While reading gpg commands from a file, \fBgpgwrap\fR ignores per default the exit code of its child processes. This option enables the check of the exit code. If a child terminates abnormal or with an exit code not equal 0 \fBgpgwrap\fR stops immediately and does return with this exit code. See also section \fBBUGS\fR.
  90 .IP "\-p \fI<file>\fR, \-\-passphrase\-file \fI<file>\fR" 8
  91 Read passphrase from \fI<file>\fR. If \fI<file>\fR is \- it is read from stdin. The passphrase is expected to be in plain text. If this option is not given the passphrase will be taken either from the environment variable \fBGPGWRAP_PASSPHRASE\fR or it will be prompted on the controlling tty if the environment variable is not set.
  92 .IP "\-o \fI<name>\fR, \-\-option\-name \fI<name>\fR" 8
  93 Specify the name of the \*(Q"\-\-passphrase\-fd\*(Q" option understood by the program to be executed. This is useful if you want to use \fBgpgwrap\fR in combination with other programs than \fBgpg\fR.
  94
  95 .SH LIMITATIONS
  96 The given passphrase is subject to several limitations depending on the way it was passed to \fBgpgwrap\fR:
  97 .RS
  98 .IP * 2
  99 There is a size limitation: the passphrase should be not larger than some kilobytes (examine the source code for the exact limit).
 100 .IP * 2
 101 \fBgpgwrap\fR allows you to use all characters in a passphrase even \\000, but this does not mean that \fBgpg\fR will accept it. \fBgpg\fR may reject your passphrase or may only read a part of it, if it contains characters like \\012 (in C also known as \\n).
 102 .IP * 2
 103 If you set the environment variable \fBGPGWRAP_PASSPHRASE\fR you should take special care with the backslash character, because \fBgpgwrap\fR uses backslash to escape octal numbers, (see option \-F). Therefore write backslash itself as octal number: \\134.
 104 .RE
 105
 106 .SH EXAMPLES
 107 .IP "1." 8
 108 .Vb
 109 \&\fBgpgwrap\fR \-p /path/to/a/secret/file  \\
 110 \&\fBgpg\fR \-c \-z 0 \-\-batch \-\-no\-tty  \\
 111 \&    \-\-cipher\-algo blowfish < infile > outfile
 112 .Ve
 113 Read passphrase from /path/to/a/secret/file and execute \fBgpg\fR to do symmetric encryption of infile and write it to outfile.
 114
 115 .IP "2." 8
 116 .Vb
 117 \&\fBgpgwrap\fR \-i \-a  \\
 118 \&\fBgpg\fR \-c \-z 0 \-\-batch \-\-no\-tty  \\
 119 \&    \-\-cipher\-algo blowfish < infile > outfile
 120 .Ve
 121 Same as above except that \fBgpgwrap\fR prompts twice for the passphrase.
 122
 123 .IP "3." 8
 124 .Vb
 125 \&\fBgpgwrap\fR \-F \-i \- <<EOL
 126 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile1\*(Q" > \*(Q"$HOME/outfile1\*(Q"
 127 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile2\*(Q" > \*(Q"$HOME/outfile2\*(Q"
 128 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile3\*(Q" > \*(Q"$HOME/outfile3\*(Q"
 129 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile4\*(Q" > \*(Q"$HOME/outfile4\*(Q"
 130 \&EOL
 131 .Ve
 132 \fBgpgwrap\fR prompts for the passphrase and executes four instances of \fBgpg\fR to decrypt the given files.
 133
 134 .IP "4." 8
 135 .Vb
 136 \&\fBGPGWRAP_PASSPHRASE\fR=\*(Q"mysecretpassphrase\*(Q"
 137 \&export \fBGPGWRAP_PASSPHRASE\fR
 138 \&\fBgpgwrap\fR \-F \-c \-v /tmp/cmdfile1 \- /tmp/cmdfile2 <<EOL
 139 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile1\*(Q" > \*(Q"$HOME/outfile1\*(Q"
 140 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile2\*(Q" > \*(Q"$HOME/outfile2\*(Q"
 141 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile3\*(Q" > \*(Q"$HOME/outfile3\*(Q"
 142 \&\fBgpg\fR \-\-decrypt \-\-batch \-\-no\-tty < \*(Q"$HOME/infile4\*(Q" > \*(Q"$HOME/outfile4\*(Q"
 143 \&EOL
 144 .Ve
 145 Same as above except that \fBgpgwrap\fR gets the passphrase via the environment variable, reads commands additionally from other files and checks the exit code of every \fBgpg\fR instance. This means if one \fBgpg\fR command has a non zero exit code, no further commands are executed. Furthermore \fBgpgwrap\fR produces verbose output.
 146
 147 .IP "5." 8
 148 .Vb
 149 \&\fBGPGWRAP_PASSPHRASE\fR=\*(Q"$(\fBgpgwrap\fR \-P \-i \-a)\*(Q"
 150 \&export \fBGPGWRAP_PASSPHRASE\fR
 151 \&
 152 \&\fBfind\fR . \-maxdepth 1 \-type f |
 153 \&while read FILE; do
 154 \&    FILE2=\*(Q"$FILE.bz2.gpg\*(Q"
 155 \&    \fBbzip2\fR \-c \*(Q"$FILE\*(Q" |
 156 \&    \fBgpgwrap\fR \fBgpg\fR \-c \-z 0 \-\-batch \-\-no\-tty  \\
 157 \&        \-\-cipher\-algo blowfish > \*(Q"$FILE2\*(Q" &&
 158 \&    \fBtouch\fR \-r \*(Q"$FILE\*(Q" \*(Q"$FILE2\*(Q" &&
 159 \&    \fBrm\fR \-f \*(Q"$FILE\*(Q"
 160 \&done
 161 .Ve
 162 Read in passphrase, compress all files in the current directory, encrypt them and keep date from original file.
 163
 164 .IP "6." 8
 165 .Vb
 166 \&\fBfind\fR . \-maxdepth 1 \-type f \-name '*.bz2.gpg' |
 167 \&\fBawk\fR '{
 168 \&    printf(\*(Q"gpg \-\-decrypt \-\-batch \-\-no\-tty \-\-quiet \*(Q");
 169 \&    printf(\*(Q"\-\-no\-secmem\-warning < %s\\n\*(Q", $0);
 170 \&    }' |
 171 \&\fBgpgwrap\fR \-F \-i \-c \- |
 172 \&\fBbzip2\fR \-d \-c \- |
 173 \&\fBgrep\fR \-i 'data'
 174 .Ve
 175 Decrypt all *.bz2.gpg files in the current directory, decompress them and print out all occurances of data. If you pipe the result to \fBless\fR you get into trouble because \fBgpgwrap\fR and \fBless\fR try to read from the TTY at the same time. In such a case it is better to use the environment variable to give the passphrase (the example above shows how to do this).
 176
 177 .IP "7." 8
 178 .Vb
 179 \&\fBGPGWRAP_PASSPHRASE\fR=\*(Q"$(\fBgpgwrap\fR \-P \-i \-a)\*(Q"
 180 \&export \fBGPGWRAP_PASSPHRASE\fR
 181 \&
 182 \&\fBgpgwrap\fR \-P |
 183 \&\fBssh\fR \-C \-x \-P \-l user host \*(Q"
 184 \&    \fBGPGWRAP_PASSPHRASE\fR=\\\*(Q"\\$(\fBcat\fR)\\\*(Q"
 185 \&    ...
 186 \&    \*(Q"
 187 .Ve
 188 Prompt for a passphrase twice and write it to the \fBGPGWRAP_PASSPHRASE\fR environment variable.
 189
 190 .IP "8." 8
 191 .Vb
 192 \&\fBecho\fR \-n \*(Q"Passphrase: \*(Q"
 193 \&\fBstty\fR \-echo
 194 \&read \fBGPGWRAP_PASSPHRASE\fR
 195 \&\fBecho\fR
 196 \&\fBstty\fR echo
 197 \&export \fBGPGWRAP_PASSPHRASE\fR
 198 .Ve
 199 Another way to prompt manually for the passphrase. It was needed in combination with older versions of \fBgpgwrap\fR, because they did not upport \-P. Be aware that with this method no automatic conversion to backslash escaped octal numbers takes place.
 200
 201 .IP "9." 8
 202 .Vb
 203 \&\fBecho\fR \*(Q"mysecretpassphrase\*(Q" |
 204 \&\fBgpg\fR \-\-batch \-\-no\-tty \-\-passphrase\-fd 0  \\
 205 \&    \-\-output outfile \-\-decrypt infile
 206 .Ve
 207 Cheap method to give passphrase to \fBgpg\fR without \fBgpgwrap\fR. Note that you can't use stdin to pass a file to \fBgpg\fR, because stdin is already used for the passphrase.
 208
 209 .IP "10." 8
 210 .Vb
 211 \&\fBgpg\fR \-\-batch \-\-no\-tty  \\
 212 \&    \-\-passphrase\-fd 3 3< /path/to/a/secret/file  \\
 213 \&    < infile > outfile
 214 .Ve
 215 This is a more advanced method to give the passphrase, it is equivalent to Option \-p of \fBgpgwrap\fR. This example should at least work with the bash.
 216
 217 .IP "11." 8
 218 .Vb
 219 \&\fBgpg\fR \-\-batch \-\-no\-tty \-\-passphrase\-fd 3  \\
 220 \&    3< <(echo \*(Q"mysecretpassphrase\*(Q")  \\
 221 \&    < infile > outfile
 222 .Ve
 223 Like above, but the passphrase is given directly. This example should at least work with the bash.
 224
 225 .SH BUGS
 226 In version 0.02 of \fBgpgwrap\fR the exit code of \fBgpg\fR was only returned if \fBgpgwrap\fR read the passphrase from a file. Since version 0.03, only \-F omits exit code checking by default, but it can be enabled with \-c.
 227
 228 .SH "SEE ALSO"
 229 \fBgpg\fR, \fBgpg\-agent\fR
 230
 231 .SH AUTHOR
 232 Karsten Scheibler