secure-logging(7)

📦
version 4.11.0 · 13 versions
, in alpine 3.24, fedora 44

💖 secure-logging(7) 💖

okay bestie, welcome to secure-logging, aka the secure-logging manual page — this is the one that gives your system logs forward integrity and confidentiality. it's giving glow-up but for log files. let's go 🫶

✨ NAME ✨

secure-logging — Provides forward integrity and confidentiality for system logs.

🌈 SYNOPSIS 🌈

$(slog --key-file <host key file> --mac-file <MAC file> ${RAWMSG})

🦋 DESCRIPTION 🦋

Secure logging is an extension of syslog-ng OSE that hands your system logs forward integrity and confidentiality. it's literally implemented as a module, and you set it up as a template in the syslog-ng OSE config file. cute, right? 💅

The main character energy of the secure logging module is tamper evident logging — like, adequately protecting the log records of a system and giving you a sensor that flags breach-attempts. how does it pull this off? by the authentical encryption of every single log record with its own individual cryptographic key that gets used only once, plus protecting the integrity of the whole log archive with a cryptographic authentication code. so every attempt to tamper with one log record or the archive itself gets immediately detected during log archive verification. no cap. an attacker literally cannot tamper with log records without being caught. 💀

To actually use the log file that the secure logging module made for analysis, you have to decrypt it first and then verify its integrity. this is done with a command line utility that ships as part of the secure logging module and gets installed along with the syslog-ng OSE package. you can plug that utility right into the import module of your existing analysis environments. iconic. ✨

The secure logging environment uses a cryptographic key to encrypt log entries. every individual log entry gets encrypted with its own key, and those keys are immediately discarded after successful encryption — that's the whole forward integrity thing. an efficient algorithm generates the key for the next log entry based on the key used for encrypting the previous log entry. the resulting chain of keys preserves forward integrity, meaning a potential attacker cannot deduce the previous key from the current key. that's the vibe. 🔥

To optimize log verification and analysis, a sequence number gets added to each log entry. that sequence number is also added to the encryption key, which creates a one-to-one correspondence of the encryption key with the log entry. and to prevent truncation attacks or deletion of individual log entries, a message authentication code (MAC) is iteratively applied to the complete log archive and stored in a separate file. upon verification, that MAC is what checks the integrity of the whole log archive. obsessed. 🎀

The following is an example of three short original log messages that are sent to a destination with secure logging enabled:

This is a log message
And here comes another log message
This is a log message with a longer text that is processed without any problems

To identify the status of the secure logging environment, check the sequence counter by querying the key file with the slogkey utility:

user@host:~> slogkey --counter /etc/syslog-ng/host.key
counter=3

The numbering of log messages starts at zero, so because of that, the counter is set to three after processing three messages. math is mathing. ✨

The output of the secure logging template for those three example messages is shown below. you can observe the sequence number that was prepended to each message. the colon indicates the end of the sequence number and the start of the original message. and since three messages were processed, the sequence counter of the key is also three.

AAAAAAAAAAA=:k3/dYpLsgO2tUJKSauo6dycIBzW6OTC3pyA9TP+7AnqFgEojBzgC2rcK4OPfRtr8yg==
AQAAAAAAAAA=:smw0ATISVgN+BYEu5d7OLBE7aQhHpK9Ro4MndmNgSVrqhcmRCBCj6DUnD6ku0Z29CKJ0N6LAJUgByX4Ev+g=
AgAAAAAAAAA=:5UVybnKL1EAbgC4CLfd8HpgurjREf4LEN61/yWHSD2hbXjRD4QmQdtbwguT1chzdItKSQASps9QRIvR5Jd4AHzHfqxI4aRgdUBcNbAq26nwUCg5vPWygjmbtQaxZgCJYkry8slxCigmbTVs=

The following is the output of a successful verification run:

0000000000000000: This is a log message
0000000000000001: And here comes another log message
0000000000000002: This is a log message with a longer text that is processed without any problems

