Imported Upstream version 7.3.15upstream/7.3.15

4 files changed, 385 insertions, 2 deletions

diff --git a/tools/Makefile.am b/tools/Makefile.am
index 9a1497c..721992f 100644
--- a/tools/Makefile.am
+++ b/tools/Makefile.am
@@ -47,7 +47,9 @@ rsyslogd_LDFLAGS = -export-dynamic
 
 EXTRA_DIST = $(man_MANS) \
 	rsgtutil.rst \
+	rsgtutil.1 \
 	rscryutil.rst \
+	rscryutil.1 \
 	recover_qi.pl
 
 if ENABLE_DIAGTOOLS
diff --git a/tools/Makefile.in b/tools/Makefile.in
index f335183..9108b04 100644
--- a/tools/Makefile.in
+++ b/tools/Makefile.in
@@ -415,8 +415,8 @@ rsyslogd_CPPFLAGS = $(PTHREADS_CFLAGS) $(RSRT_CFLAGS)
 # potentially incomplete build, a problem we had several times...)
 rsyslogd_LDADD = ../grammar/libgrammar.la ../runtime/librsyslog.la $(ZLIB_LIBS) $(PTHREADS_LIBS) $(RSRT_LIBS) $(SOL_LIBS) $(LIBEE_LIBS) $(LIBLOGNORM_LIBS) $(LIBUUID_LIBS) $(LIBGCRYPT_LIBS)
 rsyslogd_LDFLAGS = -export-dynamic
-EXTRA_DIST = $(man_MANS) rsgtutil.rst rscryutil.rst recover_qi.pl \
-	$(am__append_6) $(am__append_10)
+EXTRA_DIST = $(man_MANS) rsgtutil.rst rsgtutil.1 rscryutil.rst \
+	rscryutil.1 recover_qi.pl $(am__append_6) $(am__append_10)
 @ENABLE_DIAGTOOLS_TRUE@rsyslog_diag_hostname_SOURCES = gethostn.c
 @ENABLE_DIAGTOOLS_TRUE@zpipe_SOURCES = zpipe.c
 @ENABLE_DIAGTOOLS_TRUE@zpipe_LDADD = -lz
