1  /** @file


2  * IPRT  Random Numbers and Byte Streams.


3  */


4 


5  /*


6  * Copyright (C) 20062023 Oracle and/or its affiliates.


7  *


8  * This file is part of VirtualBox base platform packages, as


9  * available from https://www.virtualbox.org.


10  *


11  * This program is free software; you can redistribute it and/or


12  * modify it under the terms of the GNU General Public License


13  * as published by the Free Software Foundation, in version 3 of the


14  * License.


15  *


16  * This program is distributed in the hope that it will be useful, but


17  * WITHOUT ANY WARRANTY; without even the implied warranty of


18  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU


19  * General Public License for more details.


20  *


21  * You should have received a copy of the GNU General Public License


22  * along with this program; if not, see <https://www.gnu.org/licenses>.


23  *


24  * The contents of this file may alternatively be used under the terms


25  * of the Common Development and Distribution License Version 1.0


26  * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included


27  * in the VirtualBox distribution, in which case the provisions of the


28  * CDDL are applicable instead of those of the GPL.


29  *


30  * You may elect to license modified versions of this file under the


31  * terms and conditions of either the GPL or the CDDL or both.


32  *


33  * SPDXLicenseIdentifier: GPL3.0only OR CDDL1.0


34  */


35 


36  #ifndef IPRT_INCLUDED_rand_h


37  #define IPRT_INCLUDED_rand_h


38  #ifndef RT_WITHOUT_PRAGMA_ONCE


39  # pragma once


40  #endif


41 


42  #include <iprt/cdefs.h>


43  #include <iprt/types.h>


44 


45  RT_C_DECLS_BEGIN


46 


47  /** @defgroup grp_rt_rand RTRand  Random Numbers and Byte Streams


48  * @ingroup grp_rt


49  * @{


50  */


51 


52  /**


53  * Fills a buffer with random bytes.


54  *


55  * @param pv Where to store the random bytes.


56  * @param cb Number of bytes to generate.


57  */


58  RTDECL(void) RTRandBytes(void *pv, size_t cb) RT_NO_THROW_PROTO;


59 


60  /**


61  * Generate a 32bit signed random number in the set [i32First..i32Last].


62  *


63  * @returns The random number.


64  * @param i32First First number in the set.


65  * @param i32Last Last number in the set.


66  */


67  RTDECL(int32_t) RTRandS32Ex(int32_t i32First, int32_t i32Last) RT_NO_THROW_PROTO;


68 


69  /**


70  * Generate a 32bit signed random number.


71  *


72  * @returns The random number.


73  */


74  RTDECL(int32_t) RTRandS32(void) RT_NO_THROW_PROTO;


75 


76  /**


77  * Generate a 32bit unsigned random number in the set [u32First..u32Last].


78  *


79  * @returns The random number.


80  * @param u32First First number in the set.


81  * @param u32Last Last number in the set.


82  */


83  RTDECL(uint32_t) RTRandU32Ex(uint32_t u32First, uint32_t u32Last) RT_NO_THROW_PROTO;


84 


85  /**


86  * Generate a 32bit unsigned random number.


87  *


88  * @returns The random number.


89  */


90  RTDECL(uint32_t) RTRandU32(void) RT_NO_THROW_PROTO;


91 


92  /**


93  * Generate a 64bit signed random number in the set [i64First..i64Last].


94  *


95  * @returns The random number.


96  * @param i64First First number in the set.


97  * @param i64Last Last number in the set.


98  */


99  RTDECL(int64_t) RTRandS64Ex(int64_t i64First, int64_t i64Last) RT_NO_THROW_PROTO;


100 


101  /**


102  * Generate a 64bit signed random number.


103  *


104  * @returns The random number.


105  */


106  RTDECL(int64_t) RTRandS64(void) RT_NO_THROW_PROTO;


107 


108  /**


109  * Generate a 64bit unsigned random number in the set [u64First..u64Last].


110  *


111  * @returns The random number.


112  * @param u64First First number in the set.


113  * @param u64Last Last number in the set.


114  */


115  RTDECL(uint64_t) RTRandU64Ex(uint64_t u64First, uint64_t u64Last) RT_NO_THROW_PROTO;


116 


