======== rsgtutil ======== ----------------------------------- Manage (GuardTime) Signed Log Files ----------------------------------- :Author: Rainer Gerhards :Date: 2013-03-25 :Manual section: 1 SYNOPSIS ======== :: rsgtutil [OPTIONS] [FILE] ... DESCRIPTION =========== This tool performs various maintenance operations on signed log files. It specifically supports the GuardTime signature provider. The *rsgtutil* 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. 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. If no file is specified on the command line, stdin is used instead. Note that not all operation modes support stdin. OPTIONS ======= -D, --dump Select "dump" operations mode. -t, --verify Select "verify" operations mode. -T, --detect-file-type Select "detect-file-type" operations mode. -B, --show-sigblock-params Select "show-sigblock-params" operations mode. -s, --show-verified Prints out information about correctly verified blocks (by default, only errors are printed). -v, --verbose Select verbose mode. Most importantly, hashes and signatures are printed in full length (can be **very** lengthy) rather than the usual abbreviation. -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. -P , --publications-server 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. OPERATION MODES =============== 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. dump ---- The provided *signature* 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 *log* files need not to be present. verify ------ This mode does not work with stdin. On the command line, the *log* file names are specified. The corresponding *signature* 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). 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. By default, only errors are printed. To also print successful verifications, use the **--show-verified** option. extend ------ 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). 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. detect-file-type ---------------- 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. show-sigblock-params -------------------- This mode is used to print signature block parameters. It is similar to *dump* mode, but will ignore everything except signature blocks. Also, some additional meta information is printed. This mode is primarily a debug aid. EXIT CODES ========== The command returns an exit code of 0 if everything went fine, and some other code in case of failures. EXAMPLES ======== **rsgtutil --verify logfile** 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. **rsgtutil --dump logfile.gtsig** 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. SEE ALSO ======== **rsyslogd(8)** COPYRIGHT ========= This page is part of the *rsyslog* project, and is available under LGPLv2.