The original log messages have been successfully restored, and the sequence counters are also assigned to the clear text messages. this helps in analyzing problems within a particular log entry. and since real log files will contain thousands of entries, the sequence counter helps you identify faulty entries. super handy bestie. 🫶

Before the secure logging module can be used as part of an existing syslog-ng OSE installation, several preparatory activities are necessary. buckle up. 🦋

🔑 KEY GENERATION 🔑

To bootstrap the system, an initial key (k0) must be created and installed on the log host before the secure logging environment is started for the first time.

The initially created host key (k0) has its counter set to 0, marking it as the initial host key. this host key must be kept secret and it cannot be disclosed to any third parties. it's required to successfully decrypt and verify log archives processed by the secure logging environment. since each log entry is encrypted with its own key, a new host key will be created after successful processing of a log entry and it replaces the previous key. so the initial host key needs to be stored in a safe place before starting the secure logging environment, because it gets deleted from the log host after processing of the first log entry. 😭

The following steps must be done before starting the secure logging environment. Steps 1 and 2 are performed with the slogkey utility. See the slogkey.1 manual page for details on how to generate a master key and to derive a host key from it. Step 3 and 4 depend on the actual deployment in a target environment.

  1. Create a master key.
  2. Derive an initial host key (k0) from the master key (key1). Store the k0 key in a safe location that is outside of the log host.
  3. Deploy k0 on the log host, where the secure logging module is to be used.

CONFIGURATION time bestie!! This is where you actually turn it on ✨

🎀 CONFIGURATION 🎀

okay so, you configure secure logging by dropping the corresponding statements into your syslog-ng.conf file. that's it. that's the whole ritual 🕯️

Secure logging is implemented as a template and it's configured like one. And here's the cute part: apart from the actual template configuration itself, you do not need any other setting to activate secure logging. zero extra steps. slay.

You activate it by adding this statement to the config file:

template("$(slog --key-file  <host key file> --mac-file <MAC file> ${RAWMSG})\n");