117  /**


118  * Generate a 64bit unsigned random number.


119  *


120  * @returns The random number.


121  */


122  RTDECL(uint64_t) RTRandU64(void) RT_NO_THROW_PROTO;


123 


124 


125  /**


126  * Create an instance of the default random number generator.


127  *


128  * @returns IPRT status code.


129  * @param phRand Where to return the handle to the new random number


130  * generator.


131  */


132  RTDECL(int) RTRandAdvCreate(PRTRAND phRand) RT_NO_THROW_PROTO;


133 


134  /**


135  * Create an instance of the default pseudo random number generator.


136  *


137  * @returns IPRT status code.


138  * @param phRand Where to store the handle to the generator.


139  */


140  RTDECL(int) RTRandAdvCreatePseudo(PRTRAND phRand) RT_NO_THROW_PROTO;


141 


142  /**


143  * Create an instance of the ParkMiller pseudo random number generator.


144  *


145  * @returns IPRT status code.


146  * @param phRand Where to store the handle to the generator.


147  */


148  RTDECL(int) RTRandAdvCreateParkMiller(PRTRAND phRand) RT_NO_THROW_PROTO;


149 


150  /**


151  * Create an instance of the faster random number generator for the OS.


152  *


153  * @returns IPRT status code.


154  * @retval VERR_NOT_SUPPORTED on platforms which doesn't have this feature.


155  * @retval VERR_FILE_NOT_FOUND on system where the random generator hasn't


156  * been installed or configured correctly.


157  * @retval VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.


158  *


159  * @param phRand Where to store the handle to the generator.


160  *


161  * @remarks Think /dev/urandom.


162  */


163  RTDECL(int) RTRandAdvCreateSystemFaster(PRTRAND phRand) RT_NO_THROW_PROTO;


164 


165  /**


166  * Create an instance of the truer random number generator for the OS.


167  *


168  * Don't use this unless you seriously need good random numbers because most


169  * systems will have will have problems producing sufficient entropy for this


170  * and you'll end up blocking while it accumulates.


171  *


172  * @returns IPRT status code.


173  * @retval VERR_NOT_SUPPORTED on platforms which doesn't have this feature.


174  * @retval VERR_FILE_NOT_FOUND on system where the random generator hasn't


175  * been installed or configured correctly.


176  * @retval VERR_PATH_NOT_FOUND for the same reasons as VERR_FILE_NOT_FOUND.


177  *


178  * @param phRand Where to store the handle to the generator.


179  *


180  * @remarks Think /dev/random.


181  */


182  RTDECL(int) RTRandAdvCreateSystemTruer(PRTRAND phRand) RT_NO_THROW_PROTO;


183 


184  /**


185  * Destroys a random number generator.


186  *


187  * @returns IPRT status code.


188  * @param hRand Handle to the random number generator.


189  */


190  RTDECL(int) RTRandAdvDestroy(RTRAND hRand) RT_NO_THROW_PROTO;


191 


192  /**


193  * Generic method for seeding of a random number generator.


194  *


195  * The different generators may have specialized methods for


196  * seeding, use one of those if you desire better control


197  * over the result.


198  *


199  * @returns IPRT status code.


200  * @retval VERR_NOT_SUPPORTED if it isn't a pseudo generator.


201  *


202  * @param hRand Handle to the random number generator.


203  * @param u64Seed Seed.


204  */


205  RTDECL(int) RTRandAdvSeed(RTRAND hRand, uint64_t u64Seed) RT_NO_THROW_PROTO;


206 


207  /**


208  * Save the current state of a pseudo generator.


209  *


210  * This can be use to save the state so it can later be resumed at the same


211  * position.


212  *


213  * @returns IPRT status code.


214  * @retval VINF_SUCCESS on success. *pcbState contains the length of the


215  * returned string and pszState contains the state string.


216  * @retval VERR_BUFFER_OVERFLOW if the supplied buffer is too small. *pcbState


217  * will contain the necessary buffer size.


218  * @retval VERR_NOT_SUPPORTED by nonpsuedo generators.


219  *


220  * @param hRand Handle to the random number generator.


221  * @param pszState Where to store the state. The returned string will be


222  * null terminated and printable.


223  * @param pcbState The size of the buffer pszState points to on input, the


224  * size required / used on return (including the


225  * terminator, thus the 'cb' instead of 'cch').


226  */


