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 17namespace base { 18 19struct 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. 34class 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 90BASE_EXPORT std::ostream& operator<<(std::ostream& out, 91 const UnguessableToken& token); 92 93// For use in std::unordered_map. 94struct 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