From 85229d32e10c58bd8b6f02f9a1fa020c1f2fc891 Mon Sep 17 00:00:00 2001 From: Eldar Nash Date: Wed, 22 Nov 2023 19:42:10 +0100 Subject: [PATCH] Adds 3 of the missing manpages --- content/app-man-syslog-ng/slogencrypt.1.md | 71 ++++++++++++++++++++ content/app-man-syslog-ng/slogkey.1.md | 78 ++++++++++++++++++++++ content/app-man-syslog-ng/slogverify.1.md | 76 +++++++++++++++++++++ 3 files changed, 225 insertions(+) create mode 100644 content/app-man-syslog-ng/slogencrypt.1.md create mode 100644 content/app-man-syslog-ng/slogkey.1.md create mode 100644 content/app-man-syslog-ng/slogverify.1.md diff --git a/content/app-man-syslog-ng/slogencrypt.1.md b/content/app-man-syslog-ng/slogencrypt.1.md new file mode 100644 index 00000000..2f2f7271 --- /dev/null +++ b/content/app-man-syslog-ng/slogencrypt.1.md @@ -0,0 +1,71 @@ +--- +title: "The slogencrypt tool manual page" +weight: 4900 +--- + + + + +## Name + +`slogencrypt` — Encrypt existing plain text log files using the {{% param "product.abbrev" %}} secure logging environment. + +## Synopsis + +`slogencrypt [options] [arguments]` + +## Description + +The `slogencrypt` utility is used to encrypt plain text log file using an existing secure logging environment. Using this utility, log files obtained from a previous installation of `syslog-ng` or another logging system can be transferred to a secure logging environment. The order of the log entries is preserved. Encrypting plain text log files using an existing secure logging environment, requires the current encryption key to be supplied in order to preserve consistency. + +General call sequence: `slogencrypt -k <key file> -m <MAC file> <new key file> <new MAC file> <plain text log> <output file> [counter]` + +## Arguments + +- `<new key file>` + + The file that will contain the new current encryption key after successful encryption. + +- `<new MAC file>` + + The file receiving the new current message authentication code (MAC) of the secure encrypted destination after encryption. In case an existing file is supplied, new entries will be appended. + +- `<input log file>` + + The plain text log file that will be encrypted using the secure logging environment. + +- `<output log file>` + + The file that will contain the encrypted log entries from the supplied plain text log file after encryption. + +- `counter` + + The current log entry counter of the secure encrypted destination after encryption. This is required if the log entries to be encrypted will be appended to an existing secure encrypted destination. + +## Options + +- `--key-file` or `-k` + + The current host key from the system where the encryption will be performed. + +- `--mac-file` or `-m` + + The current MAC file from the system where the encryption will be performed. + +- `--help` or `-h` + + Display a help message. + +## Files + +`/usr/bin/slogencrypt` + +`/etc/syslog-ng.conf` + +## See also + +[syslog-ng.conf.5]({{< ref "/app-man-syslog-ng/syslog-ng.conf.5.md" >}}) + +[syslog-ng.8]({{< ref "/app-man-syslog-ng/syslog-ng.8/_index.md" >}}) + +{{< include-headless "chunk/manpage-more-info.md" >}} diff --git a/content/app-man-syslog-ng/slogkey.1.md b/content/app-man-syslog-ng/slogkey.1.md new file mode 100644 index 00000000..d391beef --- /dev/null +++ b/content/app-man-syslog-ng/slogkey.1.md @@ -0,0 +1,78 @@ +--- +title: "The slogkey tool manual page" +weight: 4900 +--- + + + + +## Name + +`slogkey` — Manage cryptographic keys for use with the {{% param "product.abbrev" %}} secure logging environment. + +## Synopsis + +`slogkey [options] [arguments]` + +## Description + +The `slogkey` utility is used to manage cryptographic keys for use with the secure logging module of {{% param "product.abbrev" %}}. Use this utility to create a master key, derive a host key to be used by a secure logging configuration and to display the current sequence counter of a key. The options determine the operating mode and are mutually exclusive. + +## Arguments + +The arguments depend on the operating mode. + +- Master key generation + + Call sequence: `slogkey --master-ḱey <filename>` + + `<filename>`: The name of the file to which the master key will be written. + +- Host key derivation + + Call sequence: `slogkey --derive-key <master key file> <host MAC address> <host serial number> <host key file>` + + - `<master key file>`: The master key from which the host key will be derived. + - `<host MAC address>`: The MAC address of the host on which the key will be used. Instead of the MAC address, any other string that uniquely identifies a host can be supplied, e.g. the company inventory number. + - `<host serial number>`: The serial number of the host on which the key will be used. Instead of the serial number, any other string that uniquely identifies a host can be supplied, for example, the company inventory number. + - `<host key file>`: The name of the file to which the host key will be written. + + > NOTE: The newly created host key has its counter set to 0 indicating that it represents the initial host key k0. This host key must be kept secret and not be disclosed to third parties. It will be required to successfully decrypt and verify log archives processed by the secure logging environment. As each log entry will be encrypted with its own key, a new host key will be created after successful processing of a log entry and will replace the previous key. Therefore, the initial host key needs to be stored in a safe place before starting the secure logging environment, as it will be deleted from the log host after processing of the first log entry. + +- Sequence counter display + + Call sequence: `slogkey --counter <host key file>` + + - `<host key file>`: The host key file from which the sequence will be read. + +## Options + +- `--master-key` or `-m` + + Generates a mew master key. `<filename>` is the name of the file storing the newly generated master key. + +- `--derive-key` or `-d` + + Derive a host key using a previously generated master key. + +- `--counter` or `-c` + + Display the current log sequence counter of a key. + +- `--help` or `-h` + + Display a help message. + +## Files + +`/usr/bin/slogkey` + +`/etc/syslog-ng.conf` + +## See also + +[syslog-ng.conf.5]({{< ref "/app-man-syslog-ng/syslog-ng.conf.5.md" >}}) + +[secure-logging.7]({{< ref "/app-man-syslog-ng/secure-logging.7/_index.md" >}}) + +{{< include-headless "chunk/manpage-more-info.md" >}} diff --git a/content/app-man-syslog-ng/slogverify.1.md b/content/app-man-syslog-ng/slogverify.1.md new file mode 100644 index 00000000..fedddb9a --- /dev/null +++ b/content/app-man-syslog-ng/slogverify.1.md @@ -0,0 +1,76 @@ +--- +title: "The slogverify tool manual page" +weight: 4900 +--- + + + + +## Name + +`slogverify` — Verify cryptographically secured logs. + +## Synopsis + +`slogverify [options] [arguments]` + +## Description + +The `slogverify` utility is used to verify the integrity of cryptographically secured logs and to decrypt log entries produced in a {{% param "product.abbrev" %}} secure logging environment. + +- Normal mode: `slogverify -k <host key file> -m <input MAC file> <input file> <output file> [buffers]` +- Iterative mode: `slogverify -i -p <previous host key> -r <previous MAC> -m <current MAC> <input file> <output file> [buffers]` + +## Arguments + +- `input file` + + An encrypted log file from the syslog-ng secure logging environment that will be verified. + +- `output file` + + The file that will contain the plain text log entries after decryption and verification. + +- `buffers` + + Optional number of input buffers. The number of buffers can be used for performance adjustments in case the log file to be verified is very large and cannot be processed at once. It is a positive number of log entries that can be held in memory during verification. The minimum number if 10 and the maximum number is 4294967295. If this argument is not supplied the default of 1000 is used. + +## Options + +- `--iterative` or `-i` + + Iterative mode. This is useful in case the log files are periodically copied from the system on which they where generated to central collector. As log rotation, i.e. overwriting log files in order to preserve space cannot be done in a secure logging environment, the iterative mode can be used instead. This works as follows: If a certain storage limit is reached the log file together with the host key and the MAC file is copied to new destination and the old file is deleted. The verification is then performed in iterations, i.e. separately for each file that was retrieved from the log host. For this to work, it is important to always retrieve the corresponding host key and MAC files. The process can be automated, e.g. by calling slogverify in iterative mode from a script.< + +- `--key-file` or `-k` + + The initial host key (k0). This option is used in normal mode only. + +- `--mac-file` or `-m` + + The current MAC file used. + +- `--prev-key-file` or `-p` + + The host key corresponding to the previous log file. This option can be used in iterative mode only. In theory, this can be initial host key (k0) but using this key might generate warnings, as the gap between the first log entry ever (log entry 0) and the first log entry of the current log file might be large. + +- `--prev-mac-file` or `-r` + + The MAC file from the previous log file. This option can only be used in iterative mode. + +- `--help` or `-h` + + Display a help message. + +## Files + +`/usr/bin/slogverify` + +`/etc/syslog-ng.conf` + +## See also + +[syslog-ng.conf.5]({{< ref "/app-man-syslog-ng/syslog-ng.conf.5.md" >}}) + +[secure-logging.7]({{< ref "/app-man-syslog-ng/secure-logging.7/_index.md" >}}) + +{{< include-headless "chunk/manpage-more-info.md" >}}