Ubuntu Manpage: guncat - catenates files, unencrypting pgp encrypted sections

Provided by: guncat_1.02.00-2build1_amd64

NAME

       guncat - catenates files, unencrypting pgp encrypted sections

SYNOPSIS

       guncat [OPTIONS] [file(s)]
       [OPTIONS] - cf. section OPTIONS
       [file(s)] - optional files to process (cf. section INPUT FILE(S))

DESCRIPTION

Guncat was designed to tackle a problem encountered with (partially) PGP encrypted files (which may be
encountered in, e.g., mailboxes). Tools to process text-files (like grep(1), or less(1)) may be used to
process those files, but standard tools like cat(1) leave PGP encrypted sections within such files as-is.
As a consequence, browsing the `real’ contents (i.e., clear-text sections and the unencrypted contents of
PGP encrypted sections) of those files is difficult.

Guncat acts comparably to cat, but unencrypts encrypted sections encountered in the files processed by
guncat, copying the unencrypted information to guncat’s standard output stream, which may thereupon be
processed by other tools.

PGP/GPG encrypted sections are surrounded by

-----BEGIN PGP MESSAGE-----
and

-----END PGP MESSAGE-----
markers. Whenever guncat encounters such sections they will be processed by gpg(1). Gpg needs a
passphrase to unencrypt such sections. The required passphrase may be provided to guncat, which then
forwards the passphrase to gpg.

When providing an incorrect passphrase to guncat two additional attempts to provide the correct
passphrase are provided. If the third attempt also fails, guncat terminates. Furthermore, when an
incorrect passphrase is provided, the currently processed file must be reset to the beginning of the
encrypted section. This implies that the processed file must be seekable. If the file does not support
seeking operations then guncat also terminates.

RETURN VALUE

       Guncat  returns  0  to  the  operating  system unless an error occurs (0 is also returned when the option
       --show-gpg) is specified.

INPUT FILE(S)

       When no file arguments are provided (or when - is provided) the standard input stream is processed.

       When option --passphrase is specified the first line of the first file that is processed is read  as  the
       passphrase to use. When a thus specified passphrase is incorrect, guncat terminates.

       Any  other argument is considered a file (path specifications are allowed) to be processed in sequence by
       guncat.

       If an argument does not refer to a readable file, guncat terminates with an error message.

OPTIONS

Where available, single letter options are listed between parentheses following their associated
long-option variants. Single letter options require arguments if their associated long options require
arguments as well.

o --errors-OK
When specifying the option --errors-OK the input s continue to be processed even if gpg returns a
non-zero exit value.

o --gpg=path
Path to the gpg program (default: /usr/bin/gpg)

o --gpg-msg=path (-m)
Path to where gpg and guncat should write messages. Specify - to write the messages to the
standard error stream. By default messages are suppressed.

o --gpg-no-batch
Starting with guncat version 1.02.00 this option is not used anymore. It will be removed in a
future vestion.

o --gpg-option=option (-m)
Add option to gpg’s call. If the option contains blanks, surround option by single or double
quotes. Option gpg-option may repeatedly be specified.

o --help (-h)
Basic usage information is written to the standard output stream.

o --locate-keys -l
Starting with gpg version 1.02.00 this option is not used anymore. It will be removed in a future
vestion.

o --passphrase -p
By default the passphrase is read by guncat after prompting the user to enter the passphrase. The
passphrase is not echoed. If input redirection is used or if input files are specified option
--passphrase can be specified to read the passphrase from the first line of the first input stream
that is read by guncat. In that case the input stream’s first line is (of course) not written to
the output stream. When the --passphrase option is specified and the provided password is
incorrect, guncat terminates.

o --show-gpg
Show the gpg command that would be used, and quit, returning 0.

o --time-limit=seconds (-T)
Option --time-limit is used to specify the max. time in seconds that gpg is allowed to run while
decrypting a single encrypted section. By default no time limit is used. This option is useful
when the file to process might contain errors in encrypted sections (like a missing END PGP
MESSAGE line).

o --tty-OK -t
Option --no-tty is not specified when calling gpg. By default it is specified.

o --verbose=[0-2]
Specifies gpg’s verbosity level. When calling gpg, by default --quiet is specified; with --verbose
0 gpg’s option --no-verbose is specified; otherwise --verbose is specified once or twice.

o --version (-v)
Guncat’s version number is written to the standard output stream.

BUGS

       None reported

COPYRIGHT

       This is free software, distributed under the terms of the `GNU General Public License’. Copyright remains
       with the author. Guncat is available at https://fbb-git.gitlab.io/guncat/

ORGANIZATION

       Center for Information Technology, University of Groningen.

AUTHOR

           Frank B. Brokken (f.b.brokken@rug.nl).

guncat_1.02.00.tar.gz                               2014-2018                                          guncat(1)