1 /* 2 * Copyright (c) 2019, The OpenThread Authors. 3 * All rights reserved. 4 * 5 * Redistribution and use in source and binary forms, with or without 6 * modification, are permitted provided that the following conditions are met: 7 * 1. Redistributions of source code must retain the above copyright 8 * notice, this list of conditions and the following disclaimer. 9 * 2. Redistributions in binary form must reproduce the above copyright 10 * notice, this list of conditions and the following disclaimer in the 11 * documentation and/or other materials provided with the distribution. 12 * 3. Neither the name of the copyright holder nor the 13 * names of its contributors may be used to endorse or promote products 14 * derived from this software without specific prior written permission. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" 17 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE 20 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 23 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 24 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 25 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 26 * POSSIBILITY OF SUCH DAMAGE. 27 */ 28 29 /** 30 * @file 31 * @brief 32 * This file defines the OpenThread non cryptographic random number generator API. 33 */ 34 35 #ifndef OPENTHREAD_RANDOM_H_ 36 #define OPENTHREAD_RANDOM_H_ 37 38 #include <stdint.h> 39 40 #ifdef __cplusplus 41 extern "C" { 42 #endif 43 44 /** 45 * @addtogroup api-random-non-crypto 46 * 47 * @brief 48 * This module includes functions that generates non cryptographic random numbers. 49 * 50 * @{ 51 */ 52 53 /** 54 * Generates and returns a random `uint32_t` value. 55 * 56 * @returns A random `uint32_t` value. 57 */ 58 uint32_t otRandomNonCryptoGetUint32(void); 59 60 /** 61 * Generates and returns a random byte. 62 * 63 * @returns A random `uint8_t` value. 64 */ 65 uint8_t otRandomNonCryptoGetUint8(void); 66 67 /** 68 * Generates and returns a random `uint16_t` value. 69 * 70 * @returns A random `uint16_t` value. 71 */ 72 uint16_t otRandomNonCryptoGetUint16(void); 73 74 /** 75 * Generates and returns a random `uint8_t` value within a given range `[aMin, aMax)`. 76 * 77 * @param[in] aMin A minimum value (this value can be included in returned random result). 78 * @param[in] aMax A maximum value (this value is excluded from returned random result). 79 * 80 * @returns A random `uint8_t` value in the given range (i.e., aMin <= random value < aMax). 81 */ 82 uint8_t otRandomNonCryptoGetUint8InRange(uint8_t aMin, uint8_t aMax); 83 84 /** 85 * Generates and returns a random `uint16_t` value within a given range `[aMin, aMax)`. 86 * 87 * @note The returned random value can include the @p aMin value but excludes the @p aMax. 88 * 89 * @param[in] aMin A minimum value (this value can be included in returned random result). 90 * @param[in] aMax A maximum value (this value is excluded from returned random result). 91 * 92 * @returns A random `uint16_t` value in the given range (i.e., aMin <= random value < aMax). 93 */ 94 uint16_t otRandomNonCryptoGetUint16InRange(uint16_t aMin, uint16_t aMax); 95 96 /** 97 * Generates and returns a random `uint32_t` value within a given range `[aMin, aMax)`. 98 * 99 * @note The returned random value can include the @p aMin value but excludes the @p aMax. 100 * 101 * @param[in] aMin A minimum value (this value can be included in returned random result). 102 * @param[in] aMax A maximum value (this value is excluded from returned random result). 103 * 104 * @returns A random `uint32_t` value in the given range (i.e., aMin <= random value < aMax). 105 */ 106 uint32_t otRandomNonCryptoGetUint32InRange(uint32_t aMin, uint32_t aMax); 107 108 /** 109 * Fills a given buffer with random bytes. 110 * 111 * @param[out] aBuffer A pointer to a buffer to fill with the random bytes. 112 * @param[in] aSize Size of buffer (number of bytes to fill). 113 */ 114 void otRandomNonCryptoFillBuffer(uint8_t *aBuffer, uint16_t aSize); 115 116 /** 117 * Adds a random jitter within a given range to a given value. 118 * 119 * @param[in] aValue A value to which the random jitter is added. 120 * @param[in] aJitter Maximum jitter. Random jitter is selected from the range `[-aJitter, aJitter]`. 121 * 122 * @returns The given value with an added random jitter. 123 */ 124 uint32_t otRandomNonCryptoAddJitter(uint32_t aValue, uint16_t aJitter); 125 126 /** 127 * @} 128 */ 129 130 #ifdef __cplusplus 131 } // extern "C" 132 #endif 133 134 #endif // OPENTHREAD_RANDOM_H_ 135