乱数生成

PRNG(疑似乱数生成器)を用いてランダムなバイト列を生成する機能です。 PRNGはエントロピー源を用いて定期的に再シードされます。

API

乱数生成機能のAPIを使用するには、solid_rng.h をインクルードしてください。

#include "solid_rng.h"

SOLID_RNG_SampleRandomBytes

int SOLID_RNG_SampleRandomBytes(uint8_t *outBytes, size_t length)

PRNG(疑似乱数生成器)を使用して、ランダムなバイト列を生成します。

PRNGは登録されたエントロピー源(IMPL_RNG_GetEntropy)を使用して定期的に 再シードされます。IMPL_RNG_SampleRandomBytes が実装されている場合、処理は そちらに委譲されます。

注釈

実装によっては、割り込みコンテキストやブロッキングシステムコールを発行できない システム状態をサポートせず、SOLID_ERR_NOTSUPPORTED を返す場合があります。 可能な限り、そうした状況では呼び出さないことを推奨します。

パラメータ:

  • outBytes -- 生成したバイト列の格納先

  • length -- 生成するバイト数

戻り値:

SOLID_RNG_RequestReseed

int SOLID_RNG_RequestReseed(void)

PRNGの再シードを要求します。

戻り値:

要実装関数

乱数生成機能の要実装関数の定義は、impl_rng.h にあります。

#include "impl_rng.h"

ハードウェア乱数生成器を使用する場合は IMPL_RNG_SampleRandomBytes を実装して 処理をオーバライドできます。実装しない場合は、エントロピー源 (IMPL_RNG_GetEntropy)と排他処理用の関数を用いたデフォルトのPRNG実装が使用されます。

IMPL_RNG_SampleRandomBytes

int IMPL_RNG_SampleRandomBytes(uint8_t *outBytes, size_t length)

(任意実装) 定義されている場合、SOLID_RNG_SampleRandomBytes の実装を オーバライドします。

ハードウェア乱数生成器などを使って独自の乱数生成を行いたい場合に実装します。 実装されていない場合は、下記の要実装関数を用いたデフォルトのPRNG実装が使用されます。

パラメータ:

  • outBytes -- 生成したバイト列の格納先

  • length -- 生成するバイト数

戻り値:

IMPL_RNG_InitializeCriticalSection

void IMPL_RNG_InitializeCriticalSection(void)

デフォルトのPRNG実装(IMPL_RNG_SampleRandomBytes 未実装時に使用)の 排他処理に使用するロックを初期化します。

IMPL_RNG_EnterCriticalSection

int IMPL_RNG_EnterCriticalSection(void)

デフォルトのPRNG実装の排他ロックを取得します。

RTOSカーネル上でブロッキングシステムコールを発行可能な場合(例: ITRONカーネルの カーネル動作状態・タスクコンテキスト・ディスパッチ許可状態)、この関数は 呼び出し元タスクをブロックする可能性があります。 ロックを所有しているスレッドが再度取得しようとした場合の動作は未定義です。

戻り値:

IMPL_RNG_LeaveCriticalSection

void IMPL_RNG_LeaveCriticalSection(void)

デフォルトのPRNG実装の排他ロックを解放します。

呼び出し元スレッドはロックを所有している必要があります(ロック元と異なるタスクで 解放した場合の動作は未定義)。ロックを所有したままスレッドが終了した場合の動作も 未定義です。

IMPL_RNG_GetEntropy

int IMPL_RNG_GetEntropy(uint8_t *outBytes, size_t length)

デフォルトのPRNG実装が疑似乱数生成のエントロピー源として使用する関数です。

この関数を呼び出すには、呼び出し元スレッドが IMPL_RNG_EnterCriticalSection で得られるロックを所有している必要があります。ブロッキングシステムコールを発行 可能な場合、呼び出し元タスクをブロックする可能性があります。

パラメータ:

  • outBytes -- エントロピー(バイト列)の格納先

  • length -- 取得するバイト数

戻り値: