CryptoSys PKI Pro Manual

RNG_Initialize

Initializes the RNG generator with a seed file.

VBA/VB6 Syntax

Public Declare Function RNG_Initialize Lib "diCrPKI.dll" (ByVal strSeedFile As String, ByVal nOptions As Long) As Long

nRet = RNG_Initialize(strSeedFile, nOptions)

C/C++ Syntax

long __stdcall RNG_Initialize(const char *szSeedFile, long nOptions);

Parameters

szSeedFile
[in] specifying a seed file. May be the empty string "".
nOptions
[in] option flags:
PKI_DEFAULT (0) for default options
PKI_RNG_NO_INTEL_DRNG to turn off support for Intel(R) DRNG for the current session.

Returns (VBA/C)

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).

VBA Wrapper Syntax

Public Function rngInitialize (szSeedFile As String) As Long
Public Function rngInitializeEx (Optional nOptions As Long = 0) As Long

.NET Equivalent

Rng.Initialize Method
Rng.InitializeEx Method

C++ (STL) Equivalent

static int dipki::Rng::Initialize (const std::string &seedFile)
static int dipki::Rng::InitializeEx (Opts opts=Opts::Default)

Python Equivalent

static Rng.initialize(seedfilename)
static Rng.initialize_ex(opts=0)

Remarks

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.

Examples

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)

See Also

RNG_MakeSeedFile RNG_UpdateSeedFile

[Contents] [Index]

[PREV: RNG_Guid...]   [Contents]   [Index]   
   [NEXT: RNG_MakeSeedFile...]

Copyright © 2004-24 D.I. Management Services Pty Ltd. All rights reserved. Generated 2024-01-01T11:51:59Z.