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 5 #ifndef BASE_UNGUESSABLE_TOKEN_H_ 6 #define BASE_UNGUESSABLE_TOKEN_H_ 7 8 #include <stdint.h> 9 #include <string.h> 10 #include <iosfwd> 11 #include <tuple> 12 13 #include "base/base_export.h" 14 #include "base/hash.h" 15 #include "base/logging.h" 16 17 namespace base { 18 19 struct UnguessableTokenHash; 20 21 // A UnguessableToken is an 128-bit token generated from a cryptographically 22 // strong random source. 23 // 24 // UnguessableToken should be used when a sensitive ID needs to be unguessable, 25 // and is shared across processes. It can be used as part of a larger aggregate 26 // type, or as an ID in and of itself. 27 // 28 // Use Create() for creating new UnguessableTokens. 29 // 30 // NOTE: It is illegal to send empty UnguessableTokens across processes, and 31 // sending/receiving empty tokens should be treated as a security issue. 32 // If there is a valid scenario for sending "no token" across processes, 33 // base::Optional should be used instead of an empty token. 34 class BASE_EXPORT UnguessableToken { 35 public: 36 // Create a unique UnguessableToken. 37 static UnguessableToken Create(); 38 39 // Return a UnguessableToken built from the high/low bytes provided. 40 // It should only be used in deserialization scenarios. 41 // 42 // NOTE: If the deserialized token is empty, it means that it was never 43 // initialized via Create(). This is a security issue, and should be handled. 44 static UnguessableToken Deserialize(uint64_t high, uint64_t low); 45 46 // Creates an empty UnguessableToken. 47 // Assign to it with Create() before using it. 48 constexpr UnguessableToken() = default; 49 50 // NOTE: Serializing an empty UnguessableToken is an illegal operation. 51 uint64_t GetHighForSerialization() const { 52 DCHECK(!is_empty()); 53 return high_; 54 }; 55 56 // NOTE: Serializing an empty UnguessableToken is an illegal operation. 57 uint64_t GetLowForSerialization() const { 58 DCHECK(!is_empty()); 59 return low_; 60 } 61 62 bool is_empty() const { return high_ == 0 && low_ == 0; } 63 64 std::string ToString() const; 65 66 explicit operator bool() const { return !is_empty(); } 67 68 bool operator<(const UnguessableToken& other) const { 69 return std::tie(high_, low_) < std::tie(other.high_, other.low_); 70 } 71 72 bool operator==(const UnguessableToken& other) const { 73 return high_ == other.high_ && low_ == other.low_; 74 } 75 76 bool operator!=(const UnguessableToken& other) const { 77 return !(*this == other); 78 } 79 80 private: 81 friend struct UnguessableTokenHash; 82 UnguessableToken(uint64_t high, uint64_t low); 83 84 // Note: Two uint64_t are used instead of uint8_t[16], in order to have a 85 // simpler ToString() and is_empty(). 86 uint64_t high_ = 0; 87 uint64_t low_ = 0; 88 }; 89 90 BASE_EXPORT std::ostream& operator<<(std::ostream& out, 91 const UnguessableToken& token); 92 93 // For use in std::unordered_map. 94 struct UnguessableTokenHash { 95 size_t operator()(const base::UnguessableToken& token) const { 96 DCHECK(token); 97 return base::HashInts64(token.high_, token.low_); 98 } 99 }; 100 101 } // namespace base 102 103 #endif // BASE_UNGUESSABLE_TOKEN_H_ 104
