VirtualBox

source: vbox/trunk/src/VBox/Runtime/include/internal/rand.h@ 95512

Last change on this file since 95512 was 93115, checked in by vboxsync, 3 years ago

scm --update-copyright-year

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id Revision
File size: 6.6 KB
Line 
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. */
37typedef 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 */
44typedef 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
162RT_C_DECLS_BEGIN
163
164DECL_HIDDEN_CALLBACK(void) rtRandAdvSynthesizeBytesFromU32(PRTRANDINT pThis, uint8_t *pb, size_t cb);
165DECL_HIDDEN_CALLBACK(void) rtRandAdvSynthesizeBytesFromU64(PRTRANDINT pThis, uint8_t *pb, size_t cb);
166DECL_HIDDEN_CALLBACK(uint32_t) rtRandAdvSynthesizeU32FromBytes(PRTRANDINT pThis, uint32_t u32First, uint32_t u32Last);
167DECL_HIDDEN_CALLBACK(uint32_t) rtRandAdvSynthesizeU32FromU64(PRTRANDINT pThis, uint32_t u32First, uint32_t u32Last);
168DECL_HIDDEN_CALLBACK(uint64_t) rtRandAdvSynthesizeU64FromBytes(PRTRANDINT pThis, uint64_t u64First, uint64_t u64Last);
169DECL_HIDDEN_CALLBACK(uint64_t) rtRandAdvSynthesizeU64FromU32(PRTRANDINT pThis, uint64_t u64First, uint64_t u64Last);
170DECL_HIDDEN_CALLBACK(int) rtRandAdvStubSeed(PRTRANDINT pThis, uint64_t u64Seed);
171DECL_HIDDEN_CALLBACK(int) rtRandAdvStubSaveState(PRTRANDINT pThis, char *pszState, size_t *pcbState);
172DECL_HIDDEN_CALLBACK(int) rtRandAdvStubRestoreState(PRTRANDINT pThis, char const *pszState);
173DECL_HIDDEN_CALLBACK(int) rtRandAdvDefaultDestroy(PRTRANDINT pThis);
174
175RT_C_DECLS_END
176
177#endif /* !IPRT_INCLUDED_INTERNAL_rand_h */
178
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette