gpgwrap(1)

💖 gpgwrap(1) — a small wrapper for gpg 💖

okay bestie, welcome to the General Commands Manual page for gpgwrap(1)! it's giving "tiny wrapper, big main character energy" fr fr. no cap, this little tool is here to help you feed passphrases to gpg without losing your mind. let's get into it 💅

---

🌸 NAME 🌸

gpgwrap — a small wrapper for gpg

---

✨ SYNOPSIS ✨

gpgwrap -V

gpgwrap -P [-v] [-i] [-a] [-p <file>]

gpgwrap -F [-v] [-i] [-a] [-c] [-p <file>] [-o <name>] [--] <file>
[<file> ... ]

gpgwrap [-v] [-i] [-a] [-p <file>] [-o <name>] [--] gpg [gpg options]

---

💅 DESCRIPTION 💅

okay so the GNU Privacy Guard (gpg) has this option called --passphrase-fd. it tells gpg to read the passphrase from whatever file descriptor you hand it. usually that file descriptor gets opened before gpg is executed via execvp(3). and that's literally exactly what gpgwrap does — it's the middleman, the bestie, the plug 🔌.

you can pass the passphrase to gpgwrap in 4 ways:

• as a file path, where the passphrase is stored as plain text in the file
• it is piped from another program to the stdin of gpgwrap
• through the GPGWRAP_PASSPHRASE environment variable
• gpgwrap prompts for it

with no precautions, that first point lowkey undermines the secure infrastructure gpg provides. but in pure batch oriented environments, this may be what you want. otherwise, if you're willing to enter passphrases once and don't want them stored as plain text in a file, gpg-agent is what you're looking for. another security objection could be the use of the environment variable GPGWRAP_PASSPHRASE, which contains the passphrase and may be read by other processes of the same user. so like, be careful bestie 💀

---

🎀 OPTIONS 🎀

• -V, --version — print out version and exit. that's it, that's the whole vibe.
• -P, --print — get the passphrase and print it mangled to stdout. it's giving "I'll show you but in a secret code" ✨
• -F, --file — read gpg commands from the given files. if <file> is - it is read from stdin. exactly one command per line is expected. the given line is handled in the following way:
  • in the first place the passphrase is mangled. this means that unusual characters are replaced by their backslash escaped octal numbers.
  • secondly the mangled passphrase is stored in the environment variable GPGWRAP_PASSPHRASE.
  • "exec gpgwrap -- " is prepended to each line, before the result is passed as argument to "sh -c".
• -h, --help — print out usage information. the classic "help me help you" move.
• -v, --verbose — increase verbosity level. more talk, more info, more drama.
• -i, --interactive — always prompt for passphrase (ignores -p and the environment variable). no shortcuts, just vibes.
• -a, --ask-twice — ask twice if prompting for a passphrase. double check, because we're extra like that 💅
• -c, --check-exit-code — while reading gpg commands from a file, gpgwrap 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, gpgwrap stops immediately and does return with this exit code. see also section BUGS.
• -p <file>, --passphrase-file <file> — read passphrase from <file>. if <file> 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 GPGWRAP_PASSPHRASE or it will be prompted on the controlling tty if the environment variable is not set.
• -o <name>, --option-name <name> — specify the name of the "--passphrase-fd" option understood by the program to be executed. this is useful if you want to use gpgwrap in combination with other programs than gpg.

---

🦋 LIMITATIONS 🦋

the given passphrase is subject to several limitations depending on the way it was passed to gpgwrap:

• there is a size limitation: the passphrase should be not larger than some kilobytes (examine the source code for the exact limit).
• gpgwrap allows you to use all characters in a passphrase even \000, but this does not mean that gpg will accept it. gpg may reject your passphrase or may only read a part of it, if it contains characters like \012 (in C also known as \n).
• if you set the environment variable GPGWRAP_PASSPHRASE you should take special care with the backslash character, because gpgwrap uses backslash to escape octal numbers, (see option -F). therefore write backslash itself as octal number: \134.

---

🌈 EXAMPLES 🌈

gpgwrap -p /path/to/a/secret/file  \
gpg -c -z 0 --batch --no-tty  \
    --cipher-algo blowfish < infile > outfile

read passphrase from /path/to/a/secret/file and execute gpg to do symmetric encryption of infile and write it to outfile.

gpgwrap -i -a  \
gpg -c -z 0 --batch --no-tty  \
    --cipher-algo blowfish < infile > outfile

