Add cache key hash logging field and public API (#13134)

* Add cache key hash logging field and public API

Add 'ckh' log field that emits the base64-encoded cache key
digest, and TSHttpTxnCacheKeyDigestGet() for plugin access to
the raw hash bytes. Includes admin and API documentation.

Co-Author: Craig Taylor

* Address Copilot and bneradt review comments

Set *length on all return paths in TSHttpTxnCacheKeyDigestGet(),
and use base64.b64decode(validate=True) for stricter validation
in the test verifier. Also switch the @param tags on
TSHttpTxnCacheKeyDigestGet() to use [in]/[out]/[in,out] per
AGENTS.md.

Author: zwoop

doc/admin-guide/logging/formatting.en.rst

@@ -151,6 +151,7 @@ Cache Details
 .. _crc:
 .. _crsc:
 .. _chm:
+.. _ckh:
 .. _cwr:
 .. _cwtr:
 .. _crra:
@@ -166,6 +167,10 @@ Field Source         Description
 cluc  Client Request Cache Lookup URL, also known as the :term:`cache key`,
                      which is the canonicalized version of the client request
                      URL.
+ckh   Proxy Cache    Cache Key Hash. The base64-encoded cryptographic hash of the
+                     effective cache key used for cache lookup and storage. This
+                     is the actual key used to index cache objects. Empty
+                     (``-``) when no cache lookup was performed.
 crc   Proxy Cache    Cache Result Code. The result of |TS| attempting to obtain
                      the object from cache; :ref:`admin-logging-cache-results`.
 crsc  Proxy Cache    Cache Result Sub-Code. More specific code to complement the

doc/developer-guide/api/functions/TSHttpTxnCacheKeyDigestGet.en.rst

@@ -0,0 +1,64 @@
+.. 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:: ../../../common.defs
+
+.. default-domain:: cpp
+
+TSHttpTxnCacheKeyDigestGet
+**************************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSReturnCode TSHttpTxnCacheKeyDigestGet(TSHttpTxn txnp, char *buffer, int *length)
+
+Description
+===========
+
+Get the effective cache key digest (cryptographic hash) that was used for
+cache lookup or storage on this transaction. This is the raw hash bytes,
+not a hex or base64 encoding.
+
+The digest size depends on the build configuration: 16 bytes for MD5
+(default) or 32 bytes for SHA-256 (FIPS mode). A 32-byte buffer is
+sufficient for either mode:
+
+.. code-block:: c
+
+    char digest[32];
+    int  digest_len = sizeof(digest);
+    if (TSHttpTxnCacheKeyDigestGet(txnp, digest, &digest_len) == TS_SUCCESS) {
+      // digest_len contains the actual number of bytes written
+    }
+
+Pass :code:`nullptr` for *buffer* to query the digest size without
+copying.
+
+Returns :enumerator:`TS_SUCCESS` if a cache key was computed for the
+transaction. Returns :enumerator:`TS_ERROR` if no cache lookup was
+performed, or if *buffer* is non-null and *\*length* is smaller than the
+digest size. In all cases *\*length* is set to the required digest size
+on return.
+
+See Also
+========
+
+:func:`TSHttpTxnCacheLookupUrlGet`

include/proxy/http/HttpCacheSM.h

@@ -129,6 +129,12 @@ class HttpCacheSM : public Continuation
     return cache_read_vc ? (cache_read_vc->is_compressed_in_ram()) : false;
   }
 
+  const HttpCacheKey &
+  get_cache_key() const
+  {
+    return cache_key;
+  }
+
   void
   set_open_read_tries(int value)
   {

include/proxy/logging/LogAccess.h

@@ -254,6 +254,7 @@ class LogAccess
   //
   int marshal_cache_write_code(char *);           // INT
   int marshal_cache_write_transform_code(char *); // INT
+  int marshal_cache_key_hash(char *);             // STR
 
   // other fields
   //

include/proxy/logging/TransactionLogData.h

@@ -75,8 +75,9 @@ class TransactionLogData
   int   get_unmapped_url_len() const;
 
   // ===== Cache lookup URL =====
-  char *get_cache_lookup_url_str() const;
-  int   get_cache_lookup_url_len() const;
+  char                 *get_cache_lookup_url_str() const;
+  int                   get_cache_lookup_url_len() const;
+  const ts::CryptoHash *get_cache_lookup_hash() const;
 
   // ===== Client addressing =====
   sockaddr const *get_client_addr() const;

include/ts/ts.h

@@ -2768,6 +2768,25 @@ TSReturnCode TSHttpTxnCachedRespModifiableGet(TSHttpTxn txnp, TSMBuffer *bufp, T
 TSReturnCode TSHttpTxnCacheLookupStatusSet(TSHttpTxn txnp, int cachelookup);
 TSReturnCode TSHttpTxnCacheLookupUrlGet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc obj);
 TSReturnCode TSHttpTxnCacheLookupUrlSet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc obj);
