unguessable_token.h 4.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132
  1. // Copyright 2016 The Chromium Authors. All rights reserved.
  2. // Use of this source code is governed by a BSD-style license that can be
  3. // found in the LICENSE file.
  4. #ifndef BASE_UNGUESSABLE_TOKEN_H_
  5. #define BASE_UNGUESSABLE_TOKEN_H_
  6. #include <stdint.h>
  7. #include <string.h>
  8. #include <iosfwd>
  9. #include <tuple>
  10. #include "base/base_export.h"
  11. #include "base/check.h"
  12. #include "base/hash/hash.h"
  13. #include "base/token.h"
  14. namespace base {
  15. struct UnguessableTokenHash;
  16. // UnguessableToken is, like Token, a randomly chosen 128-bit value. Unlike
  17. // Token, a new UnguessableToken is always generated at runtime from a
  18. // cryptographically strong random source (or copied or serialized and
  19. // deserialized from another such UnguessableToken). Also unlike Token, the ==
  20. // and != operators are constant time. It can be used as part of a larger
  21. // aggregate type, or as an ID in and of itself.
  22. //
  23. // An UnguessableToken is a strong *bearer token*. Bearer tokens are like HTTP
  24. // cookies: if a caller has the token, the callee thereby considers the caller
  25. // authorized to request the operation the callee performs.
  26. //
  27. // UnguessableToken can be used when the resource associated with the ID needs
  28. // to be protected against manipulation by other untrusted agents in the system,
  29. // and there is no other convenient way to verify the authority of the agent to
  30. // do so (because the resource is part of a table shared across processes, for
  31. // instance). In such a scheme, knowledge of the token value in and of itself is
  32. // sufficient proof of authority to carry out an operation on the associated
  33. // resource.
  34. //
  35. // Use Create() for creating new UnguessableTokens.
  36. //
  37. // NOTE: It is illegal to send empty UnguessableTokens across processes, and
  38. // sending/receiving empty tokens should be treated as a security issue. If
  39. // there is a valid scenario for sending "no token" across processes, use
  40. // absl::optional instead of an empty token.
  41. class BASE_EXPORT UnguessableToken {
  42. public:
  43. // Create a unique UnguessableToken.
  44. static UnguessableToken Create();
  45. // Returns a reference to a global null UnguessableToken. This should only be
  46. // used for functions that need to return a reference to an UnguessableToken,
  47. // and should not be used as a general-purpose substitute for invoking the
  48. // default constructor.
  49. static const UnguessableToken& Null();
  50. // Return a UnguessableToken built from the high/low bytes provided.
  51. // It should only be used in deserialization scenarios.
  52. //
  53. // NOTE: If the deserialized token is empty, it means that it was never
  54. // initialized via Create(). This is a security issue, and should be handled.
  55. static UnguessableToken Deserialize(uint64_t high, uint64_t low);
  56. // Creates an empty UnguessableToken.
  57. // Assign to it with Create() before using it.
  58. constexpr UnguessableToken() = default;
  59. constexpr UnguessableToken(const UnguessableToken&) = default;
  60. constexpr UnguessableToken& operator=(const UnguessableToken&) = default;
  61. constexpr UnguessableToken(UnguessableToken&&) noexcept = default;
  62. constexpr UnguessableToken& operator=(UnguessableToken&&) = default;
  63. // NOTE: Serializing an empty UnguessableToken is an illegal operation.
  64. uint64_t GetHighForSerialization() const {
  65. DCHECK(!is_empty());
  66. return token_.high();
  67. }
  68. // NOTE: Serializing an empty UnguessableToken is an illegal operation.
  69. uint64_t GetLowForSerialization() const {
  70. DCHECK(!is_empty());
  71. return token_.low();
  72. }
  73. constexpr bool is_empty() const { return token_.is_zero(); }
  74. // Hex representation of the unguessable token.
  75. std::string ToString() const { return token_.ToString(); }
  76. explicit constexpr operator bool() const { return !is_empty(); }
  77. span<const uint8_t, 16> AsBytes() const { return token_.AsBytes(); }
  78. constexpr bool operator<(const UnguessableToken& other) const {
  79. return token_ < other.token_;
  80. }
  81. bool operator==(const UnguessableToken& other) const;
  82. bool operator!=(const UnguessableToken& other) const {
  83. return !(*this == other);
  84. }
  85. #if defined(UNIT_TEST)
  86. static UnguessableToken CreateForTesting(uint64_t high, uint64_t low) {
  87. return Deserialize(high, low);
  88. }
  89. #endif
  90. private:
  91. friend struct UnguessableTokenHash;
  92. explicit UnguessableToken(const Token& token);
  93. base::Token token_;
  94. };
  95. BASE_EXPORT std::ostream& operator<<(std::ostream& out,
  96. const UnguessableToken& token);
  97. // For use in std::unordered_map.
  98. struct UnguessableTokenHash {
  99. size_t operator()(const base::UnguessableToken& token) const {
  100. DCHECK(token);
  101. return TokenHash()(token.token_);
  102. }
  103. };
  104. } // namespace base
  105. #endif // BASE_UNGUESSABLE_TOKEN_H_