Add algorithm to calculate a JA4 fingerprint

cmake/ExperimentalPlugins.cmake

@@ -40,6 +40,7 @@ auto_option(HOOK_TRACE FEATURE_VAR BUILD_HOOK_TRACE DEFAULT ${_DEFAULT})
 auto_option(HTTP_STATS FEATURE_VAR BUILD_HTTP_STATS DEFAULT ${_DEFAULT})
 auto_option(ICAP FEATURE_VAR BUILD_ICAP DEFAULT ${_DEFAULT})
 auto_option(INLINER FEATURE_VAR BUILD_INLINER DEFAULT ${_DEFAULT})
+auto_option(JA4_FINGERPRINT FEATURE_VAR BUILD_JA4_FINGERPRINT DEFAULT ${_DEFAULT})
 auto_option(
   MAGICK
   FEATURE_VAR

plugins/experimental/CMakeLists.txt

@@ -59,6 +59,9 @@ endif()
 if(BUILD_INLINER)
   add_subdirectory(inliner)
 endif()
+if(BUILD_JA4_FINGERPRINT)
+  add_subdirectory(ja4_fingerprint)
+endif()
 if(BUILD_MAGICK)
   add_subdirectory(magick)
 endif()

plugins/experimental/ja4_fingerprint/CMakeLists.txt

@@ -0,0 +1,24 @@
+#######################
+#
+#  Licensed to the Apache Software Foundation (ASF) under one or more contributor license
+#  agreements.  See the NOTICE file distributed with this work for additional information regarding
+#  copyright ownership.  The ASF licenses this file to you under the Apache License, Version 2.0
+#  (the "License"); you may not use this file except in compliance with the License.  You may obtain
+#  a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software distributed under the License
+#  is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
+#  or implied. See the License for the specific language governing permissions and limitations under
+#  the License.
+#
+#######################
+
+if(BUILD_TESTING)
+  add_executable(test_ja4 test_ja4.cc ja4.cc tls_summary.cc)
+  target_link_libraries(test_ja4 PRIVATE catch2::catch2)
+
+  add_test(test_ja4 test_ja4)
+endif()
+

plugins/experimental/ja4_fingerprint/ja4.cc

@@ -0,0 +1,159 @@
+/** @file ja3_fingerprint.cc
+ *
+  JA4 fingerprint calculation.
+
+  @section license License
+
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+ */
+
+#include "ja4.h"
+
+#include <algorithm>
+#include <cctype>
+#include <cstddef>
+#include <cstdio>
+#include <iterator>
+#include <string>
+#include <string_view>
+
+static char        convert_protocol_to_char(JA4::Protocol protocol);
+static std::string convert_TLS_version_to_string(std::string_view TLS_version);
+static std::string filter_only_digits(std::string_view src);
+static char        convert_SNI_to_char(JA4::SNI SNI_type);
+static std::string convert_count_to_two_digit_string(std::size_t count);
+static std::string convert_ALPN_to_two_char_string(std::string_view ALPN);
+static void        remove_trailing_character(std::string &s);
+static std::string hexify(std::uint16_t n);
+
+namespace
+{
+constexpr std::size_t U16_HEX_BUF_SIZE{4};
+} // end anonymous namespace
+
+std::string
+JA4::make_JA4_a_raw(TLSClientHelloSummary const &TLS_summary)
+{
+  std::string result;
+  result.push_back(convert_protocol_to_char(TLS_summary.protocol));
+  result.append(convert_TLS_version_to_string(TLS_summary.TLS_version));
+  result.push_back(convert_SNI_to_char(TLS_summary.SNI_type));
+  result.append(convert_count_to_two_digit_string(TLS_summary.get_cipher_count()));
+  result.append(convert_count_to_two_digit_string(TLS_summary.get_extension_count()));
+  result.append(convert_ALPN_to_two_char_string(TLS_summary.ALPN));
+  return result;
+}
+
+static char
+convert_protocol_to_char(JA4::Protocol protocol)
+{
+  return static_cast<char>(protocol);
+}
+
+static std::string
+convert_TLS_version_to_string(std::string_view TLS_version)
+{
+  std::string result{filter_only_digits(TLS_version)};
+  return result.empty() ? "  " : result;
+}
+
+static std::string
+filter_only_digits(std::string_view src)
+{
+  std::string result{};
+  std::copy_if(src.begin(), src.end(), std::back_inserter(result), [](unsigned char c) { return std::isdigit(c); });
+  return result;
+}
+
+static char
+convert_SNI_to_char(JA4::SNI SNI_type)
+{
+  return static_cast<char>(SNI_type);
+}
+
+static std::string
+convert_count_to_two_digit_string(std::size_t count)
+{
+  std::string result;
+  if (count <= 9) {
+    result.push_back('0');
+  }
+  // We could also clamp the lower bound to 1 since there must be at least 1
+  // cipher, but 0 is more helpful for debugging if the cipher list is empty.
+  result.append(std::to_string(std::clamp(count, std::size_t{0}, std::size_t{99})));
+  return result;
+}
+
+std::string
+convert_ALPN_to_two_char_string(std::string_view ALPN)
+{
+  std::string result;
+  if (ALPN.empty()) {
+    result = "00";
+  } else {
+    result.push_back(ALPN.front());
+    result.push_back(ALPN.back());
+  }
+  return result;
+}
+
+std::string
+JA4::make_JA4_b_raw(TLSClientHelloSummary const &TLS_summary)
+{
+  std::string result;
+  std::vector temp = TLS_summary.get_ciphers();
+  std::sort(temp.begin(), temp.end());
+
+  for (auto cipher : temp) {
+    result.append(hexify(cipher));
+    result.push_back(',');
+  }
+  remove_trailing_character(result);
+  return result;
+}
+
+std::string
+JA4::make_JA4_c_raw(TLSClientHelloSummary const &TLS_summary)
+{
+  std::string result;
+  std::vector temp = TLS_summary.get_extensions();
+  std::sort(temp.begin(), temp.end());
+
+  for (auto extension : temp) {
+    result.append(hexify(extension));
+    result.push_back(',');
+  }
+  remove_trailing_character(result);
+  return result;
+}
+
+void
+remove_trailing_character(std::string &s)
+{
+  if (!s.empty()) {
+    s.pop_back();
+  }
+}
+
+std::string
+hexify(std::uint16_t n)
+{
+  char result[U16_HEX_BUF_SIZE + 1]{};
+  std::snprintf(result, sizeof(result), "%.4x", n);
+  return result;
+}

plugins/experimental/ja4_fingerprint/ja4.h

@@ -0,0 +1,156 @@
+/** @file ja3_fingerprint.cc
+ *
+  JA4 fingerprint calculation.
+
+  @section license License
+
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+
+ */
+
+#pragma once
+
+#include <cstdint>
+#include <iterator>
+#include <string>
+#include <vector>
+
+namespace JA4
+{
+
+constexpr char PORTION_DELIMITER{'_'};
+
+enum class Protocol {
+  DTLS = 'd',
+  QUIC = 'q',
+  TLS  = 't',
+};
+
+enum class SNI {
+  to_domain = 'd',
+  to_IP     = 'i',
+};
+
+/**
+ * Represents the data sent in a TLS Client Hello needed for JA4 fingerprints.
+ */
+class TLSClientHelloSummary
+{
+public:
+  using difference_type = std::iterator_traits<std::vector<std::uint16_t>::iterator>::difference_type;
+
+  Protocol    protocol;
+  SNI         SNI_type;
+  std::string TLS_version;
+  std::string ALPN;
+
+  std::vector<std::uint16_t> const &get_ciphers() const;
+  void                              add_cipher(std::uint16_t cipher);
+
+  std::vector<std::uint16_t> const &get_extensions() const;
+  void                              add_extension(std::uint16_t extension);
+
+  /**
+   * Get the number of ciphers excluding GREASE values.
+   *
+   * @return Returns the count of non-GREASE ciphers.
+   */
+  difference_type get_cipher_count() const;
+
+  /**
+   * Get the number of extensions excluding GREASE values.
+   *
+   * @return Returns the count of non-GREASE extensions.
+   */
+  difference_type get_extension_count() const;
+
+private:
+  std::vector<std::uint16_t> _ciphers;
+  std::vector<std::uint16_t> _extensions;
+  int                        _extension_count_including_sni_and_alpn;
+};
+
+/**
+ * Calculate the a portion of the JA4 fingerprint for the given client hello.
+ *
+ * The a portion of the fingerprint encodes the protocol, TLS version, SNI
+ * type, number of cipher suites, number of extensions, and first ALPN value.
+ *
+ * For more information see:
+ * https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md.
+ *
+ * @param TLS_summary The TLS client hello.
+ * @return Returns a string containing the a portion of the JA4 fingerprint.
+ */
+std::string make_JA4_a_raw(TLSClientHelloSummary const &TLS_summary);
+
+/**
+ * Calculate the b portion of the JA4 fingerprint for the given client hello.
+ *
+ * The b portion of the fingerprint is a comma-delimited list of lowercase hex
+ * numbers representing the cipher suites in sorted order. GREASE values are
+ * ignored.
+ *
+ * For more information see:
+ * https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md.
+ *
+ * @param TLS_summary The TLS client hello.
+ * @return Returns a string containing the b portion of the JA4 fingerprint.
+ */
+std::string make_JA4_b_raw(TLSClientHelloSummary const &TLS_summary);
+
+/**
+ * Calculate the c portion of the JA4 fingerprint for the given client hello.
+ *
+ * The b portion of the fingerprint is a comma-delimited list of lowercase hex
+ * numbers representing the extensions in sorted order. GREASE values and the
+ * SNI and ALPN extensions are ignored.
+ *
+ * For more information see:
+ * https://github.com/FoxIO-LLC/ja4/blob/main/technical_details/JA4.md.
+ *
+ * @param TLS_summary The TLS client hello.
+ * @return Returns a string containing the c portion of the JA4 fingerprint.
+ */
+std::string make_JA4_c_raw(TLSClientHelloSummary const &TLS_summary);
+
+/**
+ * Calculate the JA4 fingerprint for the given TLS client hello.
+ *
+ * @param TLS_summary The TLS client hello. If there was no ALPN in the
+ * Client Hello, TLS_summary.ALPN should either be empty or set to "00".
+ * Behavior when the number of digits in TLS_summary.TLS_version is greater
+ * than 2, the number of digits in TLS_summary.ALPN is greater than 2
+ * (except when TLS_summary.ALPN is empty) is unspecified.
+ * @param UnaryOp hasher A hash function. For a specification-compliant
+ * JA4 fingerprint, this should be a sha256 hash.
+ * @return Returns a string containing the JA4 fingerprint.
+ */
+template <typename UnaryOp>
+std::string
+make_JA4_fingerprint(TLSClientHelloSummary const &TLS_summary, UnaryOp hasher)
+{
+  std::string result;
+  result.append(make_JA4_a_raw(TLS_summary));
+  result.push_back(JA4::PORTION_DELIMITER);
+  result.append(hasher(make_JA4_b_raw(TLS_summary)).substr(0, 12));
+  result.push_back(JA4::PORTION_DELIMITER);
+  result.append(hasher(make_JA4_c_raw(TLS_summary)).substr(0, 12));
+  return result;
+}
+
+} // end namespace JA4