1 | /* $Id: rand.h 93115 2022-01-01 11:31:46Z vboxsync $ */
|
---|
2 | /** @file
|
---|
3 | * IPRT - Internal RTRand header
|
---|
4 | */
|
---|
5 |
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2006-2022 Oracle Corporation
|
---|
8 | *
|
---|
9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
12 | * General Public License (GPL) as published by the Free Software
|
---|
13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
16 | *
|
---|
17 | * The contents of this file may alternatively be used under the terms
|
---|
18 | * of the Common Development and Distribution License Version 1.0
|
---|
19 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
20 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
21 | * CDDL are applicable instead of those of the GPL.
|
---|
22 | *
|
---|
23 | * You may elect to license modified versions of this file under the
|
---|
24 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
25 | */
|
---|
26 |
|
---|
27 | #ifndef IPRT_INCLUDED_INTERNAL_rand_h
|
---|
28 | #define IPRT_INCLUDED_INTERNAL_rand_h
|
---|
29 | #ifndef RT_WITHOUT_PRAGMA_ONCE
|
---|
30 | # pragma once
|
---|
31 | #endif
|
---|
32 |
|
---|
33 | #include <iprt/types.h>
|
---|
34 | #include <iprt/critsect.h>
|
---|
35 |
|
---|
36 | /** Pointer to a random number generator instance. */
|
---|
37 | typedef struct RTRANDINT *PRTRANDINT;
|
---|
38 |
|
---|
39 | /**
|
---|
40 | * Random number generator instance.
|
---|
41 | *
|
---|
42 | * @remarks Not sure if it makes sense to have three random getters...
|
---|
43 | */
|
---|
44 | typedef struct RTRANDINT
|
---|
45 | {
|
---|
46 | /** Magic value (RTRANDINT_MAGIC). */
|
---|
47 | uint32_t u32Magic;
|
---|
48 | #if 0 /** @todo later. */
|
---|
49 | /** Fast mutex semaphore that serializes the access, this is optional. */
|
---|
50 | PRTCRITSECT pCritSect;
|
---|
51 | #endif
|
---|
52 |
|
---|
53 | /**
|
---|
54 | * Generates random bytes.
|
---|
55 | *
|
---|
56 | * @param pThis Pointer to the instance data.
|
---|
57 | * @param pb Where to store the bytes.
|
---|
58 | * @param cb The number of bytes to produce.
|
---|
59 | */
|
---|
60 | DECLCALLBACKMEMBER(void , pfnGetBytes,(PRTRANDINT pThis, uint8_t *pb, size_t cb));
|
---|
61 |
|
---|
62 | /**
|
---|
63 | * Generates a unsigned 32-bit random number.
|
---|
64 | *
|
---|
65 | * @returns The random number.
|
---|
66 | * @param pThis Pointer to the instance data.
|
---|
67 | * @param u32First The first number in the range.
|
---|
68 | * @param u32Last The last number in the range (i.e. inclusive).
|
---|
69 | */
|
---|
70 | DECLCALLBACKMEMBER(uint32_t, pfnGetU32,(PRTRANDINT pThis, uint32_t u32First, uint32_t u32Last));
|
---|
71 |
|
---|
72 | /**
|
---|
73 | * Generates a unsigned 64-bit random number.
|
---|
74 | *
|
---|
75 | * @returns The random number.
|
---|
76 | * @param pThis Pointer to the instance data.
|
---|
77 | * @param u64First The first number in the range.
|
---|
78 | * @param u64Last The last number in the range (i.e. inclusive).
|
---|
79 | */
|
---|
80 | DECLCALLBACKMEMBER(uint64_t, pfnGetU64,(PRTRANDINT pThis, uint64_t u64First, uint64_t u64Last));
|
---|
81 |
|
---|
82 | /**
|
---|
83 | * Generic seeding.
|
---|
84 | *
|
---|
85 | * @returns IPRT status code.
|
---|
86 | * @retval VERR_NOT_SUPPORTED if it isn't a pseudo generator.
|
---|
87 | *
|
---|
88 | * @param pThis Pointer to the instance data.
|
---|
89 | * @param u64Seed The seed.
|
---|
90 | */
|
---|
91 | DECLCALLBACKMEMBER(int, pfnSeed,(PRTRANDINT pThis, uint64_t u64Seed));
|
---|
92 |
|
---|
93 | /**
|
---|
94 | * Save the current state of a pseudo generator.
|
---|
95 | *
|
---|
96 | * This can be use to save the state so it can later be resumed at the same
|
---|
97 | * position.
|
---|
98 | *
|
---|
99 | * @returns IPRT status code.
|
---|
100 | * @retval VINF_SUCCESS on success. *pcbState contains the length of the
|
---|
101 | * returned string and pszState contains the state string.
|
---|
102 | * @retval VERR_BUFFER_OVERFLOW if the supplied buffer is too small. *pcbState
|
---|
103 | * will contain the necessary buffer size.
|
---|
104 | * @retval VERR_NOT_SUPPORTED by non-psuedo generators.
|
---|
105 | *
|
---|
106 | * @param pThis Pointer to the instance data.
|
---|
107 | * @param pszState Where to store the state. The returned string will be
|
---|
108 | * null terminated and printable.
|
---|
109 | * @param pcbState The size of the buffer pszState points to on input, the
|
---|
110 | * size required / used on return (including the
|
---|
111 | * terminator, thus the 'cb' instead of 'cch').
|
---|
112 | */
|
---|
113 | DECLCALLBACKMEMBER(int, pfnSaveState,(PRTRANDINT pThis, char *pszState, size_t *pcbState));
|
---|
114 |
|
---|
115 | /**
|
---|
116 | * Restores the state of a pseudo generator.
|
---|
117 | *
|
---|
118 | * The state must have been obtained using pfnGetState.
|
---|
119 | *
|
---|
120 | * @returns IPRT status code.
|
---|
121 | * @retval VERR_PARSE_ERROR if the state string is malformed.
|
---|
122 | * @retval VERR_NOT_SUPPORTED by non-psuedo generators.
|
---|
123 | *
|
---|
124 | * @param pThis Pointer to the instance data.
|
---|
125 | * @param pszState The state to load.
|
---|
126 | */
|
---|
127 | DECLCALLBACKMEMBER(int, pfnRestoreState,(PRTRANDINT pThis, char const *pszState));
|
---|
128 |
|
---|
129 | /**
|
---|
130 | * Destroys the instance.
|
---|
131 | *
|
---|
132 | * The callee is responsible for freeing all resources, including
|
---|
133 | * the instance data.
|
---|
134 | *
|
---|
135 | * @returns IPRT status code. State undefined on failure.
|
---|
136 | * @param pThis Pointer to the instance data.
|
---|
137 | */
|
---|
138 | DECLCALLBACKMEMBER(int, pfnDestroy,(PRTRANDINT pThis));
|
---|
139 |
|
---|
140 | /** Union containing the specific state info for each generator. */
|
---|
141 | union
|
---|
142 | {
|
---|
143 | struct RTRandParkMiller
|
---|
144 | {
|
---|
145 | /** The context. */
|
---|
146 | uint32_t u32Ctx;
|
---|
147 | /** The number of single bits used to fill in the 31st bit. */
|
---|
148 | uint32_t u32Bits;
|
---|
149 | /** The number bits in u32Bits. */
|
---|
150 | uint32_t cBits;
|
---|
151 | } ParkMiller;
|
---|
152 |
|
---|
153 | struct RTRandFile
|
---|
154 | {
|
---|
155 | /** The file handle (native). */
|
---|
156 | intptr_t hFile;
|
---|
157 | } File;
|
---|
158 | } u;
|
---|
159 | } RTRANDINT;
|
---|
160 |
|
---|
161 |
|
---|
162 | RT_C_DECLS_BEGIN
|
---|
163 |
|
---|
164 | DECL_HIDDEN_CALLBACK(void) rtRandAdvSynthesizeBytesFromU32(PRTRANDINT pThis, uint8_t *pb, size_t cb);
|
---|
165 | DECL_HIDDEN_CALLBACK(void) rtRandAdvSynthesizeBytesFromU64(PRTRANDINT pThis, uint8_t *pb, size_t cb);
|
---|
166 | DECL_HIDDEN_CALLBACK(uint32_t) rtRandAdvSynthesizeU32FromBytes(PRTRANDINT pThis, uint32_t u32First, uint32_t u32Last);
|
---|
167 | DECL_HIDDEN_CALLBACK(uint32_t) rtRandAdvSynthesizeU32FromU64(PRTRANDINT pThis, uint32_t u32First, uint32_t u32Last);
|
---|
168 | DECL_HIDDEN_CALLBACK(uint64_t) rtRandAdvSynthesizeU64FromBytes(PRTRANDINT pThis, uint64_t u64First, uint64_t u64Last);
|
---|
169 | DECL_HIDDEN_CALLBACK(uint64_t) rtRandAdvSynthesizeU64FromU32(PRTRANDINT pThis, uint64_t u64First, uint64_t u64Last);
|
---|
170 | DECL_HIDDEN_CALLBACK(int) rtRandAdvStubSeed(PRTRANDINT pThis, uint64_t u64Seed);
|
---|
171 | DECL_HIDDEN_CALLBACK(int) rtRandAdvStubSaveState(PRTRANDINT pThis, char *pszState, size_t *pcbState);
|
---|
172 | DECL_HIDDEN_CALLBACK(int) rtRandAdvStubRestoreState(PRTRANDINT pThis, char const *pszState);
|
---|
173 | DECL_HIDDEN_CALLBACK(int) rtRandAdvDefaultDestroy(PRTRANDINT pThis);
|
---|
174 |
|
---|
175 | RT_C_DECLS_END
|
---|
176 |
|
---|
177 | #endif /* !IPRT_INCLUDED_INTERNAL_rand_h */
|
---|
178 |
|
---|