randLIB.h

00001 /*
00002  * Copyright (c) 2014-2015 ARM Limited. All rights reserved.
00003  * SPDX-License-Identifier: Apache-2.0
00004  * Licensed under the Apache License, Version 2.0 (the License); you may
00005  * not use this file except in compliance with the License.
00006  * You may obtain a copy of the License at
00007  *
00008  * http://www.apache.org/licenses/LICENSE-2.0
00009  *
00010  * Unless required by applicable law or agreed to in writing, software
00011  * distributed under the License is distributed on an AS IS BASIS, WITHOUT
00012  * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
00013  * See the License for the specific language governing permissions and
00014  * limitations under the License.
00015  */
00016 
00017 /**
00018  * \file randLIB.h
00019  * \brief Pseudo Random Library API:
00020  *
00021  *
00022  * \section net-boot Network Bootstrap Control API:
00023  *  - randLIB_seed_random(), Set seed for pseudo random
00024  *  - randLIB_get_8bit(), Generate 8-bit random number
00025  *  - randLIB_get_16bit(),Generate 16-bit random number
00026  *  - randLIB_get_32bit(),Generate 32-bit random number
00027  *  - randLIB_get_n_bytes_random(), Generate n-bytes random numbers
00028  *
00029  */
00030 
00031 #ifndef RANDLIB_H_
00032 #define RANDLIB_H_
00033 
00034 #include <stdint.h>
00035 
00036 #ifdef __cplusplus
00037 extern "C" {
00038 #endif
00039 
00040 /**
00041  * This library is made for getting random numbers for Timing needs in protocols.
00042  *
00043  * **not safe to use for security or cryptographic operations.**
00044  *
00045  */
00046 
00047 
00048 /**
00049   * \brief Init seed for Pseudo Random.
00050   *
00051   * \return None
00052   *
00053   */
00054 extern void randLIB_seed_random(void);
00055 
00056 /**
00057   * \brief Generate 8-bit random number.
00058   *
00059   * \param None
00060   * \return 8-bit random number
00061   *
00062   */
00063 extern uint8_t randLIB_get_8bit(void);
00064 
00065 /**
00066   * \brief Generate 16-bit random number.
00067   *
00068   * \param None
00069   * \return 16-bit random number
00070   *
00071   */
00072 extern uint16_t randLIB_get_16bit(void);
00073 
00074 /**
00075   * \brief Generate 32-bit random number.
00076   *
00077   * \param None
00078   * \return 16-bit random number
00079   *
00080   */
00081 extern uint32_t randLIB_get_32bit(void);
00082 
00083 /**
00084   * \brief Generate n-bytes random numbers.
00085   *
00086   * \param data_ptr pointer where random will be stored
00087   * \param eight_bit_boundary how many bytes need random
00088   * \return 0 process valid
00089   * \return -1 Unsupported Parameters
00090   *
00091   */
00092 extern int8_t randLIB_get_n_bytes_random(uint8_t *data_ptr, uint8_t eight_bit_boundary);
00093 
00094 /**
00095   * \brief Generate a random number within a range.
00096   *
00097   * The result is linearly distributed in the range [min..max], inclusive.
00098   *
00099   * \param min minimum value that can be generated
00100   * \param max maximum value that can be generated
00101   */
00102 uint16_t randLIB_get_random_in_range(uint16_t min, uint16_t max);
00103 
00104 /**
00105   * \brief Randomise a base 32-bit number by a jitter factor
00106   *
00107   * The result is linearly distributed in the jitter range, which is expressed
00108   * as fixed-point unsigned 1.15 values. For example, to produce a number in the
00109   * range [0.75 * base, 1.25 * base], set min_factor to 0x6000 and max_factor to
00110   * 0xA000.
00111   *
00112   * Result is clamped to 0xFFFFFFFF if it overflows.
00113   *
00114   * \param base The base 32-bit value
00115   * \param min_factor The minimum value for the random factor
00116   * \param max_factor The maximum value for the random factor
00117   */
00118 uint32_t randLIB_randomise_base(uint32_t base, uint16_t min_factor, uint16_t max_factor);
00119 
00120 #ifdef __cplusplus
00121 }
00122 #endif
00123 #endif /* RANDLIB_H_ */