seed_material.h (3689B)
1 // Copyright 2017 The Abseil Authors. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 #ifndef ABSL_RANDOM_INTERNAL_SEED_MATERIAL_H_ 16 #define ABSL_RANDOM_INTERNAL_SEED_MATERIAL_H_ 17 18 #include <cassert> 19 #include <cstdint> 20 #include <cstdlib> 21 #include <string> 22 #include <vector> 23 24 #include "absl/base/config.h" 25 #include "absl/random/internal/fast_uniform_bits.h" 26 #include "absl/types/optional.h" 27 #include "absl/types/span.h" 28 29 namespace absl { 30 ABSL_NAMESPACE_BEGIN 31 namespace random_internal { 32 33 // Returns the number of 32-bit blocks needed to contain the given number of 34 // bits. 35 constexpr size_t SeedBitsToBlocks(size_t seed_size) { 36 return (seed_size + 31) / 32; 37 } 38 39 // Amount of entropy (measured in bits) used to instantiate a Seed Sequence, 40 // with which to create a URBG. 41 constexpr size_t kEntropyBitsNeeded = 256; 42 43 // Amount of entropy (measured in 32-bit blocks) used to instantiate a Seed 44 // Sequence, with which to create a URBG. 45 constexpr size_t kEntropyBlocksNeeded = 46 random_internal::SeedBitsToBlocks(kEntropyBitsNeeded); 47 48 static_assert(kEntropyBlocksNeeded > 0, 49 "Entropy used to seed URBGs must be nonzero."); 50 51 // Attempts to fill a span of uint32_t-values using an OS-provided source of 52 // true entropy (eg. /dev/urandom) into an array of uint32_t blocks of data. The 53 // resulting array may be used to initialize an instance of a class conforming 54 // to the C++ Standard "Seed Sequence" concept [rand.req.seedseq]. 55 // 56 // If values.data() == nullptr, the behavior is undefined. 57 [[nodiscard]] 58 bool ReadSeedMaterialFromOSEntropy(absl::Span<uint32_t> values); 59 60 // Attempts to fill a span of uint32_t-values using variates generated by an 61 // existing instance of a class conforming to the C++ Standard "Uniform Random 62 // Bit Generator" concept [rand.req.urng]. The resulting data may be used to 63 // initialize an instance of a class conforming to the C++ Standard 64 // "Seed Sequence" concept [rand.req.seedseq]. 65 // 66 // If urbg == nullptr or values.data() == nullptr, the behavior is undefined. 67 template <typename URBG> 68 [[nodiscard]] bool ReadSeedMaterialFromURBG(URBG* urbg, 69 absl::Span<uint32_t> values) { 70 random_internal::FastUniformBits<uint32_t> distr; 71 72 assert(urbg != nullptr && values.data() != nullptr); 73 if (urbg == nullptr || values.data() == nullptr) { 74 return false; 75 } 76 77 for (uint32_t& seed_value : values) { 78 seed_value = distr(*urbg); 79 } 80 return true; 81 } 82 83 // Mixes given sequence of values with into given sequence of seed material. 84 // Time complexity of this function is O(sequence.size() * 85 // seed_material.size()). 86 // 87 // Algorithm is based on code available at 88 // https://gist.github.com/imneme/540829265469e673d045 89 // by Melissa O'Neill. 90 void MixIntoSeedMaterial(absl::Span<const uint32_t> sequence, 91 absl::Span<uint32_t> seed_material); 92 93 // Returns salt value. 94 // 95 // Salt is obtained only once and stored in static variable. 96 // 97 // May return empty value if obtaining the salt was not possible. 98 absl::optional<uint32_t> GetSaltMaterial(); 99 100 } // namespace random_internal 101 ABSL_NAMESPACE_END 102 } // namespace absl 103 104 #endif // ABSL_RANDOM_INTERNAL_SEED_MATERIAL_H_