Add base::UnguessableToken

base/nonce.h

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef BASE_NONCE_H_
+#define BASE_NONCE_H_
+
+#include <stdint.h>
+#include <string.h>
+#include <tuple>
+
+#include "base/base_export.h"
+#include "base/hash.h"
+
+namespace base {
+
+// An Nonce is a cryptographically strong, randomly generated, unguessable 128

[dcheng, 2016/09/13 23:19:05]

A Nonce is an unguessable 128-bit token generated from a cryptographically
strong random source. Nonce should be used when <insert scenarios here>.

[tguilbert, 2016/09/14 22:40:47]

Done. However, I don't know what all useful scenarios for Nonces are. I know
they can be used in some authentication schemes, but I think adding further uses
might be out of scope for the comments of this header file.

+// bit token.
+//
+// TO CREATE NEW NONCES, ONLY USE GENERATE()!

[dcheng, 2016/09/13 23:19:05]

Suggested wording:

Use Generate() for creating new unguessable nonces. Deserialize() is a helper
intended only for implementing IPC deserialization.

(I think we don't need to repeat the bit about cryptographically strong random,
since it's such a long phrase =)

[tguilbert, 2016/09/14 22:40:47]

TY for the better wording! Done.

+// The Generate() function is guaranteed to be cryptographically strong random.
+// Deserialize() is only meant to deserialize Nonces that were created via
+// Generate(), and sent across processes as two uint64_t.
+class BASE_EXPORT Nonce {
+ public:
+  // Generates a unique, strongly random, unguessable nonce.

[dcheng, 2016/09/13 23:19:05]

Ditto: "Create an unguessable and unique nonce."

[tguilbert, 2016/09/14 22:40:47]

Done.

+  // USE ONLY THIS FUNCTION TO GENERATE NEW NONCES.
+  static Nonce Generate();

[Ken Rockot(use gerrit already), 2016/09/13 23:21:13]

Why Generate? Why can't the default constructor just do what most consumers will
want it to do? We could add a special constructor for creating an empty Nonce
(e.g. over nullptr_t or something)?

[sandersd (OOO until July 31), 2016/09/13 23:51:53]

I do like the clarity of explicitly calling Generate(). A different option would
be to make the constructor protected. Both solutions are fine by me.

[tguilbert, 2016/09/14 22:40:47]

As per the discussions floating around, I have maintained the Generate()
function (in order to not generate random bits when simply reserving memory on
the stack, if it's about to be overwritten immediately after, like in some Mojo
generated code).

I have added DCHECKs and CHECKs in various places to palliate the security
missuses that would come from forgetting to Generate() Nonce.

More on this in the main discussion.

+
+  // Returns a nonce built from the high/low bytes provided.
+  // It should only be used in deserialization scenarios.
+  static Nonce Deserialize(uint64_t high, uint64_t low);
+
+  // Creates a 0 initiliazed Nonce.

[dcheng, 2016/09/13 23:19:05]

Nit: Create a zero-initialized Nonce (so it doesn't look like an O)

[Ken Rockot(use gerrit already), 2016/09/13 23:21:13]

nit: initialized (typo)

[tguilbert, 2016/09/14 22:40:47]

Done.

+  Nonce();
+
+  bool is_empty() const { return high_ == 0 && low_ == 0; }
+
+  uint64_t high() const { return high_; }
+
+  uint64_t low() const { return low_; }
+
+  std::string ToString() const;
+
+  bool operator<(const Nonce& other) const {
+    return std::tie(high_, low_) < std::tie(other.high_, other.low_);
+  }
+
+  bool operator==(const Nonce& other) const {
+    return high_ == other.high_ && low_ == other.low_;
+  }
+
+  bool operator!=(const Nonce& other) const { return !operator==(other); }
+
+ private:
+  Nonce(uint64_t high, uint64_t low);
+
+  // Note: Two uint64_t are used instead of uint8_t[16], in order to have a
+  // simpler ToString() and is_null().
+  uint64_t high_;
+  uint64_t low_;
+};
+
+// For use in std::unordered_map.
+struct NonceHash {
+  size_t operator()(const base::Nonce& nonce) const {
+    return base::HashInts64(nonce.high(), nonce.low());
+  }
+};
+
+// If base::Nonce is no longer 128 bits, the IPC serialization logic and Mojo

[DaleCurtis, 2016/09/13 23:39:48]

Drive-by: Worth moving to C++ file to avoid all includes from running
static_assert? I.e. in c++ it'll only run once, versus once for each include.

[tguilbert, 2016/09/14 22:40:47]

Done.

+// StructTraits should be updated to match the size of the struct.
+static_assert(sizeof(Nonce) == 2 * sizeof(uint64_t),
+              "base::Nonce should be of size 2 * sizeof(uint64_t).");
+
+}  // namespace base
+
+#endif  // BASE_NONCE_H_