Initializes the RNG generator with a seed file.
Public Declare Function RNG_Initialize Lib "diCrPKI.dll" (ByVal strSeedFile As String, ByVal nOptions As Long) As Long
nRet = RNG_Initialize(strSeedFile, nOptions)
long __stdcall RNG_Initialize(const char *szSeedFile, long nOptions);
"".
If successful, the return value is zero; otherwise it returns a nonzero error code.
If "" is passed for szSeedFile, it returns the support status for Intel DRNG (see Remarks).
Public Function rngInitialize (szSeedFile As String) As Long
Public Function rngInitializeEx (Optional nOptions As Long = 0) As Long
Rng.Initialize Method
Rng.InitializeEx Method
static int dipki::Rng::Initialize (const std::string &seedFile)
static int dipki::Rng::InitializeEx (Opts opts=Opts::Default)
static Rng.initialize_ex(opts=0)
static Rng.initialize(seedfilename)
static Rng.initialize_ex(opts=0)
A seed file maintains the entropy state between sessions. If the seed file does not exist, it will be created, using any existing entropy. The file must be writable by the user. File locking is used to prevent interference from simultaneous use by others. The seed file is automatically updated by this procedure. Any existing file will be overwritten without warning.
Intel(R) DRNG support: [New in v22.1] Pass an empty string "" for szSeedFile to query support for
Intel(R) Digital Random Number Generator (DRNG) on your system (and add an extra 256 bits of entropy, if available).
If supported, the return value is a positive integer (1,2,3),
otherwise it returns the error code PRNG_ERR_NOTAVAIL (-214).
See Intel(R) DRNG.
Alternatively, use the option PKI_RNG_NO_INTEL_DRNG to turn off support for Intel(R) DRNG for the current session. You might use this if calls to Intel(R) DRNG are causing problems on your system.
This example shows how to initialize the RNG with a seed file, generate some random data, and then update the seed file.
Dim strSeedFile As String Dim nRet As Long Dim abData() As Byte Dim nDataLen As Long Dim i As Integer strSeedFile = "seed.dat" ' 1. Initialize nRet = RNG_Initialize(strSeedFile, 0) Debug.Print "RNG_Initialize('" & strSeedFile & "') returns " & nRet & " (expecting 0)" ' 2. Generate some random data nDataLen = 24 ReDim abData(nDataLen - 1) For i = 1 To 3 Call RNG_Bytes(abData(0), nDataLen, "", 0) Debug.Print cnvHexStrFromBytes(abData) Next ' 3. Update the seed file nRet = RNG_UpdateSeedFile(strSeedFile, 0) Debug.Print "RNG_UpdateSeedFile('" & strSeedFile & "') returns " & nRet & " (expecting 0)"
RNG_Initialize('seed.dat') returns 0 (expecting 0)
79654D8DA3D30468B95B820E3C5615838A765CA666C68A9D
EB2DA20FC86CC797BCB3D26C9E663736E616EF99DEB56C21
5A3DB035BD374E57649AEE367A7E0156A3045AE0111D47EC
RNG_UpdateSeedFile('seed.dat') returns 0 (expecting 0)
This example demonstrates support for Intel(R) DRNG
Dim n As Long n = RNG_Initialize("", 0) ' Query support for Intel(R) DRNG Debug.Print "RNG_Initialize() returns " & n & " (If > 0 Intel(R) DRNG support available)" ' Explicitly turn off support... n = RNG_Initialize("", PKI_RNG_NO_INTEL_DRNG) ' Turns off Intel(R) DRNG support Debug.Print "RNG_Initialize(PKI_RNG_NO_INTEL_DRNG) returns " & n & " (expected -ve)" n = RNG_Initialize("", 0) ' Now query again Debug.Print "RNG_Initialize() returns " & n & " (expected -ve)"
RNG_Initialize() returns 3 (If > 0 Intel(R) DRNG support available) RNG_Initialize(PKI_RNG_NO_INTEL_DRNG) returns -214 (expected -ve) RNG_Initialize() returns -214 (expected -ve)
In practice, you should test for Intel(R) DRNG support before calling any RNG function. If supported, then the generator will have been seeded with sufficient entropy. If not supported, then use a seed file.
Dim n As Long n = rngInitializeEx() If n <= 0 Then ' Use a seed file n = rngInitialize("seed.dat") End If ' Do work... Dim abKey() As Byte abKey = rngBytes(32) Debug.Print cnvToHex(abKey) ' ...etc ' At end of session, update the seed file n = RNG_UpdateSeedFile("seed.dat", 0)
RNG_MakeSeedFile RNG_UpdateSeedFile