include/iprt/rand.h

   1 /** @file
   2  * IPRT - Random Numbers and Byte Streams.
   3  */
   4
   5 /*
   6  * Copyright (C) 2006-2024 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  * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.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 32-bit 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 32-bit 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 32-bit 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 32-bit 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 64-bit 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 64-bit 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 64-bit 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 64-bit 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 Park-Miller 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 non-psuedo 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 non-psuedo 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 32-bit 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 32-bit 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 32-bit 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 32-bit 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 64-bit 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 64-bit 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 64-bit 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 64-bit 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