MB-69825: Add --dump-encryption-header to cbcat

Allows for easy inspection of the headers:

    File: couchbase-2025-12-16T14-40-29-audit.cef
      Encrypted:
        Key ID: d2e74da9-7430-429d-92ca-cc02cf00267b
        Key Derivation: NoDerivation
        Compression: ZLIB

Change-Id: Ic14f59fc7b7b64bd5f662e01b51ef26208fa7325
Reviewed-on: https://review.couchbase.org/c/platform/+/237765
Tested-by: Build Bot <build@couchbase.com>
Reviewed-by: Jim Walker <jim@couchbase.com>

Author: trondn

cbcrypto/cbcat.cc

@@ -31,6 +31,8 @@ static constexpr int EXIT_INCORRECT_PASSWORD = 2;
 static std::string password;
 static std::unique_ptr<DumpKeysRunner> dump_keys_runner;
 static KeyStore keyStore;
+bool printHeader = false;
+bool dumpEncryptionHeader = false;
 
 /// The key lookup callback gets called from the FileReader whenever it
 /// encounters an encrypted file. It'll keep the keys around in a key store
@@ -125,14 +127,44 @@ void readKeyStoreFromStdin() {
     }
 }
 
+void print_header(std::string_view filename,
+                  std::optional<EncryptedFileHeader> header) {
+    if (!printHeader) {
+        return;
+    }
+    std::cout << "File: " << filename << std::endl;
+    if (header) {
+        try {
+            fmt::println("  Encrypted:");
+            fmt::println("    Key ID: {}", header->get_id());
+            fmt::println("    Key Derivation: {}",
+                         header->get_key_derivation());
+            if (header->get_key_derivation() ==
+                KeyDerivationMethod::PasswordBased) {
+                fmt::println("    PBKDF2 Iterations: {}",
+                             header->get_pbkdf_iterations());
+            }
+            fmt::println("    Compression: {}", header->get_compression());
+        } catch (const std::exception&) {
+            // Ignore errors
+        }
+    } else {
+        if (dumpEncryptionHeader) {
+            std::cout << "  Not an encrypted file or unable to read "
+                         "encryption header"
+                      << std::endl;
+        }
+    }
+    std::cout << std::string(70, '=') << std::endl;
+}
+
 int main(int argc, char** argv) {
     using cb::getopt::Argument;
     cb::getopt::CommandLineOptionsParser parser;
 
     std::string dumpKeysExecutable = INSTALL_ROOT "/bin/dump-keys";
     std::string gosecrets =
             INSTALL_ROOT "/var/lib/couchbase/config/gosecrets.cfg";
-    bool printHeader = false;
     bool withKeyStore = false;
     bool stdinUsed = false;
 
@@ -191,10 +223,18 @@ int main(int argc, char** argv) {
              "The JSON containing the keystore to use (use '-' to read from "
              "standard input)"});
 
