base/token.h

   1 // Copyright 2018 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 BASE_TOKEN_H_
   6 #define BASE_TOKEN_H_
   7
   8 #include <stdint.h>
   9
  10 #include <string>
  11 #include <tuple>
  12
  13 #include "base/base_export.h"
  14 #include "base/containers/span.h"
  15 #include "base/strings/string_piece_forward.h"
  16 #include "third_party/abseil-cpp/absl/types/optional.h"
  17
  18 namespace base {
  19
  20 // A Token is a randomly chosen 128-bit integer. This class supports generation
  21 // from a cryptographically strong random source, or constexpr construction over
  22 // fixed values (e.g. to store a pre-generated constant value). Tokens are
  23 // similar in spirit and purpose to UUIDs, without many of the constraints and
  24 // expectations (such as byte layout and string representation) clasically
  25 // associated with UUIDs.
  26 class BASE_EXPORT Token {
  27  public:
  28   // Constructs a zero Token.
  29   constexpr Token() = default;
  30
  31   // Constructs a Token with |high| and |low| as its contents.
  32   constexpr Token(uint64_t high, uint64_t low) : words_{high, low} {}
  33
  34   constexpr Token(const Token&) = default;
  35   constexpr Token& operator=(const Token&) = default;
  36   constexpr Token(Token&&) noexcept = default;
  37   constexpr Token& operator=(Token&&) = default;
  38
  39   // Constructs a new Token with random |high| and |low| values taken from a
  40   // cryptographically strong random source. The result's |is_zero()| is
  41   // guaranteed to be false.
  42   static Token CreateRandom();
  43
  44   // The high and low 64 bits of this Token.
  45   constexpr uint64_t high() const { return words_[0]; }
  46   constexpr uint64_t low() const { return words_[1]; }
  47
  48   constexpr bool is_zero() const { return words_[0] == 0 && words_[1] == 0; }
  49
  50   span<const uint8_t, 16> AsBytes() const {
  51     return as_bytes(make_span(words_));
  52   }
  53
  54   constexpr bool operator==(const Token& other) const {
  55     return words_[0] == other.words_[0] && words_[1] == other.words_[1];
  56   }
  57
  58   constexpr bool operator!=(const Token& other) const {
  59     return !(*this == other);
  60   }
  61
  62   constexpr bool operator<(const Token& other) const {
  63     return std::tie(words_[0], words_[1]) <
  64            std::tie(other.words_[0], other.words_[1]);
  65   }
  66
  67   // Generates a string representation of this Token useful for e.g. logging.
  68   std::string ToString() const;
  69
  70   // FromString is the opposite of ToString. It returns absl::nullopt if the
  71   // |string_representation| is invalid.
  72   static absl::optional<Token> FromString(StringPiece string_representation);
  73
  74  private:
  75   // Note: Two uint64_t are used instead of uint8_t[16] in order to have a
  76   // simpler implementation, paricularly for |ToString()|, |is_zero()|, and
  77   // constexpr value construction.
  78
  79   uint64_t words_[2] = {0, 0};
  80 };
  81
  82 // For use in std::unordered_map.
  83 struct BASE_EXPORT TokenHash {
  84   size_t operator()(const Token& token) const;
  85 };
  86
  87 class Pickle;
  88 class PickleIterator;
  89
  90 // For serializing and deserializing Token values.
  91 BASE_EXPORT void WriteTokenToPickle(Pickle* pickle, const Token& token);
  92 BASE_EXPORT absl::optional<Token> ReadTokenFromPickle(
  93     PickleIterator* pickle_iterator);
  94
  95 }  // namespace base
  96
  97 #endif  // BASE_TOKEN_H_