227  RTDECL(int) RTRandAdvSaveState(RTRAND hRand, char *pszState, size_t *pcbState) RT_NO_THROW_PROTO;


228 


229  /**


230  * Restores the state of a pseudo generator.


231  *


232  * The state must have been obtained using RTRandAdvGetState.


233  *


234  * @returns IPRT status code.


235  * @retval VERR_PARSE_ERROR if the state string is malformed.


236  * @retval VERR_NOT_SUPPORTED by nonpsuedo generators.


237  *


238  * @param hRand Handle to the random number generator.


239  * @param pszState The state to load.


240  */


241  RTDECL(int) RTRandAdvRestoreState(RTRAND hRand, char const *pszState) RT_NO_THROW_PROTO;


242 


243  /**


244  * Fills a buffer with random bytes.


245  *


246  * @param hRand Handle to the random number generator.


247  * @param pv Where to store the random bytes.


248  * @param cb Number of bytes to generate.


249  */


250  RTDECL(void) RTRandAdvBytes(RTRAND hRand, void *pv, size_t cb) RT_NO_THROW_PROTO;


251 


252  /**


253  * Generate a 32bit signed random number in the set [i32First..i32Last].


254  *


255  * @returns The random number.


256  * @param hRand Handle to the random number generator.


257  * @param i32First First number in the set.


258  * @param i32Last Last number in the set.


259  */


260  RTDECL(int32_t) RTRandAdvS32Ex(RTRAND hRand, int32_t i32First, int32_t i32Last) RT_NO_THROW_PROTO;


261 


262  /**


263  * Generate a 32bit signed random number.


264  *


265  * @returns The random number.


266  * @param hRand Handle to the random number generator.


267  */


268  RTDECL(int32_t) RTRandAdvS32(RTRAND hRand) RT_NO_THROW_PROTO;


269 


270  /**


271  * Generate a 32bit unsigned random number in the set [u32First..u32Last].


272  *


273  * @returns The random number.


274  * @param hRand Handle to the random number generator.


275  * @param u32First First number in the set.


276  * @param u32Last Last number in the set.


277  */


278  RTDECL(uint32_t) RTRandAdvU32Ex(RTRAND hRand, uint32_t u32First, uint32_t u32Last) RT_NO_THROW_PROTO;


279 


280  /**


281  * Generate a 32bit unsigned random number.


282  *


283  * @returns The random number.


284  * @param hRand Handle to the random number generator.


285  */


286  RTDECL(uint32_t) RTRandAdvU32(RTRAND hRand) RT_NO_THROW_PROTO;


287 


288  /**


289  * Generate a 64bit signed random number in the set [i64First..i64Last].


290  *


291  * @returns The random number.


292  * @param hRand Handle to the random number generator.


293  * @param i64First First number in the set.


294  * @param i64Last Last number in the set.


295  */


296  RTDECL(int64_t) RTRandAdvS64Ex(RTRAND hRand, int64_t i64First, int64_t i64Last) RT_NO_THROW_PROTO;


297 


298  /**


299  * Generate a 64bit signed random number.


300  *


301  * @returns The random number.


302  */


303  RTDECL(int64_t) RTRandAdvS64(RTRAND hRand) RT_NO_THROW_PROTO;


304 


305  /**


306  * Generate a 64bit unsigned random number in the set [u64First..u64Last].


307  *


308  * @returns The random number.


309  * @param hRand Handle to the random number generator.


310  * @param u64First First number in the set.


311  * @param u64Last Last number in the set.


312  */


313  RTDECL(uint64_t) RTRandAdvU64Ex(RTRAND hRand, uint64_t u64First, uint64_t u64Last) RT_NO_THROW_PROTO;


314 


315  /**


316  * Generate a 64bit unsigned random number.


317  *


318  * @returns The random number.


319  * @param hRand Handle to the random number generator.


320  */


321  RTDECL(uint64_t) RTRandAdvU64(RTRAND hRand) RT_NO_THROW_PROTO;


322 


323 


324  /** @} */


325 


326  RT_C_DECLS_END


327 


328 


329  #endif /* !IPRT_INCLUDED_rand_h */


330 