+
+/**
+    Gets the effective cache key digest (cryptographic hash) that was
+    used for cache lookup or storage on this transaction.  The digest
+    is returned as raw bytes — 16 bytes for MD5 (default) or 32 bytes
+    for SHA-256 (FIPS mode).  A buffer of at least 32 bytes is
+    recommended to accommodate either configuration.
+
+    @param[in] txnp the transaction.
+    @param[out] buffer caller-provided buffer to receive the raw hash
+      bytes. If @c nullptr, only @a length is set (size query).
+    @param[in,out] length capacity of @a buffer in bytes on input; actual
+      digest size in bytes on output.
+
+    @return @c TS_SUCCESS if a cache key was computed for this
+      transaction, @c TS_ERROR if no cache lookup was performed or if
+      @a buffer is non-null and too small.
+ */
+TSReturnCode TSHttpTxnCacheKeyDigestGet(TSHttpTxn txnp, char *buffer, int *length);
 TSReturnCode TSHttpTxnPrivateSessionSet(TSHttpTxn txnp, int private_session);
 const char  *TSHttpTxnCacheDiskPathGet(TSHttpTxn txnp, int *length);
 int          TSHttpTxnBackgroundFillStarted(TSHttpTxn txnp);

src/api/InkAPI.cc

@@ -4477,6 +4477,35 @@ TSHttpTxnCacheLookupUrlSet(TSHttpTxn txnp, TSMBuffer bufp, TSMLoc obj)
   return TS_SUCCESS;
 }
 
+TSReturnCode
+TSHttpTxnCacheKeyDigestGet(TSHttpTxn txnp, char *buffer, int *length)
+{
+  sdk_assert(sdk_sanity_check_txn(txnp) == TS_SUCCESS);
+  sdk_assert(length != nullptr);
+
+  HttpSM           *sm              = reinterpret_cast<HttpSM *>(txnp);
+  const CryptoHash &hash            = sm->get_cache_sm().get_cache_key().hash;
+  constexpr int     size            = CRYPTO_HASH_SIZE;
+  int               provided_length = *length;
+
+  *length = size;
+
+  if (hash.is_zero()) {
+    return TS_ERROR;
+  }
+
+  if (buffer == nullptr) {
+    return TS_SUCCESS;
+  }
+
+  if (provided_length < size) {
+    return TS_ERROR;
+  }
+
+  memcpy(buffer, hash.u8, size);
+  return TS_SUCCESS;
+}
+
 /**
  * timeout is in msec
  * overrides as proxy.config.http.transaction_active_timeout_out

src/proxy/logging/Log.cc

@@ -505,6 +505,10 @@ Log::init_fields()
   global_field_list.add(field, false);
   field_symbol_hash.emplace("cluc", field);
 
+  field = new LogField("cache_key_hash", "ckh", LogField::STRING, &LogAccess::marshal_cache_key_hash, &LogAccess::unmarshal_str);
+  global_field_list.add(field, false);
+  field_symbol_hash.emplace("ckh", field);
+
   field = new LogField("client_sni_server_name", "cssn", LogField::STRING, &LogAccess::marshal_client_sni_server_name,
                        &LogAccess::unmarshal_str);
   global_field_list.add(field, false);

src/proxy/logging/LogAccess.cc

@@ -35,6 +35,7 @@
 #include "swoc/BufferWriter.h"
 #include "tscore/Encoding.h"
 #include "tscore/ink_inet.h"
+#include "tscore/ink_base64.h"
 
 char INVALID_STR[] = "!INVALID_STR!";
 
@@ -3030,6 +3031,35 @@ LogAccess::marshal_cache_write_transform_code(char *buf)
   return INK_MIN_ALIGN;
 }
 
+/*-------------------------------------------------------------------------
+  -------------------------------------------------------------------------*/
+
+int
+LogAccess::marshal_cache_key_hash(char *buf)
+{
+  const ts::CryptoHash *hash = m_data->get_cache_lookup_hash();
+
+  if (!hash || hash->is_zero()) {
+    if (buf) {
+      marshal_str(buf, "-", padded_length(2));
+    }
+    return padded_length(2);
+  }
+
+  constexpr size_t b64_bufsize = ats_base64_encode_dstlen(CRYPTO_HASH_SIZE);
+  char             b64_str[b64_bufsize];
+  size_t           b64_len = 0;
+
+  ats_base64_encode(reinterpret_cast<const char *>(hash->u8), CRYPTO_HASH_SIZE, b64_str, b64_bufsize, &b64_len);
+
+  int len = padded_length(b64_len + 1);
+
+  if (buf) {
+    marshal_str(buf, b64_str, len);
+  }
+  return len;
+}
+
 /*-------------------------------------------------------------------------
   -------------------------------------------------------------------------*/
 

src/proxy/logging/TransactionLogData.cc

@@ -366,6 +366,16 @@ TransactionLogData::get_cache_lookup_url_len() const
   return 0;
 }
 
+const ts::CryptoHash *
+TransactionLogData::get_cache_lookup_hash() const
+{
+  if (likely(m_http_sm != nullptr)) {
+    return &(m_http_sm->get_cache_sm().get_cache_key().hash);
+  }
+
+  return nullptr;
+}
+
 // ===== Client addressing =====
 
 sockaddr const *