1 // Copyright 2020 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // 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, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 #include <cstddef> 17 #include <cstdint> 18 #include <span> 19 20 #include "pw_bytes/span.h" 21 #include "pw_status/status_with_size.h" 22 23 namespace pw::random { 24 25 // A random generator uses injected entropy to generate random values. Many of 26 // the guarantees for this interface are provided at the level of the 27 // implementations. In general: 28 // * DO NOT assume a generator is cryptographically secure. 29 // * DO NOT assume uniformity of generated data. 30 // * DO assume a generator can be exhausted. 31 class RandomGenerator { 32 public: 33 virtual ~RandomGenerator() = default; 34 35 template <class T> GetInt(T & dest)36 StatusWithSize GetInt(T& dest) { 37 static_assert(std::is_integral<T>::value, 38 "Use Get() for non-integral types"); 39 return Get({reinterpret_cast<std::byte*>(&dest), sizeof(T)}); 40 } 41 42 // Populates the destination buffer with a randomly generated value. Returns: 43 // OK - Successfully filled the destination buffer with random data. 44 // RESOURCE_EXHAUSTED - Filled the buffer with the returned number of bytes. 45 // The returned size is number of complete bytes with random data. 46 virtual StatusWithSize Get(ByteSpan dest) = 0; 47 48 // Injects entropy into the pool. `data` may have up to 32 bits of random 49 // entropy. If the number of bits of entropy is less than 32, entropy is 50 // assumed to be stored in the least significant bits of `data`. 51 virtual void InjectEntropyBits(uint32_t data, uint_fast8_t num_bits) = 0; 52 53 // Injects entropy into the pool byte-by-byte. InjectEntropy(ConstByteSpan data)54 void InjectEntropy(ConstByteSpan data) { 55 for (std::byte b : data) { 56 InjectEntropyBits(std::to_integer<uint32_t>(b), /*num_bits=*/8); 57 } 58 } 59 }; 60 61 } // namespace pw::random 62