components/browsing_topics/util.h

   1 // Copyright 2022 The Chromium Authors
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef COMPONENTS_BROWSING_TOPICS_UTIL_H_
   6 #define COMPONENTS_BROWSING_TOPICS_UTIL_H_
   7
   8 #include "base/containers/span.h"
   9 #include "base/time/time.h"
  10 #include "components/browsing_topics/common/common_types.h"
  11
  12 namespace browsing_topics {
  13
  14 using HmacKey = std::array<uint8_t, 32>;
  15 using ReadOnlyHmacKey = base::span<const uint8_t, 32>;
  16
  17 // Generate a 256 bit random hmac key.
  18 HmacKey GenerateRandomHmacKey();
  19
  20 // Returns a per-user, per-epoch hash of `top_domain` for the purpose of
  21 // deciding whether to return the random or top topic. The `hmac_key` is
  22 // per-use and `epoch_calculation_time` represents the epoch.
  23 uint64_t HashTopDomainForRandomOrTopTopicDecision(
  24     ReadOnlyHmacKey hmac_key,
  25     base::Time epoch_calculation_time,
  26     const std::string& top_domain);
  27
  28 // Returns a per-user, per-epoch hash of `top_domain` for the purpose of
  29 // deciding which random topic among the full taxonomy should be returned. The
  30 // `hmac_key` is per-use and `epoch_calculation_time` represents the epoch.
  31 uint64_t HashTopDomainForRandomTopicIndexDecision(
  32     ReadOnlyHmacKey hmac_key,
  33     base::Time epoch_calculation_time,
  34     const std::string& top_domain);
  35
  36 // Returns a per-user, per-epoch hash of `top_domain` for the purpose of
  37 // deciding which top topic to return. The `hmac_key` is per-user and
  38 // `epoch_calculation_time` represents the epoch.
  39 uint64_t HashTopDomainForTopTopicIndexDecision(
  40     ReadOnlyHmacKey hmac_key,
  41     base::Time epoch_calculation_time,
  42     const std::string& top_domain);
  43
  44 // Returns a per-user hash of `top_domain` for the purpose of deciding the epoch
  45 // switch-over time. The `hmac_key` is per-user.
  46 uint64_t HashTopDomainForEpochSwitchTimeDecision(ReadOnlyHmacKey hmac_key,
  47                                                  const std::string& top_domain);
  48
  49 // Returns a per-user hash of `context_domain` to be stored more efficiently in
  50 // disk and memory. The `hmac_key` is per-user. A per-user hash is necessary to
  51 // prevent a context from learning the topics that don't belong to it via
  52 // collision attack.
  53 HashedDomain HashContextDomainForStorage(ReadOnlyHmacKey hmac_key,
  54                                          const std::string& context_domain);
  55
  56 // Returns a hash of `main_frame_host` to be stored more efficiently in disk and
  57 // memory.
  58 HashedHost HashMainFrameHostForStorage(const std::string& main_frame_host);
  59
  60 // Override the key to be returned for subsequent invocations of
  61 // `GenerateRandomHmacKey()`.
  62 void OverrideHmacKeyForTesting(ReadOnlyHmacKey hmac_key);
  63
  64 }  // namespace browsing_topics
  65
  66 #endif  // COMPONENTS_BROWSING_TOPICS_UTIL_H_