-    parser.addOption({[&printHeader](auto value) { printHeader = true; },
+    parser.addOption({[](auto value) { printHeader = true; },
                       "print-header",
                       "Print a header with the file name before the content of "
                       "the file"});
+    parser.addOption(
+            {[](auto value) {
+                 dumpEncryptionHeader = true;
+                 printHeader = true;
+             },
+             "dump-encryption-header",
+             "Print the information from the encryption header if the file is "
+             "encrypted"});
     parser.addOption({[](auto) {
                           std::cout << "Couchbase Server " << PRODUCT_VERSION
                                     << std::endl;
@@ -215,13 +255,21 @@ int main(int argc, char** argv) {
     }
 
     for (const auto& file : arguments) {
-        if (printHeader) {
-            std::cout << std::endl
-                      << file << std::endl
-                      << std::string(file.length(), '=') << std::endl;
-        }
+        bool header_printed = false;
+        auto do_print_header =
+                [&header_printed](std::string_view filename,
+                                  std::optional<EncryptedFileHeader> header) {
+                    if (!header_printed) {
+                        print_header(filename, header);
+                        header_printed = true;
+                    }
+                };
         try {
             auto reader = FileReader::create(file, key_lookup_callback);
+            do_print_header(file,
+                            dumpEncryptionHeader
+                                    ? reader->get_encryption_header()
+                                    : std::nullopt);
             reader->set_max_allowed_chunk_size(
                     std::numeric_limits<uint32_t>::max());
             std::vector<uint8_t> blob(8192);
@@ -231,10 +279,12 @@ int main(int argc, char** argv) {
                 std::cout.flush();
             }
         } catch (const cb::crypto::dump_keys::IncorrectPasswordError& e) {
+            do_print_header(file, {});
             std::cerr << e.what() << std::endl;
             std::exit(EXIT_INCORRECT_PASSWORD);
 
         } catch (const std::exception& e) {
+            do_print_header(file, {});
             std::cerr << "Fatal error: " << e.what() << std::endl;
             return EXIT_FAILURE;
         }

cbcrypto/common.cc

@@ -21,6 +21,20 @@
 
 namespace cb::crypto {
 
+std::string format_as(const KeyDerivationMethod& keyDerivationMethod) {
+    using namespace std::string_literals;
+    switch (keyDerivationMethod) {
+    case KeyDerivationMethod::NoDerivation:
+        return "NoDerivation"s;
+    case KeyDerivationMethod::KeyBased:
+        return "KeyBased"s;
+    case KeyDerivationMethod::PasswordBased:
+        return "PasswordBased"s;
+    }
+    throw std::logic_error(fmt::format("Unknown key derivation method: {}",
+                                       static_cast<int>(keyDerivationMethod)));
+}
+
 [[nodiscard]] std::string format_as(const Cipher& cipher) {
     switch (cipher) {
     case Cipher::None:

cbcrypto/file_reader.cc

@@ -83,6 +83,11 @@ class FileStreamReader : public FileReader {
         return false;
     }
 
+    [[nodiscard]] std::optional<EncryptedFileHeader> get_encryption_header()
+            override {
+        return std::nullopt;
+    }
+
     std::string nextChunk() override {
         if (eof()) {
             return {};
@@ -158,6 +163,11 @@ class GZipFileReader : public FileReader {
         return false;
     }
 
+    [[nodiscard]] std::optional<EncryptedFileHeader> get_encryption_header()
+            override {
+        return std::nullopt;
+    }
+
     std::string nextChunk() override {
         if (eof()) {
             return {};
@@ -199,9 +209,10 @@ class GZipFileReader : public FileReader {
 class EncryptedFileReader : public FileReader {
 public:
     EncryptedFileReader(const KeyDerivationKey& kdk,
-                        const EncryptedFileHeader& header,
+                        const EncryptedFileHeader& header_,
                         std::unique_ptr<FileStreamReader> underlying)
-        : associated_data(header),
+        : header(header_),
+          associated_data(header),
           offset(sizeof(EncryptedFileHeader)),
           cipher(SymmetricCipher::create(kdk.cipher, header.derive_key(kdk))),
           file(std::move(underlying)) {
@@ -223,6 +234,11 @@ class EncryptedFileReader : public FileReader {
         return true;
     }
 
+    [[nodiscard]] std::optional<EncryptedFileHeader> get_encryption_header()
+            override {
+        return header;
+    }
+
     void set_max_allowed_chunk_size(std::size_t limit) override {
         max_allowed_chunk_size = limit;
     }
@@ -297,6 +313,7 @@ class EncryptedFileReader : public FileReader {
         current_chunk->append(decrypted.size());
     }
 
+    EncryptedFileHeader header;
     EncryptedFileAssociatedData associated_data;
     std::size_t offset;
     std::unique_ptr<SymmetricCipher> cipher;
@@ -314,6 +331,11 @@ class SnappyInflateReader : public FileReader {
         return underlying->is_encrypted();
     }
 
+    [[nodiscard]] std::optional<EncryptedFileHeader> get_encryption_header()
+            override {
+        return underlying->get_encryption_header();
+    }
+
     void set_max_allowed_chunk_size(std::size_t limit) override {
         underlying->set_max_allowed_chunk_size(limit);
     }
@@ -384,6 +406,11 @@ class ZlibInflateReader : public FileReader {
         return underlying->is_encrypted();
     }
 
+    [[nodiscard]] std::optional<EncryptedFileHeader> get_encryption_header()
+            override {
+        return underlying->get_encryption_header();
+    }
+
     void set_max_allowed_chunk_size(std::size_t limit) override {
         underlying->set_max_allowed_chunk_size(limit);
     }

include/cbcrypto/common.h

@@ -35,6 +35,7 @@ enum class KeyDerivationMethod : uint8_t {
     KeyBased = 1,
     PasswordBased = 2
 };
+std::string format_as(const KeyDerivationMethod& keyDerivationMethod);
 
 /// A structure to hold the information needed by a single key derivation key
 struct KeyDerivationKey {

include/cbcrypto/file_reader.h

@@ -11,6 +11,7 @@
 #pragma once
 
 #include <cbcrypto/common.h>
+#include <cbcrypto/encrypted_file_header.h>
 #include <filesystem>
 #include <functional>
 #include <span>
@@ -48,6 +49,10 @@ class FileReader {
     /// Is the file being read encrypted or not
     [[nodiscard]] virtual bool is_encrypted() const = 0;
 
+    /// Get the encryption header if the file is encrypted
+    [[nodiscard]] virtual std::optional<EncryptedFileHeader>
+    get_encryption_header() = 0;
+
     /**
      * The file reader tries to read various length fields off the encrypted
      * file and allocate buffers of that size. To avoid trying to allocate