diff --git a/tools/rscryutil.1 b/tools/rscryutil.1
new file mode 100644
index 0000000..cd6dc9d
--- /dev/null
+++ b/tools/rscryutil.1
@@ -0,0 +1,202 @@
+.\" Man page generated from reStructeredText.
+.
+.TH RSCRYUTIL 1 "2013-04-15" "" ""
+.SH NAME
+rscryutil \- Manage Encrypted Log Files
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+.nf
+.ft C
+rscryutil [OPTIONS] [FILE] ...
+.ft P
+.fi
+.SH DESCRIPTION
+.sp
+This tool performs various operations on encrypted log files.
+Most importantly, it provides the ability to decrypt them.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-d,  \-\-decrypt
+Select decryption mode. This is the default mode.
+.TP
+.BI \-W,  \-\-write\-keyfile \ <file>
+Utility function to write a key to a keyfile. The key can be obtained
+via any method.
+.TP
+.B \-v,  \-\-verbose
+Select verbose mode.
+.TP
+.B \-f,  \-\-force
+Forces operations that otherwise would fail.
+.TP
+.BI \-k,  \-\-keyfile \ <file>
+Reads the key from <file>. File _must_ contain the key, only, no headers
+or other meta information. Keyfiles can be generated via the
+\fI\-\-write\-keyfile\fP option.
+.TP
+.BI \-p,  \-\-key\-program \ <path\-to\-program>
+In this mode, the key is provided by a so\-called "key program". This program
+is executed and must return the key to (as well as some meta information)
+via stdout. The core idea of key programs is that using this interface the
+user can implement as complex (and secure) method to obtain keys as
+desired, all without the need to make modifications to rsyslog.
+.TP
+.BI \-K,  \-\-key \ <KEY>
+TESTING AID, NOT FOR PRODUCTION USE. This uses the KEY specified
+on the command line. This is the actual key, and as such this mode
+is highly insecure. However, it can be useful for intial testing
+steps. This option may be removed in the future.
+.TP
+.BI \-a,  \-\-algo \ <algo>
+Sets the encryption algorightm (cipher) to be used. See below
+for supported algorithms. The default is "AES128".
+.TP
+.BI \-m,  \-\-mode \ <mode>
+Sets the ciphermode to be used. See below for supported modes.
+The default is "CBC".
+.TP
+.BI \-r,  \-\-generate\-random\-key \ <bytes>
+Generates a random key of length <bytes>. This option is
+meant to be used together with \fI\-\-write\-keyfile\fP (and it is hard
+to envision any other valid use for it).
+.UNINDENT
+.SH OPERATION MODES
+.sp
+The operation mode specifies what exactly the tool does with the provided
+files. The default operation mode is "dump", but this may change in the future.
+Thus, it is recommended to always set the operations mode explicitely. If
+multiple operations mode are set on the command line, results are
+unpredictable.
+.SS decrypt
+.sp
+The provided log files are decrypted. Note that the \fI.encinfo\fP side files
+must exist and be accessible in order for decryption to to work.
+.SS write\-keyfile
+.sp
+In this mode no log files are processed; thus it is an error to specify
+any on the command line. The specified keyfile is written. The key itself
+is obtained via the usual key commands. If \fI\-\-keyfile\fP is used, that
+file is effectively copied.
+.sp
+For security reasons, existing key files are _not_ overwritten. To permit
+this, specify the \fI\-\-force\fP option. When doing so, keep in mind that lost
+keys cannot be recovered and data encrypted with them may also be considered
+lost.
+.sp
+Keyfiles are always created with 0400 permission, that is read access for only
+the user. An exception is when an existing file is overwritten via the
+\fI\-\-force\fP option, in which case the former permissions still apply.
+.SH EXIT CODES
+.sp
+The command returns an exit code of 0 if everything went fine, and some
+other code in case of failures.
+.SH SUPPORTED ALGORITHMS
+.sp
+We basically support what libgcrypt supports. This is:
+.INDENT 0.0
+.INDENT 3.5
+3DES
+CAST5
+BLOWFISH
+AES128
+AES192
+AES256
+TWOFISH
+TWOFISH128
+ARCFOUR
+DES
+SERPENT128
+SERPENT192
+SERPENT256
+RFC2268_40
+SEED
+CAMELLIA128
+CAMELLIA192
+CAMELLIA256
+.UNINDENT
+.UNINDENT
+.SH SUPPORTED CIPHER MODES
+.sp
+We basically support what libgcrypt supports. This is:
+.INDENT 0.0
+.INDENT 3.5
+ECB
+CFB
+CBC
+STREAM
+OFB
+CTR
+AESWRAP
+.UNINDENT
+.UNINDENT
+.SH EXAMPLES
+.sp
+\fBrscryutil logfile\fP
+.sp
+Decrypts "logfile" and sends data to stdout.
+.sp
+\fBrscryutil \-\-generate\-random\-key 16 \-\-keyfile /some/secured/path/keyfile\fP
+.sp
+Generates random key and stores it in the specified keyfile.
+.SH LOG SIGNATURES
+.sp
+Encrypted log files can be used together with signing. To verify such a file,
+it must be decrypted first, and the verification tool \fBrsgtutil(1)\fP must be
+run on the decrypted file.
+.SH SECURITY CONSIDERATIONS
+.sp
+Specifying keys directly on the command line (\fI\-\-key\fP option) is very
+insecure and should
+not be done, except for testing purposes with test keys. Even then it is
+recommended to use keyfiles, which are also easy to handle during testing.
+Keep in mind that command history is usally be kept by bash and can also
+easily be monitored.
+.sp
+Local keyfiles are also a security risk. At a minimum, they should be
+used with very restrictive file permissions. For this reason,
+the \fIrscryutil\fP tool creates them with read permissions for the user,
+only, no matter what umask is set to.
+.sp
+When selecting cipher algorithms and modes, care needs to be taken. The
+defaults should be reasonable safe to use, but this tends to change over
+time. Keep up with the most current crypto recommendations.
+.SH SEE ALSO
+.sp
+\fBrsgtutil(1)\fP, \fBrsyslogd(8)\fP
+.SH COPYRIGHT
+.sp
+This page is part of the \fIrsyslog\fP project, and is available under
+LGPLv2.
+.SH AUTHOR
+Rainer Gerhards <rgerhards@adiscon.com>
+.\" Generated by docutils manpage writer.
+.\" 
+.
diff --git a/tools/rsgtutil.1 b/tools/rsgtutil.1
new file mode 100644
index 0000000..5543a11
--- /dev/null
+++ b/tools/rsgtutil.1
@@ -0,0 +1,179 @@
+.\" Man page generated from reStructeredText.
+.
+.TH RSGTUTIL 1 "2013-03-25" "" ""
+.SH NAME
+rsgtutil \- Manage (GuardTime) Signed Log Files
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.SH SYNOPSIS
+.sp
+.nf
+.ft C
+rsgtutil [OPTIONS] [FILE] ...
+.ft P
+.fi
+.SH DESCRIPTION
+.sp
+This tool performs various maintenance operations on signed log files.
+It specifically supports the GuardTime signature provider.
+.sp
+The \fIrsgtutil\fP tool is the primary tool to verify log file signatures,
+dump signature file contents and carry out other maintenance operations.
+The tool offers different operation modes, which are selected via
+command line options.
+.sp
+The processing of multiple files is permitted. Depending on operation
+mode, either the signature file or the base log file must be specified.
+Within a single call, only a single operations mode is permitted. To
+use different modes on different files, multiple calles, one for each
+mode, must be made.
+.sp
+If no file is specified on the command line, stdin is used instead. Note
+that not all operation modes support stdin.
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-D,  \-\-dump
+Select "dump" operations mode.
+.TP
+.B \-t,  \-\-verify
+Select "verify" operations mode.
+.TP
+.B \-T,  \-\-detect\-file\-type
+Select "detect\-file\-type" operations mode.
+.TP
+.B \-B,  \-\-show\-sigblock\-params
+Select "show\-sigblock\-params" operations mode.
+.TP
+.B \-s,  \-\-show\-verified
+Prints out information about correctly verified blocks (by default, only
+errors are printed).
+.TP
+.B \-v,  \-\-verbose
+Select verbose mode. Most importantly, hashes and signatures are printed
+in full length (can be \fBvery\fP lengthy) rather than the usual abbreviation.
+.TP
+.B \-e,  \-\-extend
+Select extend mode. This extends the RFC3161 signatures. Note that this
+mode also implies a full verification. If there are verify errors, extending
+will also fail.
+.TP
+.BI \-P \ <URL>, \ \-\-publications\-server \ <URL>
+Sets the publications server. If not set but required by the operation a
+default server is used. The default server is not necessarily optimal
+in regard to performance and reliability.
+.UNINDENT
+.SH OPERATION MODES
+.sp
+The operation mode specifies what exactly the tool does with the provided
+files. The default operation mode is "dump", but this may change in the future.
+Thus, it is recommended to always set the operations mode explicitely. If
+multiple operations mode are set on the command line, results are
+unpredictable.
+.SS dump
+.sp
+The provided \fIsignature\fP files are dumped. For each top\-level record, the*u
+type code is printed as well as q short description. If there is additional
+information available, it will be printed in tab\-indented lines below the
+main record dump. The actual \fIlog\fP files need not to be present.
+.SS verify
+.sp
+This mode does not work with stdin. On the command line, the \fIlog\fP file names
+are specified. The corresponding \fIsignature\fP files (ending on ".gtsig") must also
+be preset at the same location as the log file. In verify mode, both the log
+and signature file is read and the validity of the log file checked. If verification
+errors are detected these are printed and processing of the file aborted. By default,
+each file is verified individually, without taking cross\-file hash chains into
+account (so the order of files on the command line does not matter).
+.sp
+Note that the actual amount of what can be verified depends on the parameters with
+which the signature file was written. If record and tree hashes are present, they
+will be verified and thus fine\-granular error reporting is possible. If they are
+not present, only the block signature itself is verified.
+.sp
+By default, only errors are printed. To also print successful verifications, use the
+\fB\-\-show\-verified\fP option.
+.SS extend
+.sp
+This extends the RFC3161 signatures. This includes a full verification
+of the file. If there are verification errors, extending will also fail.
+Note that a signature can only be extended when the required hash has been
+published. Currently, these hashes are created at the 15th of each month at
+0:00hrs UTC. It takes another few days to get them finally published. As such,
+it can be assumed that extending is only possible after this happend (which
+means it may take slightly above a month).
+.sp
+To prevent data corruption, a copy of the signature file is created during
+extension. So there must be enough disk space available for both files,
+otherwise the operation will fail. If the log file is named logfile, the
+signature file is logfile.gtsig and the temporary work file is named
+logfile.gtsig.new. When extending finished successfully, the original
+signature file (logfile.gtsig in our example) is renamed with the .old
+postfix (logfile.gtsig.old) and the temporary file written under the
+original name. The .old file can be deleted. It is just kept as a
+precaution to prevent signature loss. Note that any already existing
+.old or .new files are overwritten by these operations.
+.SS detect\-file\-type
+.sp
+This mode is used to detect the type of some well\-know files used inside the
+signature system. The detection is based on the file header. This mode is
+primarily a debug aid.
+.SS show\-sigblock\-params
+.sp
+This mode is used to print signature block parameters. It is similar to \fIdump\fP
+mode, but will ignore everything except signature blocks. Also, some additional
+meta information is printed. This mode is primarily a debug aid.
+.SH EXIT CODES
+.sp
+The command returns an exit code of 0 if everything went fine, and some
+other code in case of failures.
+.SH EXAMPLES
+.sp
+\fBrsgtutil \-\-verify logfile\fP
+.sp
+This verifies the file "logfile" via its associated signature file
+"logfile.gtsig". If errors are detected, these are reported to stderr.
+Otherwise, rsgtutil terminates without messages.
+.sp
+\fBrsgtutil \-\-dump logfile.gtsig\fP
+.sp
+This dumps the content of the signature file "logfile.gtsig". The
+actual log file is not being processed and does not even need to be
+present.
+.SH SEE ALSO
+.sp
+\fBrsyslogd(8)\fP
+.SH COPYRIGHT
+.sp
+This page is part of the \fIrsyslog\fP project, and is available under
+LGPLv2.
+.SH AUTHOR
+Rainer Gerhards <rgerhards@adiscon.com>
+.\" Generated by docutils manpage writer.
+.\" 
+.