same as above except that gpgwrap prompts twice for the passphrase.

gpgwrap -F -i - <<EOL
gpg --decrypt --batch --no-tty < "$HOME/infile1" > "$HOME/outfile1"
gpg --decrypt --batch --no-tty < "$HOME/infile2" > "$HOME/outfile2"
gpg --decrypt --batch --no-tty < "$HOME/infile3" > "$HOME/outfile3"
gpg --decrypt --batch --no-tty < "$HOME/infile4" > "$HOME/outfile4"
EOL

gpgwrap prompts for the passphrase and executes four instances of gpg to decrypt the given files.

GPGWRAP_PASSPHRASE="mysecretpassphrase"
export GPGWRAP_PASSPHRASE
gpgwrap -F -c -v /tmp/cmdfile1 - /tmp/cmdfile2 <<EOL
gpg --decrypt --batch --no-tty < "$HOME/infile1" > "$HOME/outfile1"
gpg --decrypt --batch --no-tty < "$HOME/infile2" > "$HOME/outfile2"
gpg --decrypt --batch --no-tty < "$HOME/infile3" > "$HOME/outfile3"
gpg --decrypt --batch --no-tty < "$HOME/infile4" > "$HOME/outfile4"
EOL

same as above except that gpgwrap gets the passphrase via the environment variable, reads commands additionally from other files and checks the exit code of every gpg instance. this means if one gpg command has a non zero exit code, no further commands are executed. furthermore gpgwrap produces verbose output.

GPGWRAP_PASSPHRASE="$(gpgwrap -P -i -a)"
export GPGWRAP_PASSPHRASE

find . -maxdepth 1 -type f |
while read FILE; do
    FILE2="$FILE.bz2.gpg"
    bzip2 -c "$FILE" |
    gpgwrap gpg -c -z 0 --batch --no-tty  \
        --cipher-algo blowfish > "$FILE2" &&
    touch -r "$FILE" "$FILE2" &&
    rm -f "$FILE"
done

read in passphrase, compress all files in the current directory, encrypt them and keep date from original file.

find . -maxdepth 1 -type f -name '*.bz2.gpg' |
awk '{
    printf("gpg --decrypt --batch --no-tty --quiet ");
    printf("--no-secmem-warning < %s\n", $0);
    }' |
gpgwrap -F -i -c - |
bzip2 -d -c - |
grep -i 'data'

decrypt all *.bz2.gpg files in the current directory, decompress them and print out all occurrences of data. if you pipe the result to less you get into trouble because gpgwrap and less 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).

GPGWRAP_PASSPHRASE="$(gpgwrap -P -i -a)"
export GPGWRAP_PASSPHRASE

gpgwrap -P |
ssh -C -x -P -l user host "
    GPGWRAP_PASSPHRASE=\"\$(cat)\"
    ...
    "

prompt for a passphrase twice and write it to the GPGWRAP_PASSPHRASE environment variable.

echo -n "Passphrase: "
stty -echo
read GPGWRAP_PASSPHRASE
echo
stty echo
export GPGWRAP_PASSPHRASE

another way to prompt manually for the passphrase. it was needed in combination with older versions of gpgwrap, because they did not upport -P. be aware that with this method no automatic conversion to backslash escaped octal numbers takes place.

echo "mysecretpassphrase" |
gpg --batch --no-tty --passphrase-fd 0  \
    --output outfile --decrypt infile

cheap method to give passphrase to gpg without gpgwrap. note that you can't use stdin to pass a file to gpg, because stdin is already used for the passphrase.

gpg --batch --no-tty  \
    --passphrase-fd 3 3< /path/to/a/secret/file  \
    < infile > outfile

this is a more advanced method to give the passphrase, it is equivalent to Option -p of gpgwrap. this example should at least work with the bash.

gpg --batch --no-tty --passphrase-fd 3  \
    3< <(echo "mysecretpassphrase")  \
    < infile > outfile

like above, but the passphrase is given directly. this example should at least work with the bash.

---

💀 BUGS 💀

in version 0.02 of gpgwrap the exit code of gpg was only returned if gpgwrap 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.

---

👀 SEE ALSO 👀

gpg, gpg-agent

---

👑 AUTHOR 👑

Karsten Scheibler

---

okay bestie, that's the whole page! this has been gpgwrap 0.04, from the General Commands Manual, manual page gpgwrap(1). stay encrypted, stay iconic 💖✨🦋