(that double space after --key-file? yeah it's in there. leave it. it's fine. she's fine 💅)

So what is each lil piece actually doing?? Let me break it down for you 🫶

  • slog — this is the name of the secure logging template function. You can also find this name yourself by calling syslog-ng OSE with the --module-registry arguments and checking out the template-func property of the secure logging module in the corresponding output. iykyk 🔍
  • --key-file or -k — the host key file. <host key file> is the full path of the file that stores the host key on the log host. And heads up: if this argument isn't supplied, or it doesn't point to a valid key file, syslog-ng OSE will not start and it shows you an error message. no silent failure, she will yell at you 😭
  • --mac-file or -m — the MAC file. <MAC file> is the full path of the MAC file on the log host. The file gets created automatically on the initial start, so you don't have to make it yourself 💖. But if the path is wrong, syslog-ng OSE will not start and it shows you a corresponding error message.
  • ${RAWMSG} — this gives you access to the original log message as it was received at the source. Important caveat though: this macro is only available if the store-raw-message flag was set for the source. Otherwise, an empty string is what gets passed to the secure logging template 🫠. And if access to the original message just isn't available — say the source doesn't support the store-raw-message flag — then you can use the ${MSG} macro instead. BUT: in that case, the integrity guarantee that secure logging provides is limited to the content that this macro provides, and it does not protect the complete original message. lowkey a downgrade, just so you know.
  • \n — this is a line separator, and using it is important, bestie. The secure logging template expects log entries to be separated. When a line separator is detected, the log entry is regarded as complete and gets encrypted with the current host key 🔐. So: only a single line separator is allowed. one. not two. periodt.

✨ The secure logging template plays nice with others (with limits) ✨

You can combine the secure logging template with any source or destination, but there are limitations, and they are not optional:

  • Sources must be line-oriented. Secure logging uses a line separator to distinguish between individual log entries. Sources that hand you data in a different format — for example, raw data obtained directly from a database system — cannot currently be used with the secure logging template, because the separation of log entries just isn't clearly defined for that type of data.
  • Only sources for which the store-raw-message flag is implemented and set actually benefit from the integrity guarantee that the secure logging template provides. Here's the tea: secure logging aims at protecting the integrity of complete log messages, including all associated meta-data like timestamps and host names. syslog-ng OSE parses the log message into its internal format and gives you easy access to parts of a message through macros. That's super convenient when you're rewriting log messages — but it is not helpful for secure logging. So syslog-ng OSE provides the store-raw-message flag, which gives you access to a copy of the original log message after parsing. That is the log message processed and protected by the secure logging template 💚. And if the source doesn't support the store-raw-message flag, you can use the ${MSG} macro instead — but again, in this case the integrity guarantee provided by secure logging is limited to the content that this macro provides.
  • Log rotation of any kind cannot be used with destinations using secure logging, because log rotate overwrites or deletes previous log files. And that compromises the cryptographic chain of trust of the log entries preve recovery 💀. So to efficiently handle log files, the secure logging environment features iterative verification. Using iterative verification, a log file can be verified in steps. For this to work, the log file must first be downloaded from the log host, together with the corresponding host key and MAC file, to a verification host. After downloading, the log file can be safely deleted from the log host. Verification is then performed on the verification host using the iterative mode of the slogverify utility. she's organized, she has a system 🧚

🌸 EXAMPLE: SECURE LOGGING TEMPLATE ON A FILE DESTINATION 🌸

#############################################
# Minimal syslog-ng.conf file with secure logging enabled. Encrypted log
# entries are logged to a single file called /var/log/messages.slog
#

@version: 4.4
@include "scl.conf"

source s_local {
    system();
    internal();
};

source s_network {
    network(
        transport("udp")
        port(514)
        flags(store-raw-message)
    );
};

# Secure logging template definition
template secure_logging {
    template("$(slog --key-file /etc/syslog-ng/host.key --mac-file /etc/syslog-ng/mac.dat ${RAWMSG})\n");
};

# This configures a secure logging destination
destination d_local {
    file("/var/log/messages.slog" template(secure_logging));
};

log {
    source(s_local);

    # This source has the raw message flag set
    source(s_network);

    # This statement activates secure logging for this destination
    destination(d_local);
};

look at her go 💖 notice the flags(store-raw-message) on s_network — that's the source doing its part so ${RAWMSG} actually has something to hand over. iconic behavior honestly 👑

🔍 LOG VERIFICATION 💖

okay bestie, so you've got a whole secure logging environment out there doing its thing, but the log files it makes? they're encrypted. to actually read them you've gotta decrypt them and check that nobody messed with them. that whole vibe check is called verification, and verification needs two things: the initial host key (k0) and the matching MAC file. the tool that does it is slogverify.

ngl, you do not normally run this on the log host itself — the one that's busy producing log data. in a typical deployment you pull the log files off the log host, ship them over to a central log collector, and verify them there. and because verification literally requires k0, it should only ever be performed in a trusted environment. like, fr fr, guard that key. 🔐

🥰 NORMAL MODE

in normal mode you verify a complete log archive all at once. in a typical setup that means: grab a log file together with its MAC file from a log host, grab the corresponding initial key k0 from a safe location, and hand all of it to slogverify. a typical call sequence for normal mode looks like this:

slogverify --key-file host0.key --mac-file mac.dat /var/log/messages.slog /var/log/verified/messages

so what's each piece doing? let's break it down, bestie:

  • host0.key — this is the initial host key (k0). supplying k0 alone is enough to decrypt all the log entries, because the key derivation algorithm can generate the keys for every subsequent log entry based on k0. one key to rule them all, iconic honestly. 👑
  • mac.dat — the MAC file, straight from the log host.
  • /var/log/messages.slog — the file holding the encrypted log entries, as retrieved from a log host.
  • /var/log/verified/messages — the file that receives the plain text log after decryption.

now, log files can get big — like, too big to fit in system memory. so verification happens in chunks. each part of the log file gets transferred into an internal buffer, verification runs on it, and once that buffer is done, the next chunk gets fetched. you can optionally pass a buffer argument to slogverify to change the default buffer size of 1000 log entries into whatever number suits the system you're verifying on. for example:

slogverify --key-file host.key --mac-file mac.dat /var/log/messages.slog /var/log/verified/messages 8000

want more on verification in normal mode? peep [[slogverify|adm-man-slogkey]]. ✨

🔁 ITERATIVE MODE

so normal mode is cute and all, but it doesn't fit every application scenario. lots of log hosts use log rotation to save storage space. in log rotation you define a threshold for the max storage space and a number of generations for different types of log files, and once storage is exhausted or you hit the generation count, the oldest log file gets overwritten by incoming log data.

yeah… that's not possible in a secure logging environment, bestie. 😭 overwriting — i.e. deleting — a log file would break the cryptographic chain established between the log entries. and honestly that's no surprise, because one of the main objectives of secure logging is to protect against deletion of log entries by a potential attacker. so obviously we can't just yeet old logs. 💀

to enable something similar to log rotation, the secure logging environment has an iterative mode. in iterative mode, log files can be split into different files, and each of those files can be verified separately. ⚠️ but take care when you verify in iterative mode: each of the different log files needs to be accompanied by a copy of the host key and the MAC files present on the system at the time of retrieval. a typical usage scenario for iterative mode goes like this:

  1. Define a storage threshold for the secure logging file destination. In this example a 500MB threshhold is defined.
  2. Let the secure logging environment produce log data that is written to the destination up until the allocated 500MB is reached.
  3. Stop the secure logging environment and retrieve the log file, the host key and the MAC files from the log host.
  4. Delete the log file on the log host but leave host key and MAC file untouched.
  5. Restart the secure logging environment.
  6. Perform verification in iterative mode with the log file, the host key and the MAC that was retrieved.

steps 2-6 have to repeated each time the log file reaches a size of 50 MB. so assuming the log file parts are named after the iteration — like log.1, log.2, log.3, etc. — and a similar convention is applied to the host keys and MAC files, a typical call sequence for validating a log file part in iterative mode after three iterations looks like this:

slogverify --iterative --prev-key-file host.key.2 --prev-mac-file mac.dat.2 --mac-file mac.dat /var/log/messages.slog.3 /var/log/verified/messages.3

and here's what each element is doing:

  • host.key.2 — the host key from the previous iteration. in this example, that's the second iteration.
  • mac.dat.2 — the MAC file from the previous iteration. in this example verification is performed during the third iteration, so the MAC file from the second iteration is required.
  • mac.dat — the current MAC file from the log host.
  • /var/log/messages.slog.3 — the file element containing the encrypted log entries as retrieved from the log host during the third iteration.
  • /var/log/verified/messages.3 — the file receiving the plain text log after decryption during the third iteration.

in a real deployment, all of the above steps would typically be automated using a scripting engine. 🧚 see [[slogverify|adm-man-slogver]] for details on verification in iterative mode.

📁 FILES 🎀

  • /Users/hofi/Develop/Balabit/syslog-ng/build/install/bin/slogkey
  • /Users/hofi/Develop/Balabit/syslog-ng/build/install/bin/slogencrypt
  • /Users/hofi/Develop/Balabit/syslog-ng/build/install/bin/slogverify
  • /Users/hofi/Develop/Balabit/syslog-ng/build/install/etc/syslog-ng.conf

👀 SEE ALSO 🦋

  • The syslog-ng.conf manual page
  • The slogkey manual page
  • The slogencrypt manual page
  • The slogverify manual page

and that's the whole page, bestie!! 🫶 this was secure-logging(7) from version 4.10.2, dated 18 December 2025. go forth and verify those logs, you absolute main character. 💅🌸

📦 where this page comes from