mirror of
https://github.com/wolfSSL/wolfssl.git
synced 2026-08-04 00:34:09 +02:00
Merge pull request #11024 from yosuke-wolfssl/feat/JPdoc
[JA] Add missing Japanese dox_comments for 7 API groups
This commit is contained in:
JacobBarthelmeh
GitHub
@@ -15,6 +15,64 @@
|
||||
\defgroup ECC アルゴリズム - ECC
|
||||
\defgroup ED25519 アルゴリズム - ED25519
|
||||
\defgroup ED448 アルゴリズム - ED448
|
||||
\defgroup ML_DSA アルゴリズム - ML-DSA (FIPS 204)
|
||||
ML-DSA(Module-Lattice-based Digital Signature Algorithm)は、NISTが
|
||||
FIPS 204として標準化した耐量子のデジタル署名方式です。標準化前の名称は
|
||||
Dilithiumであり、移行前のコードのために従来のDilithiumの型名および
|
||||
マクロ名がエイリアスとして残されています(<wolfssl/wolfcrypt/dilithium.h>
|
||||
を参照)。
|
||||
|
||||
ML-DSAは、NISTセキュリティカテゴリで識別される3つのパラメータセットを
|
||||
定義しています。ML-DSA-44(レベル2)、ML-DSA-65(レベル3)、ML-DSA-87
|
||||
(レベル5)です。3つはいずれも同一のwc_MlDsaKeyオブジェクトでサポートされ、
|
||||
パラメータセットはwc_MlDsaKey_SetParams()で選択します。
|
||||
|
||||
\defgroup ML_KEM アルゴリズム - ML-KEM (FIPS 203)
|
||||
ML-KEM(Module-Lattice-based Key Encapsulation Mechanism)は、NISTが
|
||||
FIPS 203として標準化した耐量子の鍵カプセル化メカニズムです。標準化前の
|
||||
名称はKyberであり、移行前のコードのために従来のKyberの型名および
|
||||
マクロ名がエイリアスとして残されています。
|
||||
|
||||
ML-KEMは3つのパラメータセットを定義しています。ML-KEM-512(NISTレベル1)、
|
||||
ML-KEM-768(レベル3)、ML-KEM-1024(レベル5)です。バリアントは
|
||||
wc_MlKemKey_Init()またはwc_MlKemKey_New()で鍵を初期化する際に選択します。
|
||||
|
||||
\defgroup SLH_DSA アルゴリズム - SLH-DSA (FIPS 205)
|
||||
SLH-DSA(Stateless Hash-based Digital Signature Algorithm)は、NISTが
|
||||
FIPS 205として標準化した耐量子の署名方式です。SPHINCS+の提案方式を
|
||||
継承しており、状態を持ちません。署名によって秘密鍵が変化しないため、
|
||||
アプリケーションが鍵の状態を同期する負担はありません。
|
||||
|
||||
ハッシュファミリ(SHAKEまたはSHA2)、セキュリティカテゴリ(128/192/256)、
|
||||
速度とサイズのトレードオフ(s = 署名が小さい、f = 署名が高速)の組み合わせ
|
||||
により、12個のパラメータセットがサポートされています。パラメータセットは
|
||||
wc_SlhDsaKey_Init()で鍵を初期化する際に選択します。
|
||||
|
||||
\defgroup LMS アルゴリズム - LMS / HSS (RFC 8554)
|
||||
LMS(Leighton-Micali Signatures)とそのマルチツリー構成であるHSS
|
||||
(Hierarchical Signature System)は、RFC 8554およびNIST SP 800-208で
|
||||
規定された、状態を持つハッシュベースの署名方式です。署名ごとに秘密鍵の
|
||||
ワンタイムコンポーネントが消費されるため、アプリケーションは署名を行う
|
||||
たびに、次の署名までの間に秘密鍵の状態を(wc_LmsKey_SetReadCb()および
|
||||
wc_LmsKey_SetWriteCb()で登録した読み込み/書き込みコールバックを介して)
|
||||
永続化しなければなりません。ワンタイム鍵を再利用すると、この方式の
|
||||
安全性は完全に失われます。
|
||||
|
||||
1つの鍵から利用できる署名の回数はパラメータセットによって上限が定まります。
|
||||
残りの回数はwc_LmsKey_SigsLeft()で問い合わせてください。
|
||||
|
||||
\defgroup XMSS アルゴリズム - XMSS / XMSS^MT (RFC 8391)
|
||||
XMSS(eXtended Merkle Signature Scheme)とそのマルチツリー版である
|
||||
XMSS^MTは、RFC 8391およびNIST SP 800-208で規定された、状態を持つ
|
||||
ハッシュベースの署名方式です。LMSと同様に、署名ごとに秘密鍵のワンタイム
|
||||
コンポーネントが消費されるため、アプリケーションは署名を行うたびに、次の
|
||||
署名までの間にwc_XmssKey_SetReadCb()およびwc_XmssKey_SetWriteCb()で
|
||||
登録したコールバックを介して秘密鍵の状態を永続化しなければなりません。
|
||||
ワンタイム鍵を再利用すると、この方式の安全性は完全に失われます。
|
||||
|
||||
1つの鍵から利用できる署名の回数はパラメータセットによって上限が定まります。
|
||||
残りの回数はwc_XmssKey_SigsLeft()で問い合わせてください。
|
||||
|
||||
\defgroup ECCSI_Overview ECCSIの概要
|
||||
ECCSI(楕円曲線ベースの証明書レス署名によるアイデンティティベース暗号化)は、RFC 6507(https://tools.ietf.org/html/rfc6507)で規定されています。
|
||||
|
||||
@@ -202,9 +260,11 @@
|
||||
\defgroup PKCS11 アルゴリズム - PKCS11
|
||||
\defgroup Password アルゴリズム - パスワードベース
|
||||
\defgroup Poly1305 アルゴリズム - Poly1305
|
||||
\defgroup PUF アルゴリズム - PUF
|
||||
\defgroup RIPEMD アルゴリズム - RIPEMD
|
||||
\defgroup RSA アルゴリズム - RSA
|
||||
\defgroup SHA アルゴリズム - SHA 128/224/256/384/512
|
||||
\defgroup SHE アルゴリズム - SHE
|
||||
\defgroup SipHash アルゴリズム - SipHash
|
||||
\defgroup SrtpKdf アルゴリズム - SRTP KDF
|
||||
\defgroup SRP アルゴリズム - SRP
|
||||
|
||||
@@ -0,0 +1,198 @@
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
完全なベアメタルの実装例(NUCLEO-H563ZIで動作確認済み)については、
|
||||
https://github.com/wolfSSL/wolfssl-examples/tree/master/puf を参照してください。
|
||||
*/
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief wc_PufCtx構造体を初期化し、すべてのフィールドをゼロクリアします。他のPUF操作を行う前に呼び出さなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxがNULLの場合に返されます
|
||||
|
||||
\param ctx 初期化するwc_PufCtx構造体へのポインタ
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_PufCtx ctx;
|
||||
ret = wc_PufInit(&ctx);
|
||||
\endcode
|
||||
|
||||
\sa wc_PufReadSram
|
||||
\sa wc_PufEnroll
|
||||
\sa wc_PufZeroize
|
||||
*/
|
||||
int wc_PufInit(wc_PufCtx* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief 生のSRAMデータをPUFコンテキストに読み込みます。電源投入時の状態を保持するため、sramAddrはNOLOADリンカセクションを指している必要があります。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxまたはsramAddrがNULLの場合に返されます
|
||||
\return PUF_READ_E sramSzがWC_PUF_RAW_BYTES未満の場合に返されます
|
||||
|
||||
\param ctx wc_PufCtx構造体へのポインタ
|
||||
\param sramAddr 生のSRAMメモリ領域へのポインタ
|
||||
\param sramSz SRAMバッファのサイズ(WC_PUF_RAW_BYTES以上でなければなりません)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
__attribute__((section(".puf_sram")))
|
||||
static volatile uint8_t puf_sram[256];
|
||||
wc_PufReadSram(&ctx, (const byte*)puf_sram, sizeof(puf_sram));
|
||||
\endcode
|
||||
|
||||
\sa wc_PufInit
|
||||
\sa wc_PufEnroll
|
||||
\sa wc_PufReconstruct
|
||||
*/
|
||||
int wc_PufReadSram(wc_PufCtx* ctx, const byte* sramAddr, word32 sramSz);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief PUFのエンロールメント(登録)を実行します。BCH(127,64,t=10)を用いて生のSRAMを符号化し、公開ヘルパーデータを生成します。エンロールメント後、コンテキストは鍵導出とアイデンティティ取得に使用できる状態になります。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxがNULLの場合に返されます
|
||||
\return PUF_ENROLL_E エンロールメントが失敗した場合に返されます
|
||||
|
||||
\param ctx wc_PufCtxへのポインタ(SRAMデータが読み込まれていなければなりません)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_PufEnroll(&ctx);
|
||||
XMEMCPY(helperData, ctx.helperData, WC_PUF_HELPER_BYTES);
|
||||
\endcode
|
||||
|
||||
\sa wc_PufReadSram
|
||||
\sa wc_PufReconstruct
|
||||
\sa wc_PufDeriveKey
|
||||
*/
|
||||
int wc_PufEnroll(wc_PufCtx* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief 保存されたヘルパーデータを用いて、ノイズを含むSRAMから安定したPUFビットを再構成します。BCH誤り訂正(t=10)により、127ビットの符号語あたり最大10ビットの反転を訂正できます。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxまたはhelperDataがNULLの場合に返されます
|
||||
\return PUF_RECONSTRUCT_E 失敗した場合に返されます(ビット誤りが多すぎる、またはhelperSzが小さすぎる)
|
||||
|
||||
\param ctx wc_PufCtxへのポインタ(SRAMデータが読み込まれていなければなりません)
|
||||
\param helperData 以前のエンロールメントで得られたヘルパーデータへのポインタ
|
||||
\param helperSz ヘルパーデータのサイズ(WC_PUF_HELPER_BYTES以上)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_PufReconstruct(&ctx, helperData, sizeof(helperData));
|
||||
\endcode
|
||||
|
||||
\sa wc_PufEnroll
|
||||
\sa wc_PufDeriveKey
|
||||
\sa wc_PufGetIdentity
|
||||
*/
|
||||
int wc_PufReconstruct(wc_PufCtx* ctx, const byte* helperData, word32 helperSz);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief HKDFを用いて、PUFの安定ビットから暗号鍵を導出します。デフォルトではSHA-256を、WC_PUF_SHA3が定義されている場合はSHA3-256を使用します。infoパラメータは複数の鍵を導出する際のドメイン分離を提供します。HAVE_HKDFが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxまたはkeyがNULLの場合、あるいはkeySzが0の場合に返されます
|
||||
\return PUF_DERIVE_KEY_E PUFが準備できていない場合、またはHKDFが失敗した場合に返されます
|
||||
|
||||
\param ctx wc_PufCtxへのポインタ(エンロールメント済みまたは再構成済みでなければなりません)
|
||||
\param info ドメイン分離のための任意のコンテキスト情報(NULLでも構いません。NULLの場合、infoSzは0として扱われます)
|
||||
\param infoSz infoのサイズ(バイト単位)
|
||||
\param key 導出した鍵を格納する出力バッファ
|
||||
\param keySz 導出する鍵のサイズ(バイト単位)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte key[32];
|
||||
const byte info[] = "my-app-key";
|
||||
wc_PufDeriveKey(&ctx, info, sizeof(info), key, sizeof(key));
|
||||
\endcode
|
||||
|
||||
\sa wc_PufEnroll
|
||||
\sa wc_PufReconstruct
|
||||
\sa wc_PufGetIdentity
|
||||
*/
|
||||
int wc_PufDeriveKey(wc_PufCtx* ctx, const byte* info, word32 infoSz,
|
||||
byte* key, word32 keySz);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief デバイスのアイデンティティハッシュ(安定ビットのSHA-256またはSHA3-256)を取得します。同一のデバイスであれば、常に同じ値が得られます。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxまたはidがNULLの場合に返されます
|
||||
\return PUF_IDENTITY_E PUFが準備できていない場合、またはidSzがWC_PUF_ID_SZ未満の場合に返されます
|
||||
|
||||
\param ctx wc_PufCtxへのポインタ(エンロールメント済みまたは再構成済みでなければなりません)
|
||||
\param id アイデンティティハッシュを格納する出力バッファ
|
||||
\param idSz idバッファのサイズ(WC_PUF_ID_SZ(32バイト)以上)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte identity[WC_PUF_ID_SZ];
|
||||
wc_PufGetIdentity(&ctx, identity, sizeof(identity));
|
||||
\endcode
|
||||
|
||||
\sa wc_PufEnroll
|
||||
\sa wc_PufReconstruct
|
||||
\sa wc_PufDeriveKey
|
||||
*/
|
||||
int wc_PufGetIdentity(wc_PufCtx* ctx, byte* id, word32 idSz);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief ForceZeroを用いて、PUFコンテキスト内のすべての機密データを安全にゼロクリアします。PUFが不要になった時点で呼び出してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxがNULLの場合に返されます
|
||||
|
||||
\param ctx ゼロクリアするwc_PufCtxへのポインタ
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_PufZeroize(&ctx);
|
||||
\endcode
|
||||
|
||||
\sa wc_PufInit
|
||||
*/
|
||||
int wc_PufZeroize(wc_PufCtx* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup PUF
|
||||
|
||||
\brief ハードウェアなしでテストを行うために、合成したSRAMテストデータを注入します。WOLFSSL_PUF_TESTが定義されている場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG ctxまたはdataがNULLの場合に返されます
|
||||
\return PUF_READ_E szがWC_PUF_RAW_BYTES未満の場合に返されます
|
||||
|
||||
\param ctx wc_PufCtxへのポインタ
|
||||
\param data 合成SRAMデータへのポインタ
|
||||
\param sz dataのサイズ(WC_PUF_RAW_BYTES(256バイト)以上)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte testSram[WC_PUF_RAW_BYTES];
|
||||
wc_PufSetTestData(&ctx, testSram, sizeof(testSram));
|
||||
\endcode
|
||||
|
||||
\sa wc_PufInit
|
||||
\sa wc_PufReadSram
|
||||
*/
|
||||
int wc_PufSetTestData(wc_PufCtx* ctx, const byte* data, word32 sz);
|
||||
@@ -0,0 +1,532 @@
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LmsKeyオブジェクトを初期化します。他のLMS/HSS操作を行う前に呼び出さなければなりません。使用が終わったらwc_LmsKey_Free()でリソースを解放してください。
|
||||
|
||||
LMS(Leighton-Micali Signatures)とマルチツリー構成であるHSS(RFC 8554、NIST SP 800-208)は、状態を持つ(STATEFUL)ハッシュベースの署名方式です。wc_LmsKey_Sign()を呼び出すたびに秘密鍵のワンタイムコンポーネントが消費され、ワンタイム鍵を再利用するとこの方式の安全性は完全に失われます。アプリケーションは、署名を行うたびに、次の署名までの間に秘密鍵の状態を永続化しなければなりません。wc_LmsKey_SetWriteCb()およびwc_LmsKey_SetReadCb()を参照してください。
|
||||
|
||||
初期化後、鍵はWC_LMS_STATE_INITED状態になります。鍵を生成または再読み込みする前に、wc_LmsKey_SetLmsParm()またはwc_LmsKey_SetParameters()でパラメータを設定しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するLmsKeyへのポインタ。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
LmsKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_LmsKey_Init(&key, NULL, INVALID_DEVID);
|
||||
if (ret != 0) {
|
||||
// 鍵の初期化エラー
|
||||
}
|
||||
wc_LmsKey_SetLmsParm(&key, WC_LMS_PARM_L2_H10_W8);
|
||||
// ... 鍵を使用 ...
|
||||
wc_LmsKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_LmsKey_Free
|
||||
\sa wc_LmsKey_SetLmsParm
|
||||
\sa wc_LmsKey_SetParameters
|
||||
\sa wc_LmsKey_MakeKey
|
||||
*/
|
||||
int wc_LmsKey_Init(LmsKey* key, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief デバイス側の鍵識別子を指定してLmsKeyを初期化します。wc_LmsKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるバイナリ形式のidも保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
idは鍵オブジェクトへコピーされます。呼び出し側はこの関数から戻った直後に自身のバッファを解放して構いません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはlenが0より大きいにもかかわらずidがNULLの場合に返されます。
|
||||
\return BUFFER_E lenが負の場合、またはLMS_MAX_ID_LENより大きい場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するLmsKeyへのポインタ。
|
||||
\param [in] id デバイス側の鍵識別子バイト列へのポインタ。lenが0の場合はNULLでも構いません。
|
||||
\param [in] len idのバイト数。[0, LMS_MAX_ID_LEN]の範囲内でなければなりません。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_LmsKey_Init
|
||||
\sa wc_LmsKey_InitLabel
|
||||
\sa wc_LmsKey_Free
|
||||
*/
|
||||
int wc_LmsKey_InitId(LmsKey* key, const unsigned char* id, int len,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief デバイス側の鍵ラベルを指定してLmsKeyを初期化します。wc_LmsKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるラベル文字列も保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlabelがNULLの場合に返されます。
|
||||
\return BUFFER_E labelが空の場合、またはLMS_MAX_LABEL_LENより長い場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するLmsKeyへのポインタ。
|
||||
\param [in] label NUL終端されたデバイス側の鍵ラベル。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_LmsKey_Init
|
||||
\sa wc_LmsKey_InitId
|
||||
*/
|
||||
int wc_LmsKey_InitLabel(LmsKey* key, const char* label, void* heap,
|
||||
int devId);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 定義済みのLMS/HSSパラメータセットを名前で選択します。列挙型wc_LmsParmは、ツリーの深さ(レベル数)、ツリーごとの高さ、Winternitzパラメータ、ハッシュファミリを1つの値にまとめています。特定のビルドで利用できる名前の一覧については、wc_LmsParmの定義を参照してください。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはlmsParmが認識できない場合、あるいはコンパイルに含まれていないパラメータセットを指している場合に返されます。
|
||||
\return BAD_STATE_E keyがWC_LMS_STATE_INITED状態でない場合に返されます。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_INITED状態のLmsKeyへのポインタ。
|
||||
\param [in] lmsParm wc_LmsParm定数(例: WC_LMS_PARM_L2_H10_W8)。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
LmsKey key;
|
||||
|
||||
wc_LmsKey_Init(&key, NULL, INVALID_DEVID);
|
||||
wc_LmsKey_SetLmsParm(&key, WC_LMS_PARM_L2_H10_W8);
|
||||
\endcode
|
||||
|
||||
\sa wc_LmsKey_SetParameters
|
||||
\sa wc_LmsKey_GetParameters
|
||||
\sa wc_LmsKey_ParmToStr
|
||||
*/
|
||||
int wc_LmsKey_SetLmsParm(LmsKey* key, enum wc_LmsParm lmsParm);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LMS/HSSのパラメータを個別に設定します。デフォルトのSHA-256/256ハッシュが使用されます。ハッシュファミリをより細かく制御する場合はwc_LmsKey_SetParameters_ex()を使用してください。
|
||||
|
||||
パラメータの組み合わせは、RFC 8554で許可されているセットのいずれかと一致しなければなりません。
|
||||
- levels: 1..8
|
||||
- height: 5、10、15、20(ビルドによっては25も)
|
||||
- winternitz: 1、2、4、8のいずれか
|
||||
|
||||
1つの鍵から利用できる署名の最大数は2^(levels * height)です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、または要求されたパラメータの組み合わせがこのビルドでサポートされていない場合に返されます。
|
||||
\return BAD_STATE_E keyがWC_LMS_STATE_INITED状態でない場合に返されます。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_INITED状態のLmsKeyへのポインタ。
|
||||
\param [in] levels HSSチェーンにおけるマークルツリーのレベル数。
|
||||
\param [in] height 個々のマークルツリーの高さ。
|
||||
\param [in] winternitz Winternitzパラメータ(1、2、4、8のいずれか)。
|
||||
|
||||
\sa wc_LmsKey_SetParameters_ex
|
||||
\sa wc_LmsKey_SetLmsParm
|
||||
\sa wc_LmsKey_GetParameters
|
||||
*/
|
||||
int wc_LmsKey_SetParameters(LmsKey* key, int levels, int height,
|
||||
int winternitz);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief ハッシュファミリのセレクタを明示的に指定して、LMS/HSSのパラメータを個別に設定します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、または要求されたパラメータの組み合わせがこのビルドでサポートされていない場合に返されます。
|
||||
\return BAD_STATE_E keyがWC_LMS_STATE_INITED状態でない場合に返されます。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_INITED状態のLmsKeyへのポインタ。
|
||||
\param [in] levels マークルツリーのレベル数。
|
||||
\param [in] height 各ツリーの高さ。
|
||||
\param [in] winternitz Winternitzパラメータ(1、2、4、8のいずれか)。
|
||||
\param [in] hash ビルドがサポートする範囲で、SHA-256/256、SHA-256/192、SHAKE256/256、SHAKE256/192を指定するハッシュファミリのセレクタ。
|
||||
|
||||
\sa wc_LmsKey_SetParameters
|
||||
\sa wc_LmsKey_GetParameters_ex
|
||||
*/
|
||||
int wc_LmsKey_SetParameters_ex(LmsKey* key, int levels, int height,
|
||||
int winternitz, int hash);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵に以前設定されたLMS/HSSのパラメータを取得します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG いずれかのポインタがNULLの場合、またはパラメータが設定されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたLmsKeyへのポインタ。
|
||||
\param [out] levels ツリーのレベル数を受け取ります。
|
||||
\param [out] height ツリーごとの高さを受け取ります。
|
||||
\param [out] winternitz Winternitzパラメータを受け取ります。
|
||||
|
||||
\sa wc_LmsKey_SetParameters
|
||||
\sa wc_LmsKey_GetParameters_ex
|
||||
*/
|
||||
int wc_LmsKey_GetParameters(const LmsKey* key, int* levels, int* height,
|
||||
int* winternitz);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵からLMS/HSSのパラメータとハッシュファミリのセレクタを取得します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG いずれかのポインタがNULLの場合、またはパラメータが設定されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたLmsKeyへのポインタ。
|
||||
\param [out] levels ツリーのレベル数を受け取ります。
|
||||
\param [out] height ツリーごとの高さを受け取ります。
|
||||
\param [out] winternitz Winternitzパラメータを受け取ります。
|
||||
\param [out] hash ハッシュファミリのセレクタを受け取ります。
|
||||
|
||||
\sa wc_LmsKey_SetParameters_ex
|
||||
*/
|
||||
int wc_LmsKey_GetParameters_ex(const LmsKey* key, int* levels, int* height,
|
||||
int* winternitz, int* hash);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 更新された秘密鍵の状態を永続化するためにwolfSSLが呼び出すコールバックを登録します。LMS/HSSは状態を持つため、アプリケーションは、署名が成功するたびに、その署名が相手に渡される前に秘密鍵を永続化しなければなりません。そうしなければ、クラッシュや再起動によってワンタイム鍵が再利用され、この方式が破られる可能性があります。
|
||||
|
||||
コールバックはエンコードされた秘密鍵のバイト列を受け取り、wc_LmsRcコードのいずれかを返します。WC_LMS_RC_SAVED_TO_NV_MEMORYは永続的な書き込みが完了したことを示します。それ以外の戻り値は失敗として扱われます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはwrite_cbがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key LmsKeyへのポインタ。
|
||||
\param [in] write_cb 秘密鍵を永続化するために呼び出されるコールバック。
|
||||
|
||||
\sa wc_LmsKey_SetReadCb
|
||||
\sa wc_LmsKey_SetContext
|
||||
\sa wc_LmsKey_Sign
|
||||
*/
|
||||
int wc_LmsKey_SetWriteCb(LmsKey* key, wc_lms_write_private_key_cb write_cb);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 永続化された秘密鍵の状態を読み込むためにwolfSSLが呼び出すコールバックを登録します。保存された鍵をメモリに復元して署名を継続するために、wc_LmsKey_Reload()から使用されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはread_cbがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key LmsKeyへのポインタ。
|
||||
\param [in] read_cb 秘密鍵を読み込むために呼び出されるコールバック。
|
||||
|
||||
\sa wc_LmsKey_SetWriteCb
|
||||
\sa wc_LmsKey_SetContext
|
||||
\sa wc_LmsKey_Reload
|
||||
*/
|
||||
int wc_LmsKey_SetReadCb(LmsKey* key, wc_lms_read_private_key_cb read_cb);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 秘密鍵の読み込みコールバックと書き込みコールバックの両方に渡される、不透明なコンテキストポインタを設定します。通常、ファイルハンドル、データベース接続、その他の永続化層の状態を保持するために使用されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key LmsKeyへのポインタ。
|
||||
\param [in] context アプリケーションが定義するポインタ。NULLでも構いません。
|
||||
|
||||
\sa wc_LmsKey_SetReadCb
|
||||
\sa wc_LmsKey_SetWriteCb
|
||||
*/
|
||||
int wc_LmsKey_SetContext(LmsKey* key, void* context);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 新しいLMS/HSS鍵ペアを生成します。事前に(wc_LmsKey_SetLmsParm()またはwc_LmsKey_SetParameters()で)パラメータが設定され、読み込みコールバックと書き込みコールバックが登録されていなければなりません。新しく生成された秘密鍵は、この関数が戻る前に書き込みコールバックを介して永続化されます。成功時、鍵はWC_LMS_STATE_OK状態に遷移します。
|
||||
|
||||
鍵生成の実行時間は最初のツリーの高さに応じて急激に増加します。3レベルでh=5の構成は、1レベルでh=15の構成よりも鍵生成がはるかに高速ですが、どちらも合計の署名可能回数は同じです。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return MEMORY_E メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key コールバックが設定され、WC_LMS_STATE_PARMSET状態にあるLmsKeyへのポインタ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
LmsKey key;
|
||||
WC_RNG rng;
|
||||
|
||||
wc_LmsKey_Init(&key, NULL, INVALID_DEVID);
|
||||
wc_LmsKey_SetLmsParm(&key, WC_LMS_PARM_L2_H10_W8);
|
||||
wc_LmsKey_SetWriteCb(&key, my_write_cb);
|
||||
wc_LmsKey_SetReadCb(&key, my_read_cb);
|
||||
wc_LmsKey_SetContext(&key, &my_storage);
|
||||
wc_InitRng(&rng);
|
||||
|
||||
if (wc_LmsKey_MakeKey(&key, &rng) != 0) {
|
||||
// 鍵の生成エラー
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_LmsKey_Sign
|
||||
\sa wc_LmsKey_Reload
|
||||
*/
|
||||
int wc_LmsKey_MakeKey(LmsKey* key, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 登録された読み込みコールバックを使用して、以前生成したLMS/HSS秘密鍵を永続ストレージから再読み込みし、さらにメッセージへ署名できる状態に鍵を復元します。成功時、鍵はWC_LMS_STATE_OK状態になります。
|
||||
|
||||
Reloadを呼び出す前に、鍵生成時に設定したものと同じパラメータをLmsKeyに再適用しなければなりません(永続化されるデータは秘密鍵のバイト列のみであり、パラメータセットはアプリケーションが管理するメタデータです)。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return WC_LMS_RC_* 読み込みコールバックが失敗した場合、対応するエラーが返されます。
|
||||
|
||||
\param [in,out] key パラメータと読み込みコールバックが設定されたLmsKeyへのポインタ。
|
||||
|
||||
\sa wc_LmsKey_MakeKey
|
||||
\sa wc_LmsKey_SetReadCb
|
||||
*/
|
||||
int wc_LmsKey_Reload(LmsKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、エンコードされた秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたLmsKeyへのポインタ。
|
||||
\param [out] len 秘密鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_LmsKey_GetPubLen
|
||||
\sa wc_LmsKey_GetSigLen
|
||||
*/
|
||||
int wc_LmsKey_GetPrivLen(const LmsKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、LMS/HSS公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたLmsKeyへのポインタ。
|
||||
\param [out] len 公開鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_LmsKey_ExportPubRaw
|
||||
\sa wc_LmsKey_GetPrivLen
|
||||
*/
|
||||
int wc_LmsKey_GetPubLen(const LmsKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、LMS/HSS署名のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたLmsKeyへのポインタ。
|
||||
\param [out] len 署名のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_LmsKey_Sign
|
||||
*/
|
||||
int wc_LmsKey_GetSigLen(const LmsKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief keyが保持するLMS/HSS秘密鍵でmsgに署名します。呼び出し時、*sigSzはsigバッファのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
署名が成功するたびに、秘密鍵のワンタイムコンポーネントが1つ消費されます。更新された鍵の状態は、新しい署名が呼び出し側に返される前に、登録された書き込みコールバックを介して永続化されます。書き込みコールバックが失敗した場合、署名の呼び出しも失敗し、署名は返されません。使用可能なワンタイム鍵を使い切ると、鍵はWC_LMS_STATE_NOSIGS状態に遷移し、以降の署名の試行はSIG_OTHER_E(または類似のコード)を返します。この状態を事前に検出するにはwc_LmsKey_SigsLeft()を問い合わせてください。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *sigSzが署名のサイズより小さい場合に返されます。
|
||||
\return -1 (または類似のコード)すべてのワンタイム鍵が使用済みの場合に返されます。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_OK状態のLmsKeyへのポインタ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgSz msgのバイト単位の長さ。
|
||||
|
||||
\sa wc_LmsKey_Verify
|
||||
\sa wc_LmsKey_SigsLeft
|
||||
\sa wc_LmsKey_SetWriteCb
|
||||
*/
|
||||
int wc_LmsKey_Sign(LmsKey* key, byte* sig, word32* sigSz, const byte* msg,
|
||||
int msgSz);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief この鍵で残り何回のワンタイム署名が可能かを返します。この数が0になると、鍵はそれ以上署名できないため、使用を終了してください。
|
||||
|
||||
\return 成功した場合、残りの署名可能回数(非負の値)を返します。
|
||||
\return 失敗した場合は負のエラーコードが返されます(例: keyがNULLの場合はBAD_FUNC_ARG)。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_OK状態のLmsKeyへのポインタ。
|
||||
|
||||
\sa wc_LmsKey_Sign
|
||||
*/
|
||||
int wc_LmsKey_SigsLeft(LmsKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LmsKeyが保持しているリソースを解放します。NULLポインタを渡しても安全です。この呼び出しの後、鍵はWC_LMS_STATE_FREED状態になり、再利用する前に再初期化しなければなりません。
|
||||
|
||||
\param [in,out] key 解放するLmsKeyへのポインタ。
|
||||
|
||||
\sa wc_LmsKey_Init
|
||||
*/
|
||||
void wc_LmsKey_Free(LmsKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief keySrcの公開鍵部分をkeyDstにコピーします。コピー先の鍵は同じパラメータを継承し、検証に使用できます。秘密鍵の状態は持たないため、署名はできません。検証者に必要最小限のデータだけを渡す場合に有用です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyDstまたはkeySrcがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] keyDst 初期化済みのコピー先LmsKeyへのポインタ。
|
||||
\param [in] keySrc 公開鍵を保持するLmsKeyへのポインタ。
|
||||
|
||||
\sa wc_LmsKey_ExportPub_ex
|
||||
\sa wc_LmsKey_ExportPubRaw
|
||||
*/
|
||||
int wc_LmsKey_ExportPub(LmsKey* keyDst, const LmsKey* keySrc);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief wc_LmsKey_ExportPub()と同様ですが、コピー先の鍵は指定されたheapとdevIdで新規に初期化されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyDstまたはkeySrcがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] keyDst 内容を設定する対象のLmsKeyへのポインタ。
|
||||
\param [in] keySrc 公開鍵を保持するLmsKeyへのポインタ。
|
||||
\param [in] heap keyDst用のヒープヒント。
|
||||
\param [in] devId keyDst用のデバイス識別子。
|
||||
|
||||
\sa wc_LmsKey_ExportPub
|
||||
*/
|
||||
int wc_LmsKey_ExportPub_ex(LmsKey* keyDst, const LmsKey* keySrc, void* heap,
|
||||
int devId);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LMS/HSS公開鍵を生のバイト列としてエクスポートします。呼び出し時、*outLenはoutのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *outLenが公開鍵のサイズより小さい場合に返されます。
|
||||
|
||||
\param [in] key LmsKeyへのポインタ。
|
||||
\param [out] out 公開鍵を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時: outのサイズ。出力時: 書き込まれたバイト数。
|
||||
|
||||
\sa wc_LmsKey_ImportPubRaw
|
||||
\sa wc_LmsKey_GetPubLen
|
||||
*/
|
||||
int wc_LmsKey_ExportPubRaw(const LmsKey* key, byte* out, word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 生のLMS/HSS公開鍵をkeyにインポートします。鍵はWC_LMS_STATE_INITED状態でなければなりません。パラメータ情報はエンコードされたヘッダから復元され、その後、鍵はWC_LMS_STATE_VERIFYONLY状態に遷移します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E inLenが小さすぎる場合に返されます。
|
||||
|
||||
\param [in,out] key WC_LMS_STATE_INITED状態のLmsKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列。
|
||||
\param [in] inLen inのバイト単位の長さ。
|
||||
|
||||
\sa wc_LmsKey_ExportPubRaw
|
||||
\sa wc_LmsKey_Verify
|
||||
*/
|
||||
int wc_LmsKey_ImportPubRaw(LmsKey* key, const byte* in, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief keyが保持する公開鍵を使用して、msgに対するLMS/HSS署名を検証します。この関数は署名が有効な場合にのみ0を返します。それ以外の値は署名が拒否されたことを示します。
|
||||
|
||||
\return 0 署名が有効な場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return SIG_VERIFY_E (または類似のコード)署名が無効または形式が不正な場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵が設定されたLmsKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigSz sigのバイト単位の長さ。
|
||||
\param [in] msg 署名対象であったメッセージ。
|
||||
\param [in] msgSz msgのバイト単位の長さ。
|
||||
|
||||
\sa wc_LmsKey_Sign
|
||||
\sa wc_LmsKey_ImportPubRaw
|
||||
*/
|
||||
int wc_LmsKey_Verify(LmsKey* key, const byte* sig, word32 sigSz,
|
||||
const byte* msg, int msgSz);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LMSパラメータセットを説明する、静的でNUL終端された文字列を返します。ログ出力や診断に有用です。
|
||||
|
||||
\return 成功した場合、静的な文字列へのポインタを返します。
|
||||
\return NULL lmsParmが認識できない場合に返されます。
|
||||
|
||||
\param [in] lmsParm wc_LmsParm定数。
|
||||
|
||||
\sa wc_LmsKey_SetLmsParm
|
||||
*/
|
||||
const char* wc_LmsKey_ParmToStr(enum wc_LmsParm lmsParm);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief 秘密鍵に埋め込まれた16バイトのLMS鍵識別子(I)へのポインタと、その長さを返します。返されるポインタは内部の鍵メモリを参照しており、鍵が解放されるまでの間のみ有効です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するLmsKeyへのポインタ。
|
||||
\param [out] kid Iのバイト列へのポインタを受け取ります。
|
||||
\param [out] kidSz 長さ(16 / WC_LMS_I_LEN)を受け取ります。
|
||||
|
||||
\sa wc_LmsKey_GetKidFromPrivRaw
|
||||
*/
|
||||
int wc_LmsKey_GetKid(LmsKey* key, const byte** kid, word32* kidSz);
|
||||
|
||||
/*!
|
||||
\ingroup LMS
|
||||
|
||||
\brief LmsKeyオブジェクトを必要とせずに、生のエンコードされた秘密鍵バッファ内のLMS鍵識別子(I)へのポインタを返します。再読み込み時に、永続ストレージ内の対応する状態レコードを検索するために使用されます。
|
||||
|
||||
\return 成功した場合、priv内のIのバイト列へのポインタを返します。
|
||||
\return NULL privがNULLの場合、またはprivSzが有効なヘッダを含むには小さすぎる場合に返されます。
|
||||
|
||||
\param [in] priv エンコードされた秘密鍵バイト列。
|
||||
\param [in] privSz privのバイト単位の長さ。
|
||||
|
||||
\sa wc_LmsKey_GetKid
|
||||
*/
|
||||
const byte* wc_LmsKey_GetKidFromPrivRaw(const byte* priv, word32 privSz);
|
||||
@@ -0,0 +1,792 @@
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief wc_MlDsaKeyオブジェクトを初期化します。他のML-DSA操作を行う前に呼び出さなければなりません。使用が終わったらwc_MlDsaKey_Free()でリソースを解放してください。
|
||||
|
||||
ML-DSA(FIPS 204)は耐量子のデジタル署名アルゴリズムです。3つのパラメータセットが定義されており、初期化後にwc_MlDsaKey_SetParams()で選択します。
|
||||
- WC_ML_DSA_44(NISTセキュリティレベル2)
|
||||
- WC_ML_DSA_65(レベル3)
|
||||
- WC_ML_DSA_87(レベル5)
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_MlDsaKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
|
||||
if (ret != 0) {
|
||||
// 鍵の初期化エラー
|
||||
}
|
||||
ret = wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65);
|
||||
// ... 鍵を使用 ...
|
||||
wc_MlDsaKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_MlDsaKey_Free
|
||||
\sa wc_MlDsaKey_SetParams
|
||||
\sa wc_MlDsaKey_MakeKey
|
||||
*/
|
||||
int wc_MlDsaKey_Init(wc_MlDsaKey* key, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 新しいwc_MlDsaKeyをヒープ上に確保して初期化します。返されたポインタはwc_MlDsaKey_Delete()で解放しなければなりません。wolfSSLがWC_NO_CONSTRUCTORSを指定せずにビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 成功した場合、新しく確保されたwc_MlDsaKeyへのポインタを返します。
|
||||
\return NULL メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_MlDsaKey* key = wc_MlDsaKey_New(NULL, INVALID_DEVID);
|
||||
if (key == NULL) {
|
||||
// メモリ確保に失敗
|
||||
}
|
||||
// ... 鍵を使用 ...
|
||||
wc_MlDsaKey_Delete(key, &key);
|
||||
\endcode
|
||||
|
||||
\sa wc_MlDsaKey_Delete
|
||||
\sa wc_MlDsaKey_Init
|
||||
*/
|
||||
wc_MlDsaKey* wc_MlDsaKey_New(void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief wc_MlDsaKey_New()が返したヒープ上のwc_MlDsaKeyをゼロクリアして解放します。成功時、key_pがNULLでない場合はkey_pを介して呼び出し側のポインタ変数にNULLが設定されます。wolfSSLがWC_NO_CONSTRUCTORSを指定せずにビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 解放するwc_MlDsaKey。
|
||||
\param [in,out] key_p 呼び出し側のポインタ変数のアドレス(省略可)。NULLでない場合、成功時にNULLが設定されます。
|
||||
|
||||
\sa wc_MlDsaKey_New
|
||||
*/
|
||||
int wc_MlDsaKey_Delete(wc_MlDsaKey* key, wc_MlDsaKey** key_p);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief デバイス側の鍵識別子を指定してwc_MlDsaKeyを初期化します。wc_MlDsaKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるバイナリ形式のidも保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
idは鍵オブジェクトへコピーされます。呼び出し側はこの関数から戻った直後に自身のバッファを解放して構いません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
\return BUFFER_E lenが負の場合、またはMLDSA_MAX_ID_LENを超える場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] id デバイス側の鍵識別子バイト列へのポインタ。lenが0の場合はNULLでも構いません。
|
||||
\param [in] len idのバイト数。[0, MLDSA_MAX_ID_LEN]の範囲内でなければなりません。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。INVALID_DEVIDではなく、登録済みのコールバックのdevIdを指定してください。
|
||||
|
||||
\sa wc_MlDsaKey_Init
|
||||
\sa wc_MlDsaKey_InitLabel
|
||||
\sa wc_MlDsaKey_Free
|
||||
*/
|
||||
int wc_MlDsaKey_InitId(wc_MlDsaKey* key, const unsigned char* id, int len,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief デバイス側の鍵ラベルを指定してwc_MlDsaKeyを初期化します。wc_MlDsaKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるラベル文字列も保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
ラベルの長さはXSTRLENで取得されるため、途中にNULバイトが含まれるとそこでラベルが終端します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlabelがNULLの場合に返されます。
|
||||
\return BUFFER_E labelが空の場合、またはMLDSA_MAX_LABEL_LENより長い場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] label NUL終端されたデバイス側の鍵ラベル文字列。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_MlDsaKey_Init
|
||||
\sa wc_MlDsaKey_InitId
|
||||
\sa wc_MlDsaKey_Free
|
||||
*/
|
||||
int wc_MlDsaKey_InitLabel(wc_MlDsaKey* key, const char* label, void* heap,
|
||||
int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵に使用するML-DSAのパラメータセットを選択します。wc_MlDsaKey_Init()の後、鍵生成・署名・検証を行う前に呼び出さなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはlevelが認識できるパラメータセットでない場合に返されます。
|
||||
\return NOT_COMPILED_IN levelがビルド時に無効化されたパラメータセットを指している場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのwc_MlDsaKeyへのポインタ。
|
||||
\param [in] level パラメータセット。WC_ML_DSA_44、WC_ML_DSA_65、WC_ML_DSA_87のいずれか。
|
||||
|
||||
\sa wc_MlDsaKey_GetParams
|
||||
\sa wc_MlDsaKey_Init
|
||||
*/
|
||||
int wc_MlDsaKey_SetParams(wc_MlDsaKey* key, byte level);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵に現在設定されているML-DSAのパラメータセットを取得します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlevelがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのwc_MlDsaKeyへのポインタ。
|
||||
\param [out] level WC_ML_DSA_44、WC_ML_DSA_65、WC_ML_DSA_87のいずれかを受け取ります。
|
||||
|
||||
\sa wc_MlDsaKey_SetParams
|
||||
*/
|
||||
int wc_MlDsaKey_GetParams(wc_MlDsaKey* key, byte* level);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief wc_MlDsaKeyが保持しているリソースを解放します。この呼び出しの後、オブジェクトを再度使用するにはwc_MlDsaKey_Init()で再初期化しなければなりません。NULLポインタを渡しても安全です。
|
||||
|
||||
\param [in,out] key 解放するwc_MlDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_Init
|
||||
*/
|
||||
void wc_MlDsaKey_Free(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 指定されたRNGを使用して新しいML-DSA鍵ペアを生成します。事前にwc_MlDsaKey_SetParams()でパラメータセットが設定されていなければなりません。成功時には公開鍵と秘密鍵の両方の要素が設定されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはrngがNULLの場合に返されます。
|
||||
\return MEMORY_E メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_MlDsaKey key;
|
||||
WC_RNG rng;
|
||||
|
||||
wc_MlDsaKey_Init(&key, NULL, INVALID_DEVID);
|
||||
wc_MlDsaKey_SetParams(&key, WC_ML_DSA_65);
|
||||
wc_InitRng(&rng);
|
||||
|
||||
if (wc_MlDsaKey_MakeKey(&key, &rng) != 0) {
|
||||
// 鍵ペアの生成エラー
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_MlDsaKey_MakeKeyFromSeed
|
||||
\sa wc_MlDsaKey_SetParams
|
||||
*/
|
||||
int wc_MlDsaKey_MakeKey(wc_MlDsaKey* key, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 32バイトのシードからML-DSA鍵ペアを決定的に生成します。既知解テストや、シードを別の秘密から導出するアプリケーションで有用です。seedバッファはちょうど32バイトを保持していなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはseedがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [in] seed 32バイトのシードバッファへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_MakeKey
|
||||
*/
|
||||
int wc_MlDsaKey_MakeKeyFromSeed(wc_MlDsaKey* key, const byte* seed);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief FIPS 204のコンテキスト付きランダム化署名APIを使用して、ML-DSAでメッセージに署名します。空のコンテキストを使用する場合はctx=NULL、ctxLen=0を渡してください。
|
||||
|
||||
呼び出し時、*sigLenはsigバッファのサイズを表します。成功時には書き込まれたバイト数に更新されます。必要なバッファサイズはwc_MlDsaKey_SigSize()またはwc_MlDsaKey_GetSigLen()で取得できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはctxLenが無効な場合に返されます。
|
||||
\return BUFFER_E sigバッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULLでも構いません)。
|
||||
\param [in] ctxLen ctxのバイト単位の長さ。ctxがNULLの場合は0でなければならず、255以下でなければなりません。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_VerifyCtx
|
||||
\sa wc_MlDsaKey_SignCtxWithSeed
|
||||
\sa wc_MlDsaKey_SignCtxHash
|
||||
*/
|
||||
int wc_MlDsaKey_SignCtx(wc_MlDsaKey* key, const byte* ctx, byte ctxLen,
|
||||
byte* sig, word32* sigLen, const byte* msg, word32 msgLen, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief HashML-DSAの署名バリアントです。事前にハッシュされたメッセージに署名します。呼び出し側がハッシュ値のバイト列を渡し、ハッシュアルゴリズムを指定します。これはFIPS 204の「事前ハッシュ」モードです。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、ctxLenが無効な場合、またはhashAlgがサポートされていない場合に返されます。
|
||||
\return BUFFER_E sigバッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULL)。
|
||||
\param [in] ctxLen ctxのバイト単位の長さ。255以下でなければなりません。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] hash 署名するメッセージダイジェスト。
|
||||
\param [in] hashLen hashのバイト単位の長さ。
|
||||
\param [in] hashAlg ハッシュアルゴリズム識別子(例: WC_HASH_TYPE_SHA256)。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtx
|
||||
\sa wc_MlDsaKey_VerifyCtxHash
|
||||
*/
|
||||
int wc_MlDsaKey_SignCtxHash(wc_MlDsaKey* key, const byte* ctx, byte ctxLen,
|
||||
byte* sig, word32* sigLen, const byte* hash, word32 hashLen,
|
||||
int hashAlg, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief コンテキストパラメータを持たない旧来のML-DSA署名APIです。wolfSSLがWOLFSSL_MLDSA_NO_CTXを有効にしてビルドされている場合にのみ利用できます。新しいコードでは、FIPS 204に準拠した空コンテキストの署名を得るために、ctx=NULL、ctxLen=0でwc_MlDsaKey_SignCtx()を呼び出してください。
|
||||
|
||||
\return wc_MlDsaKey_SignCtx()を参照してください。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtx
|
||||
\sa wc_MlDsaKey_Verify
|
||||
*/
|
||||
int wc_MlDsaKey_Sign(wc_MlDsaKey* key, byte* sig, word32* sigLen,
|
||||
const byte* msg, word32 msgLen, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief wc_MlDsaKey_SignCtx()の決定的な署名バリアントです。32バイトのシードがRNGから供給される乱数を置き換えるため、同じkey/ctx/msg/seedの組み合わせからは常に同じ署名が生成されます。
|
||||
|
||||
\return wc_MlDsaKey_SignCtx()を参照してください。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULL)。
|
||||
\param [in] ctxLen ctxの長さ。255以下でなければなりません。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [in] seed 32バイトのシードバイト列。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtx
|
||||
\sa wc_MlDsaKey_SignCtxHashWithSeed
|
||||
*/
|
||||
int wc_MlDsaKey_SignCtxWithSeed(wc_MlDsaKey* key, const byte* ctx, byte ctxLen,
|
||||
byte* sig, word32* sigLen, const byte* msg, word32 msgLen,
|
||||
const byte* seed);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 決定的なHashML-DSA署名です。wc_MlDsaKey_SignCtxHash()と同様ですが、RNGの代わりに与えられた32バイトのシードを使用します。
|
||||
|
||||
\return wc_MlDsaKey_SignCtxHash()を参照してください。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULL)。
|
||||
\param [in] ctxLen ctxの長さ。255以下でなければなりません。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] hash 署名するメッセージダイジェスト。
|
||||
\param [in] hashLen hashのバイト単位の長さ。
|
||||
\param [in] hashAlg ハッシュアルゴリズム識別子。
|
||||
\param [in] seed 32バイトのシードバイト列。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtxHash
|
||||
*/
|
||||
int wc_MlDsaKey_SignCtxHashWithSeed(wc_MlDsaKey* key, const byte* ctx,
|
||||
byte ctxLen, byte* sig, word32* sigLen, const byte* hash,
|
||||
word32 hashLen, int hashAlg, const byte* seed);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 決定的な32バイトのシードを使用して、事前に計算されたmu値(FIPS 204に従って外部で導出された(tr || ctx || msg)のSHAKE256ハッシュ)に署名します。メッセージのハッシュ処理と署名処理を分離する必要があるプロトコルで使用されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはmuLenが64でない場合に返されます。
|
||||
\return BUFFER_E sigバッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] mu 64バイトのmu値(SHAKE256の出力)。
|
||||
\param [in] muLen muの長さ。64でなければなりません。
|
||||
\param [in] seed 32バイトのシードバイト列。
|
||||
|
||||
\sa wc_MlDsaKey_VerifyMu
|
||||
*/
|
||||
int wc_MlDsaKey_SignMuWithSeed(wc_MlDsaKey* key, byte* sig, word32* sigLen,
|
||||
const byte* mu, word32 muLen, const byte* seed);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief コンテキストパラメータを持たない旧来のシードベース署名APIです。wolfSSLがWOLFSSL_MLDSA_NO_CTXを有効にしてビルドされている場合にのみ利用できます。新しいコードではwc_MlDsaKey_SignCtxWithSeed()を使用してください。
|
||||
|
||||
\return wc_MlDsaKey_SignCtxWithSeed()を参照してください。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigLen 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [in] seed 32バイトのシードバイト列。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtxWithSeed
|
||||
*/
|
||||
int wc_MlDsaKey_SignWithSeed(wc_MlDsaKey* key, byte* sig, word32* sigLen,
|
||||
const byte* msg, word32 msgLen, const byte* seed);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief wc_MlDsaKey_SignCtx()またはそのバリアントが生成したML-DSA署名を検証します。呼び出し時にresは0に設定され、署名が有効な場合は1に設定されます。それ以外の場合は0のままです。この関数の戻り値は検証処理を実行できたかどうかを示すものであり、署名が不正であること自体は関数レベルのエラーではありません。
|
||||
|
||||
\return 0 検証処理が完了した場合に返されます(結果はresを確認してください)。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはctxLenが無効な場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigLen sigのバイト単位の長さ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULL)。
|
||||
\param [in] ctxLen ctxの長さ。255以下でなければなりません。
|
||||
\param [in] msg 署名対象であったメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [out] res 署名が有効な場合は1、それ以外の場合は0が設定されます。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtx
|
||||
\sa wc_MlDsaKey_VerifyCtxHash
|
||||
\sa wc_MlDsaKey_VerifyMu
|
||||
*/
|
||||
int wc_MlDsaKey_VerifyCtx(wc_MlDsaKey* key, const byte* sig, word32 sigLen,
|
||||
const byte* ctx, byte ctxLen, const byte* msg, word32 msgLen, int* res);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief メッセージダイジェストが直接渡されたHashML-DSA署名を検証します。resの意味についてはwc_MlDsaKey_VerifyCtx()を参照してください。
|
||||
|
||||
\return 0 検証処理が完了した場合に返されます(結果はresを確認してください)。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、ctxLenが無効な場合、またはhashAlgがサポートされていない場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigLen sigのバイト単位の長さ。
|
||||
\param [in] ctx コンテキスト文字列(省略可。ctxLen=0の場合はNULL)。
|
||||
\param [in] ctxLen ctxの長さ。255以下でなければなりません。
|
||||
\param [in] hash 署名対象であったメッセージダイジェスト。
|
||||
\param [in] hashLen hashのバイト単位の長さ。
|
||||
\param [in] hashAlg ハッシュアルゴリズム識別子。
|
||||
\param [out] res 署名が有効な場合は1、それ以外の場合は0が設定されます。
|
||||
|
||||
\sa wc_MlDsaKey_SignCtxHash
|
||||
\sa wc_MlDsaKey_VerifyCtx
|
||||
*/
|
||||
int wc_MlDsaKey_VerifyCtxHash(wc_MlDsaKey* key, const byte* sig, word32 sigLen,
|
||||
const byte* ctx, byte ctxLen, const byte* hash, word32 hashLen,
|
||||
int hashAlg, int* res);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 事前に計算された64バイトのmu値に対する署名を検証します(wc_MlDsaKey_SignMuWithSeed()を参照)。resの意味についてはwc_MlDsaKey_VerifyCtx()を参照してください。
|
||||
|
||||
\return 0 検証処理が完了した場合に返されます(結果はresを確認してください)。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはmuLenが64でない場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigLen sigのバイト単位の長さ。
|
||||
\param [in] mu 64バイトのmu値。
|
||||
\param [in] muLen muの長さ。64でなければなりません。
|
||||
\param [out] res 署名が有効な場合は1、それ以外の場合は0が設定されます。
|
||||
|
||||
\sa wc_MlDsaKey_SignMuWithSeed
|
||||
*/
|
||||
int wc_MlDsaKey_VerifyMu(wc_MlDsaKey* key, const byte* sig, word32 sigLen,
|
||||
const byte* mu, word32 muLen, int* res);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief コンテキストパラメータを持たない旧来のML-DSA検証APIです。wolfSSLがWOLFSSL_MLDSA_NO_CTXを有効にしてビルドされている場合にのみ利用できます。新しいコードではctx=NULL、ctxLen=0でwc_MlDsaKey_VerifyCtx()を使用してください。
|
||||
|
||||
\return wc_MlDsaKey_VerifyCtx()を参照してください。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigLen sigのバイト単位の長さ。
|
||||
\param [in] msg 署名対象であったメッセージ。
|
||||
\param [in] msgLen msgのバイト単位の長さ。
|
||||
\param [out] res 署名が有効な場合は1、それ以外の場合は0が設定されます。
|
||||
|
||||
\sa wc_MlDsaKey_VerifyCtx
|
||||
\sa wc_MlDsaKey_Sign
|
||||
*/
|
||||
int wc_MlDsaKey_Verify(wc_MlDsaKey* key, const byte* sig, word32 sigLen,
|
||||
const byte* msg, word32 msgLen, int* res);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、エンコードされた秘密鍵のサイズをバイト単位で返します。wc_MlDsaKey_PrivSize()と同等で、APIの互換性のために提供されています。
|
||||
|
||||
\return 成功した場合、エンコードされた秘密鍵のサイズ(バイト単位、正の値)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_PrivSize
|
||||
\sa wc_MlDsaKey_PubSize
|
||||
\sa wc_MlDsaKey_SigSize
|
||||
*/
|
||||
int wc_MlDsaKey_Size(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、エンコードされた秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、エンコードされた秘密鍵のサイズ(正の値)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_PubSize
|
||||
\sa wc_MlDsaKey_GetPrivLen
|
||||
*/
|
||||
int wc_MlDsaKey_PrivSize(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、エンコードされた公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、エンコードされた公開鍵のサイズ(正の値)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_PrivSize
|
||||
\sa wc_MlDsaKey_GetPubLen
|
||||
*/
|
||||
int wc_MlDsaKey_PubSize(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief この鍵のパラメータセットで生成される署名のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、署名のサイズ(正の値)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_MlDsaKey_GetSigLen
|
||||
\sa wc_MlDsaKey_SignCtx
|
||||
*/
|
||||
int wc_MlDsaKey_SigSize(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief エンコードされた秘密鍵のサイズを*lenに書き込みます。wc_MlDsaKey_PrivSize()と同じ情報を、出力パラメータ形式で提供します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合、あるいはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [out] len 秘密鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlDsaKey_PrivSize
|
||||
*/
|
||||
int wc_MlDsaKey_GetPrivLen(wc_MlDsaKey* key, int* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief エンコードされた公開鍵のサイズを*lenに書き込みます。wc_MlDsaKey_PubSize()と同じ情報を、出力パラメータ形式で提供します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合、あるいはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [out] len 公開鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlDsaKey_PubSize
|
||||
*/
|
||||
int wc_MlDsaKey_GetPubLen(wc_MlDsaKey* key, int* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 署名のサイズを*lenに書き込みます。wc_MlDsaKey_SigSize()と同じ情報を、出力パラメータ形式で提供します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合、あるいはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [out] len 署名のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlDsaKey_SigSize
|
||||
*/
|
||||
int wc_MlDsaKey_GetSigLen(wc_MlDsaKey* key, int* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 秘密鍵から公開鍵を再計算し、保存されている公開鍵と比較することでML-DSA鍵を自己検査します。wolfSSLがWOLFSSL_MLDSA_CHECK_KEYを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 0 鍵が整合している場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
\return PUBLIC_KEY_E 再計算した公開鍵が一致しない場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵部分と秘密鍵部分の両方が設定されたwc_MlDsaKeyへのポインタ。
|
||||
*/
|
||||
int wc_MlDsaKey_CheckKey(wc_MlDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生のML-DSA公開鍵をインポートします。パラメータセットは事前に鍵に設定されている必要があります。inLenは、設定されているパラメータセットに対してwc_MlDsaKey_PubSize()が返すサイズと一致しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはinがNULLの場合に返されます。
|
||||
\return BUFFER_E inLenが期待される公開鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列。
|
||||
\param [in] inLen inのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlDsaKey_ExportPubRaw
|
||||
\sa wc_MlDsaKey_ImportPrivRaw
|
||||
*/
|
||||
int wc_MlDsaKey_ImportPubRaw(wc_MlDsaKey* key, const byte* in, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生のML-DSA秘密鍵をインポートします。パラメータセットは事前に設定されている必要があります。privSzはwc_MlDsaKey_PrivSize()が返すサイズと一致しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはprivがNULLの場合に返されます。
|
||||
\return BUFFER_E privSzが期待される秘密鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [in] priv 生の秘密鍵バイト列。
|
||||
\param [in] privSz privのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlDsaKey_ExportPrivRaw
|
||||
\sa wc_MlDsaKey_ImportKey
|
||||
*/
|
||||
int wc_MlDsaKey_ImportPrivRaw(wc_MlDsaKey* key, const byte* priv,
|
||||
word32 privSz);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生のML-DSA鍵ペア(秘密鍵部分と公開鍵部分をまとめて)をインポートします。パラメータセットは事前に設定されている必要があります。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E privSzまたはpubSzが期待されるサイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたwc_MlDsaKeyへのポインタ。
|
||||
\param [in] priv 生の秘密鍵バイト列。
|
||||
\param [in] privSz privの長さ。
|
||||
\param [in] pub 生の公開鍵バイト列。
|
||||
\param [in] pubSz pubの長さ。
|
||||
|
||||
\sa wc_MlDsaKey_ExportKey
|
||||
*/
|
||||
int wc_MlDsaKey_ImportKey(wc_MlDsaKey* key, const byte* priv, word32 privSz,
|
||||
const byte* pub, word32 pubSz);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生のML-DSA公開鍵をエクスポートします。呼び出し時、*outLenはoutのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *outLenが公開鍵のサイズより小さい場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] out 公開鍵を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時: outのサイズ。出力時: 書き込まれたバイト数。
|
||||
|
||||
\sa wc_MlDsaKey_ImportPubRaw
|
||||
*/
|
||||
int wc_MlDsaKey_ExportPubRaw(wc_MlDsaKey* key, byte* out, word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生のML-DSA秘密鍵をエクスポートします。呼び出し時、*outLenはoutのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *outLenが秘密鍵のサイズより小さい場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] out 秘密鍵を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時: outのサイズ。出力時: 書き込まれたバイト数。
|
||||
|
||||
\sa wc_MlDsaKey_ImportPrivRaw
|
||||
*/
|
||||
int wc_MlDsaKey_ExportPrivRaw(wc_MlDsaKey* key, byte* out, word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief 生の公開鍵と秘密鍵の両方のML-DSA鍵要素を1回の呼び出しでエクスポートします。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E いずれかのバッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in] key 両方の鍵要素を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] priv 秘密鍵を受け取るバッファ。
|
||||
\param [in,out] privSz 入力時: privのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [out] pub 公開鍵を受け取るバッファ。
|
||||
\param [in,out] pubSz 入力時: pubのサイズ。出力時: 書き込まれたバイト数。
|
||||
|
||||
\sa wc_MlDsaKey_ImportKey
|
||||
*/
|
||||
int wc_MlDsaKey_ExportKey(wc_MlDsaKey* key, byte* priv, word32 *privSz,
|
||||
byte* pub, word32 *pubSz);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief DER/ASN.1でエンコードされたバッファ(PKCS#8 OneAsymmetricKey)からML-DSA秘密鍵を解析します。パラメータセットはエンコード内のアルゴリズム識別子から推定されるため、事前に設定する必要はありません。成功時、*inOutIdxは消費したバイト数分進められます。
|
||||
|
||||
WOLFSSL_MLDSA_NO_ASN1が定義されていない場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return ASN_PARSE_E エンコードの形式が不正な場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのwc_MlDsaKeyへのポインタ。
|
||||
\param [in] input DERエンコードされた秘密鍵バイト列。
|
||||
\param [in] inSz inputのバイト単位の長さ。
|
||||
\param [in,out] inOutIdx 入力時: デコードを開始するinput内のオフセット。出力時: 消費したバイトの直後のオフセット。
|
||||
|
||||
\sa wc_MlDsaKey_PrivateKeyToDer
|
||||
\sa wc_MlDsaKey_PublicKeyDecode
|
||||
*/
|
||||
int wc_MlDsaKey_PrivateKeyDecode(wc_MlDsaKey* key, const byte* input,
|
||||
word32 inSz, word32* inOutIdx);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief DER/ASN.1でエンコードされたバッファ(SubjectPublicKeyInfo)からML-DSA公開鍵を解析します。パラメータセットはアルゴリズム識別子から推定されます。成功時、*inOutIdxは消費したバイト数分進められます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return ASN_PARSE_E エンコードの形式が不正な場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのwc_MlDsaKeyへのポインタ。
|
||||
\param [in] input DERエンコードされたSPKIバイト列。
|
||||
\param [in] inSz inputのバイト単位の長さ。
|
||||
\param [in,out] inOutIdx 入力時: デコードを開始するinput内のオフセット。出力時: 消費したバイトの直後のオフセット。
|
||||
|
||||
\sa wc_MlDsaKey_PublicKeyToDer
|
||||
*/
|
||||
int wc_MlDsaKey_PublicKeyDecode(wc_MlDsaKey* key, const byte* input,
|
||||
word32 inSz, word32* inOutIdx);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief ML-DSA公開鍵をDERにエンコードします。withAlgが0以外の場合、出力は完全なSubjectPublicKeyInfo(AlgorithmIdentifierを含む)になります。0の場合、出力は生の公開鍵バイト列になります。
|
||||
|
||||
必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
\return BUFFER_E outputがNULLでなく、inLenが必要なサイズより小さい場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] output DERエンコードを受け取るバッファ。サイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのサイズ(outputがNULLの場合は無視されます)。
|
||||
\param [in] withAlg SubjectPublicKeyInfoを出力する場合は0以外、生の公開鍵のみを出力する場合は0。
|
||||
|
||||
\sa wc_MlDsaKey_PublicKeyDecode
|
||||
\sa wc_MlDsaKey_KeyToDer
|
||||
*/
|
||||
int wc_MlDsaKey_PublicKeyToDer(wc_MlDsaKey* key, byte* output,
|
||||
word32 inLen, int withAlg);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief ML-DSA鍵ペア(公開鍵+秘密鍵)をPKCS#8 OneAsymmetricKey構造としてDERにエンコードします。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
\return BUFFER_E outputがNULLでなく、inLenが小さすぎる場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] output DERエンコードを受け取るバッファ。サイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのサイズ(outputがNULLの場合は無視されます)。
|
||||
|
||||
\sa wc_MlDsaKey_PrivateKeyDecode
|
||||
\sa wc_MlDsaKey_PrivateKeyToDer
|
||||
\sa wc_MlDsaKey_PublicKeyToDer
|
||||
*/
|
||||
int wc_MlDsaKey_KeyToDer(wc_MlDsaKey* key, byte* output, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup ML_DSA
|
||||
|
||||
\brief ML-DSA秘密鍵をDERにエンコードします。FIPS 204では秘密鍵のエンコードに公開鍵の要素が含まれるため、この関数は現在wc_MlDsaKey_KeyToDer()のエイリアスであり、他のアルゴリズムとのAPIの一貫性のために維持されています。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。
|
||||
\return wc_MlDsaKey_KeyToDer()から引き継がれたエラーコードが返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するwc_MlDsaKeyへのポインタ。
|
||||
\param [out] output DERエンコードを受け取るバッファ。サイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのサイズ(outputがNULLの場合は無視されます)。
|
||||
|
||||
\sa wc_MlDsaKey_KeyToDer
|
||||
\sa wc_MlDsaKey_PrivateKeyDecode
|
||||
*/
|
||||
int wc_MlDsaKey_PrivateKeyToDer(wc_MlDsaKey* key, byte* output,
|
||||
word32 inLen);
|
||||
@@ -0,0 +1,403 @@
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 新しいMlKemKeyをヒープ上に確保して初期化します。返されたポインタはwc_MlKemKey_Delete()で解放しなければなりません。
|
||||
|
||||
ML-KEM(FIPS 203)は耐量子の鍵カプセル化メカニズムです。typeパラメータでバリアントを選択します。WC_ML_KEM_512(NISTセキュリティレベル1)、WC_ML_KEM_768(レベル3)、WC_ML_KEM_1024(レベル5)のいずれかです。
|
||||
|
||||
\return 成功した場合、新しく確保されたMlKemKeyへのポインタを返します。
|
||||
\return NULL メモリ確保に失敗した場合、またはtypeが無効な場合に返されます。
|
||||
|
||||
\param [in] type ML-KEMのバリアント。WC_ML_KEM_512、WC_ML_KEM_768、WC_ML_KEM_1024のいずれか。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
MlKemKey* key = wc_MlKemKey_New(WC_ML_KEM_768, NULL,
|
||||
INVALID_DEVID);
|
||||
if (key == NULL) {
|
||||
// メモリ確保に失敗
|
||||
}
|
||||
// ... 鍵を使用 ...
|
||||
wc_MlKemKey_Delete(key, &key);
|
||||
\endcode
|
||||
|
||||
\sa wc_MlKemKey_Delete
|
||||
\sa wc_MlKemKey_Init
|
||||
*/
|
||||
MlKemKey* wc_MlKemKey_New(int type, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief wc_MlKemKey_New()が返したヒープ上のMlKemKeyをゼロクリアして解放します。成功時、key_pがNULLでない場合はkey_pを介して呼び出し側のポインタ変数にNULLが設定されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 解放するMlKemKey。
|
||||
\param [in,out] key_p 呼び出し側のポインタ変数のアドレス(省略可)。NULLでない場合、成功時にNULLが設定されます。
|
||||
|
||||
\sa wc_MlKemKey_New
|
||||
*/
|
||||
int wc_MlKemKey_Delete(MlKemKey* key, MlKemKey** key_p);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 呼び出し側が用意したMlKemKeyオブジェクトを初期化します。typeパラメータはML-KEMのバリアントを選択し、WC_ML_KEM_512、WC_ML_KEM_768、WC_ML_KEM_1024のいずれかでなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはtypeが無効な場合に返されます。
|
||||
\return NOT_COMPILED_IN typeがビルド時に無効化されたバリアントを指している場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するMlKemKeyへのポインタ。
|
||||
\param [in] type ML-KEMのバリアント。WC_ML_KEM_512、WC_ML_KEM_768、WC_ML_KEM_1024のいずれか。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
MlKemKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_MlKemKey_Init(&key, WC_ML_KEM_768, NULL, INVALID_DEVID);
|
||||
if (ret != 0) {
|
||||
// 鍵の初期化エラー
|
||||
}
|
||||
// ... 鍵を使用 ...
|
||||
wc_MlKemKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_MlKemKey_Free
|
||||
\sa wc_MlKemKey_MakeKey
|
||||
*/
|
||||
int wc_MlKemKey_Init(MlKemKey* key, int type, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief MlKemKeyが保持しているリソースを解放します。この呼び出しの後、オブジェクトを再度使用するにはwc_MlKemKey_Init()で再初期化しなければなりません。NULLポインタを渡しても安全です。
|
||||
|
||||
\return 0 成功した場合に返されます。keyがNULLの場合も含みます。
|
||||
|
||||
\param [in,out] key 解放するMlKemKeyへのポインタ。
|
||||
|
||||
\sa wc_MlKemKey_Init
|
||||
*/
|
||||
int wc_MlKemKey_Free(MlKemKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief デバイス側の鍵識別子を指定してMlKemKeyを初期化します。wc_MlKemKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるバイナリ形式のidも保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
idは鍵オブジェクトへコピーされます。呼び出し側はこの関数から戻った直後に自身のバッファを解放して構いません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、lenが0でないにもかかわらずidがNULLの場合、またはtypeが無効な場合に返されます。
|
||||
\return BUFFER_E lenが負の場合、またはMLKEM_MAX_ID_LENを超える場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するMlKemKeyへのポインタ。
|
||||
\param [in] type ML-KEMのバリアント識別子。
|
||||
\param [in] id デバイス側の鍵識別子バイト列へのポインタ。lenが0の場合はNULLでも構いません。
|
||||
\param [in] len idのバイト数。[0, MLKEM_MAX_ID_LEN]の範囲内でなければなりません。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_MlKemKey_Init
|
||||
\sa wc_MlKemKey_Init_Label
|
||||
\sa wc_MlKemKey_Free
|
||||
*/
|
||||
int wc_MlKemKey_Init_Id(MlKemKey* key, int type, const unsigned char* id,
|
||||
int len, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief デバイス側の鍵ラベルを指定してMlKemKeyを初期化します。wc_MlKemKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるラベル文字列も保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlabelがNULLの場合、またはtypeが無効な場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するMlKemKeyへのポインタ。
|
||||
\param [in] type ML-KEMのバリアント識別子。
|
||||
\param [in] label NUL終端されたデバイス側の鍵ラベル。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_MlKemKey_Init
|
||||
\sa wc_MlKemKey_Init_Id
|
||||
\sa wc_MlKemKey_Free
|
||||
*/
|
||||
int wc_MlKemKey_Init_Label(MlKemKey* key, int type, const char* label,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 指定されたRNGを使用して新しいML-KEM鍵ペアを生成します。成功時には公開鍵と秘密鍵の両方の要素が設定されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはrngがNULLの場合に返されます。
|
||||
\return MEMORY_E メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
MlKemKey key;
|
||||
WC_RNG rng;
|
||||
|
||||
wc_MlKemKey_Init(&key, WC_ML_KEM_768, NULL, INVALID_DEVID);
|
||||
wc_InitRng(&rng);
|
||||
|
||||
if (wc_MlKemKey_MakeKey(&key, &rng) != 0) {
|
||||
// 鍵ペアの生成エラー
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_MlKemKey_MakeKeyWithRandom
|
||||
\sa wc_MlKemKey_Encapsulate
|
||||
\sa wc_MlKemKey_Decapsulate
|
||||
*/
|
||||
int wc_MlKemKey_MakeKey(MlKemKey* key, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 決定的な鍵生成を行います。RNGの代わりに、与えられた64バイトの乱数からML-KEM鍵ペアを生成します。既知解テストや、鍵の乱数を別の秘密から導出するアプリケーションで有用です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはlenが64でない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [in] rand 乱数バッファへのポインタ。
|
||||
\param [in] len randのバイト単位の長さ。64でなければなりません。
|
||||
|
||||
\sa wc_MlKemKey_MakeKey
|
||||
*/
|
||||
int wc_MlKemKey_MakeKeyWithRandom(MlKemKey* key, const unsigned char* rand,
|
||||
int len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief この鍵に設定されているバリアントの暗号文サイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [out] len 暗号文サイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlKemKey_SharedSecretSize
|
||||
\sa wc_MlKemKey_Encapsulate
|
||||
*/
|
||||
int wc_MlKemKey_CipherTextSize(MlKemKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief ML-KEMの共有秘密サイズをバイト単位で返します。この値はすべてのパラメータセットで同一(32バイト)ですが、wc_MlKemKey_CipherTextSize()との対称性のためにプログラムから問い合わせられるようになっています。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [out] len 共有秘密サイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlKemKey_CipherTextSize
|
||||
*/
|
||||
int wc_MlKemKey_SharedSecretSize(MlKemKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief keyが保持する公開鍵に対して、新しい共有秘密をカプセル化します。対応する秘密鍵の保持者がwc_MlKemKey_Decapsulate()に渡すことで同じ共有秘密を復元できる暗号文を生成します。
|
||||
|
||||
ctバッファはwc_MlKemKey_CipherTextSize()バイト以上、ssバッファはwc_MlKemKey_SharedSecretSize()バイト以上でなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BAD_STATE_E 公開鍵が設定されていない場合に返されます。
|
||||
\return NOT_COMPILED_IN wolfSSLがWC_NO_RNGを指定してビルドされている場合に返されます。
|
||||
\return MEMORY_E カプセル化ルーチン内でメモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するMlKemKeyへのポインタ。
|
||||
\param [out] ct 暗号文を受け取るバッファ。
|
||||
\param [out] ss 32バイトの共有秘密を受け取るバッファ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
MlKemKey key;
|
||||
unsigned char ct[WC_ML_KEM_768_CIPHER_TEXT_SIZE];
|
||||
unsigned char ss[WC_ML_KEM_SS_SZ];
|
||||
|
||||
// ... keyは受信者の公開鍵を保持している ...
|
||||
if (wc_MlKemKey_Encapsulate(&key, ct, ss, &rng) != 0) {
|
||||
// カプセル化中のエラー
|
||||
}
|
||||
// ctを対応する秘密鍵の保持者に送信します。
|
||||
\endcode
|
||||
|
||||
\sa wc_MlKemKey_EncapsulateWithRandom
|
||||
\sa wc_MlKemKey_Decapsulate
|
||||
*/
|
||||
int wc_MlKemKey_Encapsulate(MlKemKey* key, unsigned char* ct,
|
||||
unsigned char* ss, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief wc_MlKemKey_Encapsulate()の決定的なバリアントです。RNGの出力を消費する代わりに、与えられた32バイトの乱数を使用します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはlenが32でない場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するMlKemKeyへのポインタ。
|
||||
\param [out] ct 暗号文を受け取るバッファ。
|
||||
\param [out] ss 32バイトの共有秘密を受け取るバッファ。
|
||||
\param [in] rand 乱数バッファ。
|
||||
\param [in] len randのバイト単位の長さ。32でなければなりません。
|
||||
|
||||
\sa wc_MlKemKey_Encapsulate
|
||||
*/
|
||||
int wc_MlKemKey_EncapsulateWithRandom(MlKemKey* key, unsigned char* ct,
|
||||
unsigned char* ss, const unsigned char* rand, int len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief keyが保持する秘密鍵を使用して暗号文のカプセル化を解除し、wc_MlKemKey_Encapsulate()が生成した共有秘密を復元します。ML-KEMのカプセル化解除は一定時間で実行され、不正な形式の暗号文に対する暗黙的拒否のチェックを含みます(攻撃者は実行時間からctの正当性を知ることはできません)。
|
||||
|
||||
ssバッファはwc_MlKemKey_SharedSecretSize()バイト以上、ctはちょうどwc_MlKemKey_CipherTextSize()バイトでなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます(共有秘密がssに書き込まれました)。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BAD_STATE_E 秘密鍵が設定されていない場合に返されます。
|
||||
\return BUFFER_E lenが、設定されているML-KEMバリアントで期待される暗号文サイズと一致しない場合に返されます。
|
||||
\return NOT_COMPILED_IN 鍵のML-KEMバリアントがビルド時に無効化されている場合に返されます。
|
||||
\return MEMORY_E メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key 秘密鍵を保持するMlKemKeyへのポインタ。
|
||||
\param [out] ss 32バイトの共有秘密を受け取るバッファ。
|
||||
\param [in] ct カプセル化を解除する暗号文。
|
||||
\param [in] len ctのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlKemKey_Encapsulate
|
||||
\sa wc_MlKemKey_CipherTextSize
|
||||
*/
|
||||
int wc_MlKemKey_Decapsulate(MlKemKey* key, unsigned char* ss,
|
||||
const unsigned char* ct, word32 len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 生のML-KEM秘密鍵をデコードしてkeyに格納します。バリアントは事前に鍵に設定されている必要があり(通常はwc_MlKemKey_Init()またはwc_MlKemKey_New()で選択します)、lenはそのバリアントの秘密鍵サイズと一致しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはlenが期待されるサイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [in] in 生の秘密鍵バイト列。
|
||||
\param [in] len inのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlKemKey_EncodePrivateKey
|
||||
\sa wc_MlKemKey_PrivateKeySize
|
||||
*/
|
||||
int wc_MlKemKey_DecodePrivateKey(MlKemKey* key, const unsigned char* in,
|
||||
word32 len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief 生のML-KEM公開鍵をデコードしてkeyに格納します。バリアントは事前に鍵に設定されている必要があり、lenはそのバリアントの公開鍵サイズと一致しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはlenが期待されるサイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列。
|
||||
\param [in] len inのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlKemKey_EncodePublicKey
|
||||
\sa wc_MlKemKey_PublicKeySize
|
||||
*/
|
||||
int wc_MlKemKey_DecodePublicKey(MlKemKey* key, const unsigned char* in,
|
||||
word32 len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief この鍵に設定されているバリアントの、エンコードされた秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [out] len 秘密鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlKemKey_PublicKeySize
|
||||
*/
|
||||
int wc_MlKemKey_PrivateKeySize(MlKemKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief この鍵に設定されているバリアントの、エンコードされた公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのMlKemKeyへのポインタ。
|
||||
\param [out] len 公開鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_MlKemKey_PrivateKeySize
|
||||
*/
|
||||
int wc_MlKemKey_PublicKeySize(MlKemKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief ML-KEM秘密鍵をエンコードしてoutに格納します。outバッファの長さはちょうどwc_MlKemKey_PrivateKeySize()バイトでなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BAD_STATE_E 鍵オブジェクトに秘密鍵と公開鍵のいずれかが設定されていない場合に返されます。
|
||||
\return BUFFER_E lenが、設定されているML-KEMバリアントでエンコードされた秘密鍵のサイズと完全に一致しない場合に返されます。
|
||||
\return NOT_COMPILED_IN 鍵のML-KEMバリアントがビルド時に無効化されている場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するMlKemKeyへのポインタ。
|
||||
\param [out] out エンコードされた秘密鍵を受け取るバッファ。
|
||||
\param [in] len outのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlKemKey_DecodePrivateKey
|
||||
\sa wc_MlKemKey_PrivateKeySize
|
||||
*/
|
||||
int wc_MlKemKey_EncodePrivateKey(MlKemKey* key, unsigned char* out,
|
||||
word32 len);
|
||||
|
||||
/*!
|
||||
\ingroup ML_KEM
|
||||
|
||||
\brief ML-KEM公開鍵をエンコードしてoutに格納します。outバッファの長さはちょうどwc_MlKemKey_PublicKeySize()バイトでなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BAD_STATE_E 公開鍵が設定されていない場合に返されます。
|
||||
\return BUFFER_E lenが、設定されているML-KEMバリアントでエンコードされた公開鍵のサイズと完全に一致しない場合に返されます。
|
||||
\return NOT_COMPILED_IN 鍵のML-KEMバリアントがビルド時に無効化されている場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するMlKemKeyへのポインタ。
|
||||
\param [out] out エンコードされた公開鍵を受け取るバッファ。
|
||||
\param [in] len outのバイト単位の長さ。
|
||||
|
||||
\sa wc_MlKemKey_DecodePublicKey
|
||||
\sa wc_MlKemKey_PublicKeySize
|
||||
*/
|
||||
int wc_MlKemKey_EncodePublicKey(MlKemKey* key, unsigned char* out,
|
||||
word32 len);
|
||||
@@ -0,0 +1,732 @@
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief ヒープヒントとデバイスIDを指定してSHEコンテキストを初期化します。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheがNULLの場合に返されます
|
||||
|
||||
\param she 初期化するwc_SHE構造体へのポインタ
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID、またはソフトウェアのみで処理する場合はINVALID_DEVID
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_SHE she;
|
||||
int ret;
|
||||
ret = wc_SHE_Init(&she, NULL, INVALID_DEVID);
|
||||
if (ret == 0) {
|
||||
// sheコンテキストを使用します
|
||||
}
|
||||
wc_SHE_Free(&she);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_Init_Id
|
||||
\sa wc_SHE_Init_Label
|
||||
\sa wc_SHE_Free
|
||||
*/
|
||||
int wc_SHE_Init(wc_SHE* she, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 不透明なハードウェア鍵識別子を指定してSHEコンテキストを初期化します。暗号コールバックを使用し、スロットや鍵グループの情報を判別するためにSHEコンテキストへ追加情報を付加する必要がある場合に有用です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheがNULLの場合、lenが0より大きいにもかかわらずidがNULLの場合、またはlenがWC_SHE_MAX_ID_LENを超える場合に返されます
|
||||
|
||||
\param she 初期化するwc_SHE構造体へのポインタ
|
||||
\param id 不透明な鍵識別子のバイト列
|
||||
\param len idのバイト単位の長さ(0からWC_SHE_MAX_ID_LEN)
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_SHE she;
|
||||
unsigned char myId[] = { 0x01, 0x02, 0x03 };
|
||||
int ret;
|
||||
ret = wc_SHE_Init_Id(&she, myId, sizeof(myId), NULL, myDevId);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_Init
|
||||
\sa wc_SHE_Init_Label
|
||||
\sa wc_SHE_Free
|
||||
*/
|
||||
int wc_SHE_Init_Id(wc_SHE* she, unsigned char* id, int len,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 人間が読める鍵ラベルを指定してSHEコンテキストを初期化します。暗号コールバックを使用し、スロットや鍵グループの情報を判別するためにSHEコンテキストへ追加情報を付加する必要がある場合に有用です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheまたはlabelがNULLの場合、あるいはlabelの長さがWC_SHE_MAX_LABEL_LENを超える場合に返されます
|
||||
|
||||
\param she 初期化するwc_SHE構造体へのポインタ
|
||||
\param label NUL終端された鍵ラベル文字列
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_SHE she;
|
||||
int ret;
|
||||
ret = wc_SHE_Init_Label(&she, "ecu-master-key", NULL, myDevId);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_Init
|
||||
\sa wc_SHE_Init_Id
|
||||
\sa wc_SHE_Free
|
||||
*/
|
||||
int wc_SHE_Init_Label(wc_SHE* she, const char* label,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief すべてのデータを消去し、SHEコンテキストをゼロクリアします。NULLポインタに対して呼び出しても安全です。
|
||||
|
||||
\param she wc_SHE構造体へのポインタ、またはNULL
|
||||
|
||||
_Example_
|
||||
\code
|
||||
wc_SHE she;
|
||||
wc_SHE_Init(&she, NULL, INVALID_DEVID);
|
||||
// ... コンテキストを使用 ...
|
||||
wc_SHE_Free(&she);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_Init
|
||||
*/
|
||||
void wc_SHE_Free(wc_SHE* she);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 暗号コールバックを介してハードウェアからUIDを取得します。WOLF_CRYPTO_CBが有効で、かつNO_WC_SHE_GETUIDが定義されていないことが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG she、uid、uidSzのいずれかが無効な場合に返されます
|
||||
\return CRYPTOCB_UNAVAILABLE コールバックが登録されていない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param uid 15バイト(120ビット)のSHE UIDを受け取るバッファ
|
||||
\param uidSz uidバッファのバイト単位のサイズ(WC_SHE_UID_SZ以上でなければなりません)
|
||||
\param ctx コールバックに渡される読み取り専用の呼び出し側コンテキスト(例: チャレンジバッファ、HSMハンドル)
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte uid[WC_SHE_UID_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_GetUID(&she, uid, sizeof(uid), NULL);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GetCounter
|
||||
*/
|
||||
int wc_SHE_GetUID(wc_SHE* she, byte* uid, word32 uidSz,
|
||||
const void* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 暗号コールバックを介してハードウェアから単調増加カウンタの値を取得します。SHE仕様では28ビットのカウンタを使用します。呼び出し側は、この値をGenerateM1M2M3またはGenerateM4M5に渡す前にインクリメントしてください。WOLF_CRYPTO_CBが有効で、かつNO_WC_SHE_GETCOUNTERが定義されていないことが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheまたはcounterがNULLの場合に返されます
|
||||
\return CRYPTOCB_UNAVAILABLE コールバックが登録されていない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param counter 現在のカウンタ値を受け取るポインタ
|
||||
\param ctx コールバックに渡される読み取り専用の呼び出し側コンテキスト
|
||||
|
||||
_Example_
|
||||
\code
|
||||
word32 counter;
|
||||
int ret;
|
||||
ret = wc_SHE_GetCounter(&she, &counter, NULL);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GetUID
|
||||
*/
|
||||
int wc_SHE_GetCounter(wc_SHE* she, word32* counter,
|
||||
const void* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief Miyaguchi-Preneel鍵導出で使用するKDF定数をカスタム値に設定します。デフォルト値はSHE仕様のKEY_UPDATE_ENC_CおよびKEY_UPDATE_MAC_Cです。どちらのポインタもNULLにでき、NULLを指定した側の定数は変更されません。WOLFSSL_SHE_EXTENDEDが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheがNULLの場合、または対応するポインタがNULLでないにもかかわらずサイズがWC_SHE_KEY_SZでない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param encC 16バイトの暗号化導出定数(CENC)、またはNULL
|
||||
\param encCSz encCがNULLでない場合はWC_SHE_KEY_SZ(16)でなければなりません
|
||||
\param macC 16バイトのMAC導出定数(CMAC)、またはNULL
|
||||
\param macCSz macCがNULLでない場合はWC_SHE_KEY_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte myEncC[WC_SHE_KEY_SZ] = { ... };
|
||||
byte myMacC[WC_SHE_KEY_SZ] = { ... };
|
||||
int ret;
|
||||
ret = wc_SHE_SetKdfConstants(&she, myEncC, WC_SHE_KEY_SZ,
|
||||
myMacC, WC_SHE_KEY_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_SetM2Header
|
||||
\sa wc_SHE_SetM4Header
|
||||
\sa wc_SHE_GenerateM1M2M3
|
||||
*/
|
||||
int wc_SHE_SetKdfConstants(wc_SHE* she,
|
||||
const byte* encC, word32 encCSz,
|
||||
const byte* macC, word32 macCSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief M2の平文ヘッダ(暗号化前のM2の先頭16バイト)を上書きします。設定すると、GenerateM1M2M3はカウンタとフラグから自動生成する代わりにこの値を使用します。WOLFSSL_SHE_EXTENDEDが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheまたはheaderがNULLの場合、あるいはheaderSzがWC_SHE_KEY_SZでない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param header 16バイトの平文ヘッダブロック
|
||||
\param headerSz WC_SHE_KEY_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte header[WC_SHE_KEY_SZ] = { ... };
|
||||
int ret;
|
||||
ret = wc_SHE_SetM2Header(&she, header, WC_SHE_KEY_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_SetKdfConstants
|
||||
\sa wc_SHE_SetM4Header
|
||||
\sa wc_SHE_GenerateM1M2M3
|
||||
*/
|
||||
int wc_SHE_SetM2Header(wc_SHE* she,
|
||||
const byte* header, word32 headerSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief M4の平文カウンタブロック(K3で暗号化される16バイトのブロック)を上書きします。設定すると、GenerateM4M5はカウンタから自動生成する代わりにこの値を使用します。WOLFSSL_SHE_EXTENDEDが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheまたはheaderがNULLの場合、あるいはheaderSzがWC_SHE_KEY_SZでない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param header 16バイトの平文カウンタブロック
|
||||
\param headerSz WC_SHE_KEY_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte header[WC_SHE_KEY_SZ] = { ... };
|
||||
int ret;
|
||||
ret = wc_SHE_SetM4Header(&she, header, WC_SHE_KEY_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_SetKdfConstants
|
||||
\sa wc_SHE_SetM2Header
|
||||
\sa wc_SHE_GenerateM4M5
|
||||
*/
|
||||
int wc_SHE_SetM4Header(wc_SHE* she,
|
||||
const byte* header, word32 headerSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 外部から提供されたM1/M2/M3をSHEコンテキストにインポートします。生成済みフラグが設定されるため、GenerateM4M5のコールバックはコンテキストからM1/M2/M3を読み取ってハードウェアへ送信できます。WOLF_CRYPTO_CBが有効で、かつNO_WC_SHE_IMPORT_M123が定義されていないことが必要です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheがNULLの場合、またはいずれかのメッセージサイズが正しくない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param m1 16バイトのM1メッセージ(UID | KeyID | AuthID)
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2メッセージ(暗号化されたcounter|flags|pad|newkey)
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3メッセージ(M1|M2に対するCMAC)
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
int ret;
|
||||
ret = wc_SHE_ImportM1M2M3(&she,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GenerateM1M2M3
|
||||
\sa wc_SHE_GenerateM4M5
|
||||
\sa wc_SHE_LoadKey
|
||||
*/
|
||||
int wc_SHE_ImportM1M2M3(wc_SHE* she,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief SHEの鍵更新メッセージM1、M2、M3を生成し、呼び出し側が用意したバッファへ書き込みます。認可鍵からK1とK2を導出するためにMiyaguchi-Preneel AES-128 KDFを、新しい鍵の暗号化(M2)にAES-CBCを、認証(M3)にAES-CMACを使用します。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param uid 15バイトのSHE UID(120ビットのECU/モジュール識別子)
|
||||
\param uidSz WC_SHE_UID_SZ(15)でなければなりません
|
||||
\param authKeyId 認可鍵のスロットID(0〜14)
|
||||
\param authKey 認可鍵の16バイトの値
|
||||
\param authKeySz WC_SHE_KEY_SZ(16)でなければなりません
|
||||
\param targetKeyId ロード対象の鍵のスロットID(1〜14)
|
||||
\param newKey ロードする新しい鍵の16バイトの値
|
||||
\param newKeySz WC_SHE_KEY_SZ(16)でなければなりません
|
||||
\param counter 28ビットの単調増加カウンタ値(対象スロットに格納されているカウンタより大きい値でなければなりません。同じ値は使用できません)
|
||||
\param flags 鍵保護フラグ(下位4ビット)
|
||||
\param m1 M1の出力バッファ(16バイト)
|
||||
\param m1Sz m1バッファのサイズ。WC_SHE_M1_SZ以上でなければなりません
|
||||
\param m2 M2の出力バッファ(32バイト)
|
||||
\param m2Sz m2バッファのサイズ。WC_SHE_M2_SZ以上でなければなりません
|
||||
\param m3 M3の出力バッファ(16バイト)
|
||||
\param m3Sz m3バッファのサイズ。WC_SHE_M3_SZ以上でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m1[WC_SHE_M1_SZ], m2[WC_SHE_M2_SZ], m3[WC_SHE_M3_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_GenerateM1M2M3(&she,
|
||||
uid, WC_SHE_UID_SZ,
|
||||
authKeyId, authKey, WC_SHE_KEY_SZ,
|
||||
targetKeyId, newKey, WC_SHE_KEY_SZ,
|
||||
counter, flags,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GenerateM4M5
|
||||
\sa wc_SHE_ImportM1M2M3
|
||||
\sa wc_SHE_LoadKey
|
||||
*/
|
||||
int wc_SHE_GenerateM1M2M3(wc_SHE* she,
|
||||
const byte* uid, word32 uidSz,
|
||||
byte authKeyId, const byte* authKey, word32 authKeySz,
|
||||
byte targetKeyId, const byte* newKey, word32 newKeySz,
|
||||
word32 counter, byte flags,
|
||||
byte* m1, word32 m1Sz,
|
||||
byte* m2, word32 m2Sz,
|
||||
byte* m3, word32 m3Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief SHEの検証メッセージM4とM5を生成し、呼び出し側が用意したバッファへ書き込みます。新しい鍵からK3とK4を導出するためにMiyaguchi-Preneel AES-128 KDFを、M4のカウンタブロックにAES-ECBを、M5にAES-CMACを使用します。M1/M2/M3とは独立しており、別のコンテキストで呼び出すこともできます。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param uid 15バイトのSHE UID(M1で使用したものと同じUID)
|
||||
\param uidSz WC_SHE_UID_SZ(15)でなければなりません
|
||||
\param authKeyId 認可鍵のスロットID(M1と同じ)
|
||||
\param targetKeyId ロード対象の鍵のスロットID(M1と同じ)
|
||||
\param newKey 新しい鍵の16バイトの値
|
||||
\param newKeySz WC_SHE_KEY_SZ(16)でなければなりません
|
||||
\param counter 28ビットの単調増加カウンタ(M2と同じ値)
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_GenerateM4M5(&she,
|
||||
uid, WC_SHE_UID_SZ,
|
||||
authKeyId, targetKeyId,
|
||||
newKey, WC_SHE_KEY_SZ,
|
||||
counter,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GenerateM1M2M3
|
||||
\sa wc_SHE_LoadKey_Verify
|
||||
*/
|
||||
int wc_SHE_GenerateM4M5(wc_SHE* she,
|
||||
const byte* uid, word32 uidSz,
|
||||
byte authKeyId, byte targetKeyId,
|
||||
const byte* newKey, word32 newKeySz,
|
||||
word32 counter,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief Init、ImportM1M2M3、GenerateM4M5(コールバック経由)、Freeを一括で行う便利なラッパーです。M1/M2/M3をHSMへ送信してM4/M5を受け取るハードウェア暗号コールバックにディスパッチします。有効なdevId(INVALID_DEVIDではない値)が必要です。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey(NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey_Id
|
||||
\sa wc_SHE_LoadKey_Label
|
||||
\sa wc_SHE_LoadKey_Verify
|
||||
\sa wc_SHE_ImportM1M2M3
|
||||
\sa wc_SHE_GenerateM4M5
|
||||
*/
|
||||
int wc_SHE_LoadKey(
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 不透明なハードウェア鍵識別子を指定して鍵ロードを一括で行います。wc_SHE_LoadKeyと同じですが、コンテキストの初期化にwc_SHE_Init_Idを使用します。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param id 不透明な鍵識別子のバイト列
|
||||
\param idLen idのバイト単位の長さ
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
unsigned char keyId[] = { 0x01, 0x02 };
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey_Id(keyId, sizeof(keyId), NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey
|
||||
\sa wc_SHE_LoadKey_Label
|
||||
\sa wc_SHE_LoadKey_Verify_Id
|
||||
*/
|
||||
int wc_SHE_LoadKey_Id(
|
||||
unsigned char* id, int idLen,
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 人間が読める鍵ラベルを指定して鍵ロードを一括で行います。wc_SHE_LoadKeyと同じですが、コンテキストの初期化にwc_SHE_Init_Labelを使用します。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param label NUL終端された鍵ラベル文字列
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey_Label("ecu-master", NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey
|
||||
\sa wc_SHE_LoadKey_Id
|
||||
\sa wc_SHE_LoadKey_Verify_Label
|
||||
*/
|
||||
int wc_SHE_LoadKey_Label(
|
||||
const char* label,
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief M4/M5の検証を伴う一括の鍵ロードです。wc_SHE_LoadKeyと同じですが、HSMが返したM4/M5を、呼び出し側が用意した期待値と一定時間で比較して照合します。不一致の場合はSIG_VERIFY_Eを返します。失敗した場合でも、実際のM4/M5は出力バッファへ書き込まれます。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return SIG_VERIFY_E M4/M5が期待値と一致しない場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
\param m4Expected 照合に使用するM4検証メッセージの期待値
|
||||
\param m4ExpectedSz WC_SHE_M4_SZ(32)でなければなりません
|
||||
\param m5Expected 照合に使用するM5検証メッセージの期待値
|
||||
\param m5ExpectedSz WC_SHE_M5_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey_Verify(NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ,
|
||||
expectedM4, WC_SHE_M4_SZ,
|
||||
expectedM5, WC_SHE_M5_SZ);
|
||||
if (ret == SIG_VERIFY_E) {
|
||||
// M4/M5の不一致
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey
|
||||
\sa wc_SHE_LoadKey_Verify_Id
|
||||
\sa wc_SHE_LoadKey_Verify_Label
|
||||
*/
|
||||
int wc_SHE_LoadKey_Verify(
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz,
|
||||
const byte* m4Expected, word32 m4ExpectedSz,
|
||||
const byte* m5Expected, word32 m5ExpectedSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 不透明な鍵識別子とM4/M5の検証を伴う一括の鍵ロードです。wc_SHE_LoadKey_Idとwc_SHE_LoadKey_Verifyを組み合わせたものです。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return SIG_VERIFY_E M4/M5が期待値と一致しない場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param id 不透明な鍵識別子のバイト列
|
||||
\param idLen idのバイト単位の長さ
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
\param m4Expected M4検証メッセージの期待値
|
||||
\param m4ExpectedSz WC_SHE_M4_SZ(32)でなければなりません
|
||||
\param m5Expected M5検証メッセージの期待値
|
||||
\param m5ExpectedSz WC_SHE_M5_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
unsigned char keyId[] = { 0x01, 0x02 };
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey_Verify_Id(keyId, sizeof(keyId), NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ, m2, WC_SHE_M2_SZ, m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ, m5, WC_SHE_M5_SZ,
|
||||
expectedM4, WC_SHE_M4_SZ, expectedM5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey_Id
|
||||
\sa wc_SHE_LoadKey_Verify
|
||||
\sa wc_SHE_LoadKey_Verify_Label
|
||||
*/
|
||||
int wc_SHE_LoadKey_Verify_Id(
|
||||
unsigned char* id, int idLen,
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz,
|
||||
const byte* m4Expected, word32 m4ExpectedSz,
|
||||
const byte* m5Expected, word32 m5ExpectedSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief 鍵ラベルとM4/M5の検証を伴う一括の鍵ロードです。wc_SHE_LoadKey_Labelとwc_SHE_LoadKey_Verifyを組み合わせたものです。コンパイル対象から除外するにはNO_WC_SHE_LOADKEYを定義してください。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return SIG_VERIFY_E M4/M5が期待値と一致しない場合に返されます
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合、またはサイズが正しくない場合に返されます
|
||||
|
||||
\param label NUL終端された鍵ラベル文字列
|
||||
\param heap 内部のメモリ確保に使用するヒープヒント、またはNULL
|
||||
\param devId 暗号コールバックのデバイスID(INVALID_DEVIDであってはなりません)
|
||||
\param m1 16バイトのM1入力メッセージ
|
||||
\param m1Sz WC_SHE_M1_SZ(16)でなければなりません
|
||||
\param m2 32バイトのM2入力メッセージ
|
||||
\param m2Sz WC_SHE_M2_SZ(32)でなければなりません
|
||||
\param m3 16バイトのM3入力メッセージ
|
||||
\param m3Sz WC_SHE_M3_SZ(16)でなければなりません
|
||||
\param m4 M4の出力バッファ(32バイト)
|
||||
\param m4Sz m4バッファのサイズ。WC_SHE_M4_SZ以上でなければなりません
|
||||
\param m5 M5の出力バッファ(16バイト)
|
||||
\param m5Sz m5バッファのサイズ。WC_SHE_M5_SZ以上でなければなりません
|
||||
\param m4Expected M4検証メッセージの期待値
|
||||
\param m4ExpectedSz WC_SHE_M4_SZ(32)でなければなりません
|
||||
\param m5Expected M5検証メッセージの期待値
|
||||
\param m5ExpectedSz WC_SHE_M5_SZ(16)でなければなりません
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_LoadKey_Verify_Label("ecu-master", NULL, myDevId,
|
||||
m1, WC_SHE_M1_SZ, m2, WC_SHE_M2_SZ, m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ, m5, WC_SHE_M5_SZ,
|
||||
expectedM4, WC_SHE_M4_SZ, expectedM5, WC_SHE_M5_SZ);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_LoadKey_Label
|
||||
\sa wc_SHE_LoadKey_Verify
|
||||
\sa wc_SHE_LoadKey_Verify_Id
|
||||
*/
|
||||
int wc_SHE_LoadKey_Verify_Label(
|
||||
const char* label,
|
||||
void* heap, int devId,
|
||||
const byte* m1, word32 m1Sz,
|
||||
const byte* m2, word32 m2Sz,
|
||||
const byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz,
|
||||
const byte* m4Expected, word32 m4ExpectedSz,
|
||||
const byte* m5Expected, word32 m5ExpectedSz);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief ハードウェアから鍵をSHEのロード可能な形式(M1〜M5)でエクスポートします。一部のHSMでは特定の鍵スロット(例: RAM鍵)のエクスポートが許可されており、後からSHEの鍵更新プロトコルで再ロードできます。WOLF_CRYPTO_CBが有効で、かつNO_WC_SHE_EXPORTKEYが定義されていないことが必要です。出力バッファはいずれもNULLにでき、その場合そのメッセージはスキップされます。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG sheがNULLの場合に返されます
|
||||
\return CRYPTOCB_UNAVAILABLE コールバックが登録されていない場合に返されます
|
||||
|
||||
\param she 初期化済みのSHEコンテキスト
|
||||
\param m1 M1の出力バッファ(16バイト)、スキップする場合はNULL
|
||||
\param m1Sz m1バッファのサイズ
|
||||
\param m2 M2の出力バッファ(32バイト)、スキップする場合はNULL
|
||||
\param m2Sz m2バッファのサイズ
|
||||
\param m3 M3の出力バッファ(16バイト)、スキップする場合はNULL
|
||||
\param m3Sz m3バッファのサイズ
|
||||
\param m4 M4の出力バッファ(32バイト)、スキップする場合はNULL
|
||||
\param m4Sz m4バッファのサイズ
|
||||
\param m5 M5の出力バッファ(16バイト)、スキップする場合はNULL
|
||||
\param m5Sz m5バッファのサイズ
|
||||
\param ctx コールバックに渡される読み取り専用の呼び出し側コンテキスト
|
||||
|
||||
_Example_
|
||||
\code
|
||||
byte m1[WC_SHE_M1_SZ], m2[WC_SHE_M2_SZ], m3[WC_SHE_M3_SZ];
|
||||
byte m4[WC_SHE_M4_SZ], m5[WC_SHE_M5_SZ];
|
||||
int ret;
|
||||
ret = wc_SHE_ExportKey(&she,
|
||||
m1, WC_SHE_M1_SZ,
|
||||
m2, WC_SHE_M2_SZ,
|
||||
m3, WC_SHE_M3_SZ,
|
||||
m4, WC_SHE_M4_SZ,
|
||||
m5, WC_SHE_M5_SZ,
|
||||
NULL);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_ImportM1M2M3
|
||||
\sa wc_SHE_LoadKey
|
||||
*/
|
||||
int wc_SHE_ExportKey(wc_SHE* she,
|
||||
byte* m1, word32 m1Sz,
|
||||
byte* m2, word32 m2Sz,
|
||||
byte* m3, word32 m3Sz,
|
||||
byte* m4, word32 m4Sz,
|
||||
byte* m5, word32 m5Sz,
|
||||
const void* ctx);
|
||||
|
||||
/*!
|
||||
\ingroup SHE
|
||||
\brief Miyaguchi-Preneel AES-128一方向圧縮関数です。H_0 = 0、H_i = E_{H_{i-1}}(M_i) XOR M_i XOR H_{i-1}。鍵サイズがブロックサイズと等しいAES-128でのみ使用できます。テスト目的で公開している内部関数です。
|
||||
|
||||
\return 0 成功した場合に返されます
|
||||
\return BAD_FUNC_ARG いずれかのポインタがNULLの場合に返されます
|
||||
|
||||
\param aes 呼び出し側が所有する初期化済みのAes構造体
|
||||
\param in 入力データ(例: BaseKey || KDF_Constant、32バイト)
|
||||
\param inSz 入力のバイト単位の長さ(ブロック境界までゼロパディングされます)
|
||||
\param out 16バイトの圧縮結果を受け取る出力バッファ
|
||||
|
||||
_Example_
|
||||
\code
|
||||
Aes aes;
|
||||
byte input[32] = { ... };
|
||||
byte output[WC_SHE_KEY_SZ];
|
||||
int ret;
|
||||
wc_AesInit(&aes, NULL, INVALID_DEVID);
|
||||
ret = wc_SHE_AesMp16(&aes, input, sizeof(input), output);
|
||||
wc_AesFree(&aes);
|
||||
\endcode
|
||||
|
||||
\sa wc_SHE_GenerateM1M2M3
|
||||
\sa wc_SHE_GenerateM4M5
|
||||
*/
|
||||
int wc_SHE_AesMp16(Aes* aes, const byte* in, word32 inSz,
|
||||
byte* out);
|
||||
@@ -0,0 +1,951 @@
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 指定されたパラメータセットでSLH-DSA鍵オブジェクトを初期化します。他のSLH-DSA操作を行う前に呼び出さなければなりません。使用が終わったらwc_SlhDsaKey_Free()でリソースを解放してください。
|
||||
|
||||
SLH-DSA(FIPS 205)は状態を持たないハッシュベースのデジタル署名アルゴリズムです。パラメータセットによって、ハッシュ関数(SHAKEまたはSHA2)、セキュリティレベル(128、192、256)、速度とサイズのトレードオフ(s = 署名が小さい、f = 署名が高速)が決まります。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはparamが無効な場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するSlhDsaKeyへのポインタ。
|
||||
\param [in] param 使用するパラメータセット。次のいずれか: SLHDSA_SHAKE128S、SLHDSA_SHAKE128F、SLHDSA_SHAKE192S、SLHDSA_SHAKE192F、SLHDSA_SHAKE256S、SLHDSA_SHAKE256F、SLHDSA_SHA2_128S、SLHDSA_SHA2_128F、SLHDSA_SHA2_192S、SLHDSA_SHA2_192F、SLHDSA_SHA2_256S、SLHDSA_SHA2_256F。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒントへのポインタ。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
if (ret != 0) {
|
||||
// 鍵の初期化エラー
|
||||
}
|
||||
// ... 鍵を使用 ...
|
||||
wc_SlhDsaKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Free
|
||||
\sa wc_SlhDsaKey_MakeKey
|
||||
*/
|
||||
int wc_SlhDsaKey_Init(SlhDsaKey* key, enum SlhDsaParam param,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief デバイス側の鍵識別子(id)を指定してSLH-DSA鍵を初期化します。wc_SlhDsaKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるバイナリ形式のidも保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
idは鍵オブジェクトへコピーされます。呼び出し側はこの関数から戻った直後に自身のバッファを解放して構いません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはlenが0より大きいにもかかわらずidがNULLの場合に返されます。
|
||||
\return BUFFER_E lenが負の場合、またはSLHDSA_MAX_ID_LENより大きい場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するSlhDsaKeyへのポインタ。
|
||||
\param [in] param 使用するパラメータセット(wc_SlhDsaKey_Initを参照)。
|
||||
\param [in] id デバイス側の鍵識別子バイト列へのポインタ。lenが0の場合はNULLでも構いません。
|
||||
\param [in] len idのバイト数。[0, SLHDSA_MAX_ID_LEN]の範囲内でなければなりません。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒントへのポインタ。NULLでも構いません。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。idが意味を持つためには、INVALID_DEVIDではなく登録済みのコールバックのdevIdを指定してください。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
unsigned char id[8] = { 0x01, 0x02, 0x03, 0x04,
|
||||
0x05, 0x06, 0x07, 0x08 };
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_Init_id(&key, SLHDSA_SHAKE128F, id, sizeof(id),
|
||||
NULL, devId);
|
||||
if (ret != 0) {
|
||||
// idを指定した鍵の初期化エラー
|
||||
}
|
||||
// ... 鍵を使用。コールバックがid -> デバイス鍵を解決します ...
|
||||
wc_SlhDsaKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Init
|
||||
\sa wc_SlhDsaKey_Init_label
|
||||
\sa wc_SlhDsaKey_Free
|
||||
*/
|
||||
int wc_SlhDsaKey_Init_id(SlhDsaKey* key, enum SlhDsaParam param,
|
||||
const unsigned char* id, int len, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief デバイス側の鍵ラベルを指定してSLH-DSA鍵を初期化します。wc_SlhDsaKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるラベル文字列も保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
ラベルの長さはXSTRLENで取得されるため、途中にNULバイトが含まれるとそこでラベルが終端します。key->labelに保存されるコピーはNUL終端されているとは保証されません(入力がちょうどSLHDSA_MAX_LABEL_LENバイトの場合、配列全体が使用されます)。呼び出し側が読み取ってよいのは最大でkey->labelLenバイトまでです。key->labelをC文字列APIに渡してはいけません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlabelがNULLの場合に返されます。
|
||||
\return BUFFER_E labelが空の場合、またはSLHDSA_MAX_LABEL_LENより長い場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するSlhDsaKeyへのポインタ。
|
||||
\param [in] param 使用するパラメータセット(wc_SlhDsaKey_Initを参照)。
|
||||
\param [in] label NUL終端されたデバイス側の鍵ラベル文字列。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒントへのポインタ。NULLでも構いません。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。labelが意味を持つためには、INVALID_DEVIDではなく登録済みのコールバックのdevIdを指定してください。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_Init_label(&key, SLHDSA_SHAKE128F,
|
||||
"device-key-1", NULL, devId);
|
||||
if (ret != 0) {
|
||||
// labelを指定した鍵の初期化エラー
|
||||
}
|
||||
// ... 鍵を使用。コールバックがlabel -> デバイス鍵を解決します ...
|
||||
wc_SlhDsaKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Init
|
||||
\sa wc_SlhDsaKey_Init_id
|
||||
\sa wc_SlhDsaKey_Free
|
||||
*/
|
||||
int wc_SlhDsaKey_Init_label(SlhDsaKey* key, enum SlhDsaParam param,
|
||||
const char* label, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA鍵オブジェクトに関連付けられたリソースを解放します。
|
||||
|
||||
\param [in,out] key 解放するSlhDsaKeyへのポインタ。NULLでも構いません。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
// ... 鍵を使用 ...
|
||||
wc_SlhDsaKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Init
|
||||
*/
|
||||
void wc_SlhDsaKey_Free(SlhDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief RNGを乱数源として使用し、新しいSLH-DSA鍵ペアを生成します。鍵は事前にwc_SlhDsaKey_Init()で初期化されていなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはrngがNULLの場合、あるいはkeyが初期化されていない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
WC_RNG rng;
|
||||
int ret;
|
||||
|
||||
wc_InitRng(&rng);
|
||||
wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
ret = wc_SlhDsaKey_MakeKey(&key, &rng);
|
||||
if (ret != 0) {
|
||||
// 鍵の生成エラー
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Init
|
||||
\sa wc_SlhDsaKey_MakeKeyWithRandom
|
||||
*/
|
||||
int wc_SlhDsaKey_MakeKey(SlhDsaKey* key, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 呼び出し側が提供したシード素材からSLH-DSA鍵ペアを生成します。これは決定的な鍵生成インターフェースであり、同じシードを与えれば同じ鍵ペアが生成されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはいずれかのシードポインタがNULLの場合、あるいは長さがパラメータセットのn値と一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
\param [in] sk_seed 秘密鍵のシード(nバイト)。
|
||||
\param [in] sk_seed_len sk_seedの長さ。
|
||||
\param [in] sk_prf 秘密鍵のPRFシード(nバイト)。
|
||||
\param [in] sk_prf_len sk_prfの長さ。
|
||||
\param [in] pk_seed 公開鍵のシード(nバイト)。
|
||||
\param [in] pk_seed_len pk_seedの長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sk_seed[16], sk_prf[16], pk_seed[16]; // 128ビットパラメータではn=16
|
||||
int ret;
|
||||
|
||||
// シードに既知の値を設定します(例: NISTテストベクタから)
|
||||
wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
ret = wc_SlhDsaKey_MakeKeyWithRandom(&key,
|
||||
sk_seed, sizeof(sk_seed),
|
||||
sk_prf, sizeof(sk_prf),
|
||||
pk_seed, sizeof(pk_seed));
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_MakeKey
|
||||
*/
|
||||
int wc_SlhDsaKey_MakeKeyWithRandom(SlhDsaKey* key,
|
||||
const byte* sk_seed, word32 sk_seed_len,
|
||||
const byte* sk_prf, word32 sk_prf_len,
|
||||
const byte* pk_seed, word32 pk_seed_len);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSAの外部(pure)インターフェースを使用し、決定的な乱数でメッセージに署名します。これはopt_randをPK.seedに設定したFIPS 205のアルゴリズム22に相当します。メッセージMは署名前に内部でM' = 0x00 || len(ctx) || ctx || Mとしてラップされます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、msg、sig、sigSzのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E 出力バッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx ドメイン分離のためのコンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] msg 署名するメッセージへのポインタ。
|
||||
\param [in] msgSz メッセージの長さ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte msg[] = "Hello World!";
|
||||
int ret;
|
||||
|
||||
// 鍵はwc_SlhDsaKey_MakeKey()で生成済み
|
||||
ret = wc_SlhDsaKey_SignDeterministic(&key, NULL, 0,
|
||||
msg, sizeof(msg), sig, &sigSz);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignWithRandom
|
||||
\sa wc_SlhDsaKey_Sign
|
||||
\sa wc_SlhDsaKey_Verify
|
||||
*/
|
||||
int wc_SlhDsaKey_SignDeterministic(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* msg, word32 msgSz, byte* sig, word32* sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSAの外部(pure)インターフェースを使用し、呼び出し側が提供した追加の乱数でメッセージに署名します。これはopt_rand値を明示的に指定したFIPS 205のアルゴリズム22に相当します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、msg、sig、sigSz、addRndのいずれかがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] msg 署名するメッセージへのポインタ。
|
||||
\param [in] msgSz メッセージの長さ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
\param [in] addRnd 追加の乱数(nバイト。nはパラメータセットのセキュリティパラメータ)。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte msg[] = "Hello World!";
|
||||
byte addRnd[16]; // 128ビットパラメータではn=16
|
||||
int ret;
|
||||
|
||||
wc_RNG_GenerateBlock(&rng, addRnd, sizeof(addRnd));
|
||||
ret = wc_SlhDsaKey_SignWithRandom(&key, NULL, 0,
|
||||
msg, sizeof(msg), sig, &sigSz, addRnd);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignDeterministic
|
||||
\sa wc_SlhDsaKey_Sign
|
||||
*/
|
||||
int wc_SlhDsaKey_SignWithRandom(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* msg, word32 msgSz, byte* sig, word32* sigSz,
|
||||
const byte* addRnd);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSAの外部(pure)インターフェースを使用し、RNGが提供する乱数でメッセージに署名します。これはopt_randにWC_RNGを使用する汎用の署名関数です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、msg、sig、sigSz、rngのいずれかがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] msg 署名するメッセージへのポインタ。
|
||||
\param [in] msgSz メッセージの長さ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
WC_RNG rng;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte msg[] = "Hello World!";
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_Sign(&key, NULL, 0,
|
||||
msg, sizeof(msg), sig, &sigSz, &rng);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignDeterministic
|
||||
\sa wc_SlhDsaKey_Verify
|
||||
*/
|
||||
int wc_SlhDsaKey_Sign(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* msg, word32 msgSz, byte* sig, word32* sigSz,
|
||||
WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 外部(pure)インターフェースを使用して、メッセージに対するSLH-DSA署名を検証します。これはFIPS 205のアルゴリズム24に相当します。メッセージは検証前に内部でM' = 0x00 || len(ctx) || ctx || Mとしてラップされます。
|
||||
|
||||
\return 0 成功した場合(署名が有効)に返されます。
|
||||
\return BAD_FUNC_ARG key、msg、sigのいずれかがNULLの場合、またはctxがNULLでctxSzが0より大きい場合に返されます。
|
||||
\return BAD_LENGTH_E sigSzがパラメータセットの署名長と一致しない場合に返されます。
|
||||
\return MISSING_KEY 公開鍵が設定されていない場合に返されます。
|
||||
\return SIG_VERIFY_E 署名が無効な場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] msg 検証するメッセージへのポインタ。
|
||||
\param [in] msgSz メッセージの長さ。
|
||||
\param [in] sig 検証する署名へのポインタ。
|
||||
\param [in] sigSz 署名の長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[...]; // 以前に生成した署名
|
||||
word32 sigSz;
|
||||
byte msg[] = "Hello World!";
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_Verify(&key, NULL, 0,
|
||||
msg, sizeof(msg), sig, sigSz);
|
||||
if (ret == 0) {
|
||||
// 署名は有効です
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_Sign
|
||||
\sa wc_SlhDsaKey_SignDeterministic
|
||||
*/
|
||||
int wc_SlhDsaKey_Verify(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* msg, word32 msgSz, const byte* sig,
|
||||
word32 sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSAの内部インターフェースを使用し、決定的な乱数で署名します。外部インターフェースと異なり、M'は呼び出し側が直接提供し、ラップ処理は行われません。これはopt_randをPK.seedに設定したFIPS 205のアルゴリズム19(slh_sign_internal)に相当します。
|
||||
|
||||
ACVPのsignatureInterface=internalテストフレームワークやプロトコル層が既にM'を構築している場合に使用してください。HashSLH-DSAの場合、呼び出し側はM'を0x01 || ctxSz || ctx || OID(hashType) || PHMとして構築してここに渡します。ここでPHMはhashTypeによるアプリケーションメッセージのハッシュです。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、mprime、sig、sigSzのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E sigSzがパラメータセットの署名長より小さい場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] mprime 事前に構築されたM'メッセージへのポインタ。
|
||||
\param [in] mprimeSz M'の長さ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte mprime[] = { ... }; // 事前に構築したM'
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_SignMsgDeterministic(&key,
|
||||
mprime, sizeof(mprime), sig, &sigSz);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignMsgWithRandom
|
||||
\sa wc_SlhDsaKey_VerifyMsg
|
||||
\sa wc_SlhDsaKey_SignDeterministic
|
||||
\sa wc_SlhDsaKey_SignHashDeterministic
|
||||
*/
|
||||
int wc_SlhDsaKey_SignMsgDeterministic(SlhDsaKey* key,
|
||||
const byte* mprime, word32 mprimeSz, byte* sig, word32* sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSAの内部インターフェースを使用し、呼び出し側が提供した追加の乱数で署名します。M'は直接提供され、ラップ処理は行われません。これはopt_rand値を明示的に指定したFIPS 205のアルゴリズム19(slh_sign_internal)に相当します。HashSLH-DSAで使用するM'のレイアウトについてはwc_SlhDsaKey_SignMsgDeterministicを参照してください。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、mprime、sig、sigSz、addRndのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E sigSzがパラメータセットの署名長より小さい場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] mprime 事前に構築されたM'メッセージへのポインタ。
|
||||
\param [in] mprimeSz M'の長さ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
\param [in] addRnd 追加の乱数(nバイト)。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte mprime[] = { ... };
|
||||
byte addRnd[16];
|
||||
int ret;
|
||||
|
||||
wc_RNG_GenerateBlock(&rng, addRnd, sizeof(addRnd));
|
||||
ret = wc_SlhDsaKey_SignMsgWithRandom(&key,
|
||||
mprime, sizeof(mprime), sig, &sigSz, addRnd);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignMsgDeterministic
|
||||
\sa wc_SlhDsaKey_VerifyMsg
|
||||
\sa wc_SlhDsaKey_SignHashWithRandom
|
||||
*/
|
||||
int wc_SlhDsaKey_SignMsgWithRandom(SlhDsaKey* key,
|
||||
const byte* mprime, word32 mprimeSz, byte* sig, word32* sigSz,
|
||||
const byte* addRnd);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 内部インターフェースを使用してSLH-DSA署名を検証します。M'は直接提供され、ラップ処理は行われません。これはFIPS 205のアルゴリズム20(slh_verify_internal)に相当します。
|
||||
|
||||
\return 0 成功した場合(署名が有効)に返されます。
|
||||
\return BAD_FUNC_ARG key、mprime、sigのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E sigSzがパラメータセットの署名長と一致しない場合に返されます。
|
||||
\return MISSING_KEY 公開鍵が設定されていない場合に返されます。
|
||||
\return SIG_VERIFY_E 署名が無効な場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] mprime 事前に構築されたM'メッセージへのポインタ。
|
||||
\param [in] mprimeSz M'の長さ。
|
||||
\param [in] sig 検証する署名へのポインタ。
|
||||
\param [in] sigSz 署名の長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[...]; // 以前に生成した署名
|
||||
word32 sigSz;
|
||||
byte mprime[] = { ... };
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_VerifyMsg(&key,
|
||||
mprime, sizeof(mprime), sig, sigSz);
|
||||
if (ret == 0) {
|
||||
// 署名は有効です
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignMsgDeterministic
|
||||
\sa wc_SlhDsaKey_Verify
|
||||
\sa wc_SlhDsaKey_VerifyHash
|
||||
*/
|
||||
int wc_SlhDsaKey_VerifyMsg(SlhDsaKey* key, const byte* mprime,
|
||||
word32 mprimeSz, const byte* sig, word32 sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 呼び出し側が事前にハッシュしたメッセージダイジェストに対して、SLH-DSAの外部(HashSLH-DSA)インターフェースを使用し、決定的な乱数で署名します。事前ハッシュのドメイン分離子(0x01)を用いたFIPS 205のアルゴリズム23に従います。呼び出し側が先にhashTypeでアプリケーションメッセージをハッシュし、そのダイジェストをhashとして渡さなければなりません。この関数は入力をハッシュしません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、hash、sig、sigSzのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E hashSzがhashTypeのダイジェストサイズと一致しない場合に返されます(FIPS 205セクション10.2.2に従い、SHAKE128では32、SHAKE256では64)。
|
||||
\return NOT_COMPILED_IN hashTypeがこのビルドでサポートされていない場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] hash 事前にハッシュしたメッセージダイジェストへのポインタ。hashSzはhashTypeのダイジェストサイズと一致しなければなりません。
|
||||
\param [in] hashSz ダイジェストのバイト単位の長さ。
|
||||
\param [in] hashType 事前ハッシュに使用したハッシュアルゴリズム(OIDを選択します)。サポート: WC_HASH_TYPE_SHA224、WC_HASH_TYPE_SHA256、WC_HASH_TYPE_SHA384、WC_HASH_TYPE_SHA512、WC_HASH_TYPE_SHA512_224、WC_HASH_TYPE_SHA512_256、WC_HASH_TYPE_SHAKE128、WC_HASH_TYPE_SHAKE256、WC_HASH_TYPE_SHA3_224、WC_HASH_TYPE_SHA3_256、WC_HASH_TYPE_SHA3_384、WC_HASH_TYPE_SHA3_512。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[WC_SLHDSA_MAX_SIG_LEN];
|
||||
word32 sigSz = sizeof(sig);
|
||||
byte msg[] = "Hello World!";
|
||||
byte digest[WC_SHA256_DIGEST_SIZE];
|
||||
int ret;
|
||||
|
||||
wc_Sha256Hash(msg, sizeof(msg), digest);
|
||||
ret = wc_SlhDsaKey_SignHashDeterministic(&key, NULL, 0,
|
||||
digest, sizeof(digest), WC_HASH_TYPE_SHA256, sig, &sigSz);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignHashWithRandom
|
||||
\sa wc_SlhDsaKey_SignHash
|
||||
\sa wc_SlhDsaKey_VerifyHash
|
||||
\sa wc_SlhDsaKey_SignMsgDeterministic
|
||||
*/
|
||||
int wc_SlhDsaKey_SignHashDeterministic(SlhDsaKey* key,
|
||||
const byte* ctx, byte ctxSz, const byte* hash, word32 hashSz,
|
||||
enum wc_HashType hashType, byte* sig, word32* sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 呼び出し側が事前にハッシュしたメッセージダイジェストに対して、SLH-DSAの外部(HashSLH-DSA)インターフェースを使用し、呼び出し側が提供した追加の乱数で署名します。呼び出し側が先にhashTypeでアプリケーションメッセージをハッシュし、そのダイジェストをhashとして渡さなければなりません。この関数は入力をハッシュしません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、hash、sig、sigSz、addRndのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E hashSzがhashTypeのダイジェストサイズと一致しない場合に返されます(FIPS 205セクション10.2.2に従い、SHAKE128では32、SHAKE256では64)。
|
||||
\return NOT_COMPILED_IN hashTypeがこのビルドでサポートされていない場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] hash 事前にハッシュしたメッセージダイジェストへのポインタ。hashSzはhashTypeのダイジェストサイズと一致しなければなりません。
|
||||
\param [in] hashSz ダイジェストのバイト単位の長さ。
|
||||
\param [in] hashType 事前ハッシュに使用したハッシュアルゴリズム(OIDを選択します)。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
\param [in] addRnd 追加の乱数(nバイト)。
|
||||
|
||||
\sa wc_SlhDsaKey_SignHashDeterministic
|
||||
\sa wc_SlhDsaKey_VerifyHash
|
||||
\sa wc_SlhDsaKey_SignMsgWithRandom
|
||||
*/
|
||||
int wc_SlhDsaKey_SignHashWithRandom(SlhDsaKey* key,
|
||||
const byte* ctx, byte ctxSz, const byte* hash, word32 hashSz,
|
||||
enum wc_HashType hashType, byte* sig, word32* sigSz, const byte* addRnd);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 呼び出し側が事前にハッシュしたメッセージダイジェストに対して、SLH-DSAの外部(HashSLH-DSA)インターフェースを使用し、RNGが提供する乱数で署名します。呼び出し側が先にhashTypeでアプリケーションメッセージをハッシュし、そのダイジェストをhashとして渡さなければなりません。この関数は入力をハッシュしません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、hash、sig、sigSz、rngのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E hashSzがhashTypeのダイジェストサイズと一致しない場合に返されます(FIPS 205セクション10.2.2に従い、SHAKE128では32、SHAKE256では64)。
|
||||
\return NOT_COMPILED_IN hashTypeがこのビルドでサポートされていない場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] hash 事前にハッシュしたメッセージダイジェストへのポインタ。hashSzはhashTypeのダイジェストサイズと一致しなければなりません。
|
||||
\param [in] hashSz ダイジェストのバイト単位の長さ。
|
||||
\param [in] hashType 事前ハッシュに使用したハッシュアルゴリズム(OIDを選択します)。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時はsigバッファのサイズ。出力時は実際の署名長。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
\sa wc_SlhDsaKey_SignHashDeterministic
|
||||
\sa wc_SlhDsaKey_VerifyHash
|
||||
\sa wc_SlhDsaKey_SignMsgDeterministic
|
||||
*/
|
||||
int wc_SlhDsaKey_SignHash(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* hash, word32 hashSz, enum wc_HashType hashType,
|
||||
byte* sig, word32* sigSz, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 外部のHashSLH-DSAインターフェース(FIPS 205のアルゴリズム25)を使用してSLH-DSA署名を検証します。呼び出し側が先にhashTypeでアプリケーションメッセージをハッシュし、そのダイジェストをhashとして渡さなければなりません。この関数は入力をハッシュしません。
|
||||
|
||||
\return 0 成功した場合(署名が有効)に返されます。
|
||||
\return BAD_FUNC_ARG key、hash、sigのいずれかがNULLの場合に返されます。
|
||||
\return BAD_LENGTH_E sigSzがパラメータセットと一致しない場合、またはhashSzがhashTypeのダイジェストサイズと一致しない場合に返されます(FIPS 205セクション10.2.2に従い、SHAKE128では32、SHAKE256では64)。
|
||||
\return NOT_COMPILED_IN hashTypeがこのビルドでサポートされていない場合に返されます。
|
||||
\return MISSING_KEY 公開鍵が設定されていない場合に返されます。
|
||||
\return SIG_VERIFY_E 署名が無効な場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [in] ctx コンテキスト文字列。ctxSzが0の場合はNULLでも構いません。
|
||||
\param [in] ctxSz コンテキスト文字列の長さ(0〜255)。
|
||||
\param [in] hash 事前にハッシュしたメッセージダイジェストへのポインタ。hashSzはhashTypeのダイジェストサイズと一致しなければなりません。
|
||||
\param [in] hashSz ダイジェストのバイト単位の長さ。
|
||||
\param [in] hashType 事前ハッシュに使用したハッシュアルゴリズム(OIDを選択します)。署名時に使用したハッシュと一致しなければなりません。
|
||||
\param [in] sig 検証する署名へのポインタ。
|
||||
\param [in] sigSz 署名の長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte sig[...];
|
||||
word32 sigSz;
|
||||
byte msg[] = "Hello World!";
|
||||
byte digest[WC_SHA256_DIGEST_SIZE];
|
||||
int ret;
|
||||
|
||||
wc_Sha256Hash(msg, sizeof(msg), digest);
|
||||
ret = wc_SlhDsaKey_VerifyHash(&key, NULL, 0,
|
||||
digest, sizeof(digest), WC_HASH_TYPE_SHA256, sig, sigSz);
|
||||
if (ret == 0) {
|
||||
// 署名は有効です
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_SignHashDeterministic
|
||||
\sa wc_SlhDsaKey_Verify
|
||||
\sa wc_SlhDsaKey_VerifyMsg
|
||||
*/
|
||||
int wc_SlhDsaKey_VerifyHash(SlhDsaKey* key, const byte* ctx,
|
||||
byte ctxSz, const byte* hash, word32 hashSz, enum wc_HashType hashType,
|
||||
const byte* sig, word32 sigSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 生のバイトバッファからSLH-DSA秘密鍵をインポートします。バッファには秘密鍵全体(4*nバイト: SK.seed || SK.prf || PK.seed || PK.root)が含まれていなければなりません。インポート後、その鍵は署名に使用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはinがNULLの場合、あるいはinLenがパラメータセットで期待される秘密鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
\param [in] in 生の秘密鍵バイト列を含むバッファ。
|
||||
\param [in] inLen 入力バッファの長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte privKey[...]; // 4*nバイト
|
||||
int ret;
|
||||
|
||||
wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
ret = wc_SlhDsaKey_ImportPrivate(&key, privKey, sizeof(privKey));
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_ExportPrivate
|
||||
\sa wc_SlhDsaKey_ImportPublic
|
||||
*/
|
||||
int wc_SlhDsaKey_ImportPrivate(SlhDsaKey* key, const byte* in,
|
||||
word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 生のバイトバッファからSLH-DSA公開鍵をインポートします。バッファにはPK.seed || PK.root(2*nバイト)が含まれていなければなりません。インポート後、その鍵は検証に使用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはinがNULLの場合、あるいはinLenが期待される公開鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列を含むバッファ。
|
||||
\param [in] inLen 入力バッファの長さ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte pubKey[...]; // 2*nバイト
|
||||
int ret;
|
||||
|
||||
wc_SlhDsaKey_Init(&key, SLHDSA_SHAKE128F, NULL, INVALID_DEVID);
|
||||
ret = wc_SlhDsaKey_ImportPublic(&key, pubKey, sizeof(pubKey));
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_ExportPublic
|
||||
\sa wc_SlhDsaKey_ImportPrivate
|
||||
*/
|
||||
int wc_SlhDsaKey_ImportPublic(SlhDsaKey* key, const byte* in,
|
||||
word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA鍵の整合性を検査します。秘密鍵と公開鍵の両方の要素を持つ鍵に対して、公開鍵が秘密鍵と一致することを検証します。
|
||||
|
||||
\return 0 成功した場合(鍵が有効)に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in] key 検査するSlhDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_SlhDsaKey_MakeKey
|
||||
\sa wc_SlhDsaKey_ImportPrivate
|
||||
*/
|
||||
int wc_SlhDsaKey_CheckKey(SlhDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA鍵オブジェクトから秘密鍵を生のバイトバッファ(4*nバイト)にエクスポートします。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、out、outLenのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E 出力バッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [out] out 生の秘密鍵バイト列を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時はoutバッファのサイズ。出力時は書き込まれたバイト数。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte privKey[4 * 32]; // 256ビットパラメータでは4*n
|
||||
word32 privKeySz = sizeof(privKey);
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_ExportPrivate(&key, privKey, &privKeySz);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_ImportPrivate
|
||||
\sa wc_SlhDsaKey_ExportPublic
|
||||
*/
|
||||
int wc_SlhDsaKey_ExportPrivate(SlhDsaKey* key, byte* out,
|
||||
word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA鍵オブジェクトから公開鍵を生のバイトバッファ(2*nバイト: PK.seed || PK.root)にエクスポートします。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG key、out、outLenのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E 出力バッファが小さすぎる場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵を保持するSlhDsaKeyへのポインタ。
|
||||
\param [out] out 生の公開鍵バイト列を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時はoutバッファのサイズ。出力時は書き込まれたバイト数。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
SlhDsaKey key;
|
||||
byte pubKey[2 * 32];
|
||||
word32 pubKeySz = sizeof(pubKey);
|
||||
int ret;
|
||||
|
||||
ret = wc_SlhDsaKey_ExportPublic(&key, pubKey, &pubKeySz);
|
||||
\endcode
|
||||
|
||||
\sa wc_SlhDsaKey_ImportPublic
|
||||
\sa wc_SlhDsaKey_ExportPrivate
|
||||
*/
|
||||
int wc_SlhDsaKey_ExportPublic(SlhDsaKey* key, byte* out,
|
||||
word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief この鍵のパラメータセットにおける秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、秘密鍵のサイズ(4*nバイト)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、または初期化されていない場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_SlhDsaKey_PublicSize
|
||||
\sa wc_SlhDsaKey_SigSize
|
||||
\sa wc_SlhDsaKey_PrivateSizeFromParam
|
||||
*/
|
||||
int wc_SlhDsaKey_PrivateSize(SlhDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief この鍵のパラメータセットにおける公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、公開鍵のサイズ(2*nバイト)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、または初期化されていない場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_SlhDsaKey_PrivateSize
|
||||
\sa wc_SlhDsaKey_SigSize
|
||||
\sa wc_SlhDsaKey_PublicSizeFromParam
|
||||
*/
|
||||
int wc_SlhDsaKey_PublicSize(SlhDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief この鍵のパラメータセットにおける署名のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、署名のサイズ(バイト単位)を返します。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、または初期化されていない場合に返されます。
|
||||
|
||||
\param [in] key 初期化済みのSlhDsaKeyへのポインタ。
|
||||
|
||||
\sa wc_SlhDsaKey_PrivateSize
|
||||
\sa wc_SlhDsaKey_PublicSize
|
||||
\sa wc_SlhDsaKey_SigSizeFromParam
|
||||
*/
|
||||
int wc_SlhDsaKey_SigSize(SlhDsaKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 初期化済みの鍵オブジェクトを必要とせずに、指定されたパラメータセットにおける秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、秘密鍵のサイズ(4*nバイト)を返します。
|
||||
\return BAD_FUNC_ARG paramが無効な場合に返されます。
|
||||
|
||||
\param [in] param SLH-DSAのパラメータセット。
|
||||
|
||||
\sa wc_SlhDsaKey_PrivateSize
|
||||
*/
|
||||
int wc_SlhDsaKey_PrivateSizeFromParam(enum SlhDsaParam param);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 初期化済みの鍵オブジェクトを必要とせずに、指定されたパラメータセットにおける公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、公開鍵のサイズ(2*nバイト)を返します。
|
||||
\return BAD_FUNC_ARG paramが無効な場合に返されます。
|
||||
|
||||
\param [in] param SLH-DSAのパラメータセット。
|
||||
|
||||
\sa wc_SlhDsaKey_PublicSize
|
||||
*/
|
||||
int wc_SlhDsaKey_PublicSizeFromParam(enum SlhDsaParam param);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief 初期化済みの鍵オブジェクトを必要とせずに、指定されたパラメータセットにおける署名のサイズをバイト単位で返します。
|
||||
|
||||
\return 成功した場合、署名のサイズ(バイト単位)を返します。
|
||||
\return BAD_FUNC_ARG paramが無効な場合に返されます。
|
||||
|
||||
\param [in] param SLH-DSAのパラメータセット。
|
||||
|
||||
\sa wc_SlhDsaKey_SigSize
|
||||
*/
|
||||
int wc_SlhDsaKey_SigSizeFromParam(enum SlhDsaParam param);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief RFC 9909で定義されたPKCS#8 OneAsymmetricKey形式のDERエンコードされたSLH-DSA秘密鍵をデコードします。privateKey OCTET STRINGには、Ed25519/Ed448で使われるような入れ子のOCTET STRINGラッパーを介さず、生の連結SK.seed || SK.prf || PK.seed || PK.root(4*nバイト)が直接格納されます。SLH-DSAのパラメータセットはAlgorithmIdentifierのOIDから検出され、key->paramsがそれに合わせて更新されます。WOLFSSL_SLHDSA_VERIFY_ONLYが定義されていない場合にのみ利用できます。
|
||||
|
||||
key->skへの書き込みが行われる前に検出された失敗(BAD_FUNC_ARG、ヘッダ/OIDの解析エラー、privateKeyの長さの誤り)では、鍵の状態は変更されません。wc_SlhDsaKey_ImportPrivateがkey->skを設定した後に検出された失敗(SHA-2の事前計算エラー、末尾フィールドの検証エラー)では、key->skはForceZeroで消去され、WC_SLHDSA_FLAG_PRIVATE/PUBLICフラグがクリアされます。これにより、ゼロクリアされたバイト列が有効な鍵としてフラグ付けされたまま残ることはありません。いずれのロールバックの場合も、key->paramsとinOutIdxは呼び出し前の値に復元されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG input、inOutIdx、keyのいずれかがNULLの場合、またはinSzが0の場合に返されます。
|
||||
\return ASN_PARSE_E DERをSLH-DSA秘密鍵として解析できない場合に返されます(入力の形式不正、鍵サイズの誤り、末尾フィールド違反)。
|
||||
\return NOT_COMPILED_IN OIDが、このライブラリに組み込まれていないSLH-DSAのバリアントを指している場合に返されます。
|
||||
|
||||
\param [in] input DERエンコードされた鍵データ。
|
||||
\param [in,out] inOutIdx 入力時はinput内の開始オフセット。出力時は解析した鍵の直後まで進みます(失敗時は変更されません)。
|
||||
\param [in,out] key SLH-DSA鍵。パラメータセットはエンコードされたOIDから自動検出されます。
|
||||
\param [in] inSz inputの全体サイズ(バイト単位)。
|
||||
|
||||
\sa wc_SlhDsaKey_KeyToDer
|
||||
\sa wc_SlhDsaKey_PublicKeyDecode
|
||||
\sa wc_SlhDsaKey_ImportPrivate
|
||||
*/
|
||||
int wc_SlhDsaKey_PrivateKeyDecode(const byte* input, word32* inOutIdx,
|
||||
SlhDsaKey* key, word32 inSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SubjectPublicKeyInfo(SPKI)形式のDERエンコードされたSLH-DSA公開鍵をデコードします。SLH-DSAのパラメータセットはAlgorithmIdentifierのOIDから検出され、key->paramsがそれに応じて更新されます。
|
||||
|
||||
高速パスとして、key->paramsが既に設定されている場合、この関数はまずinOutIdxからinSzまでのウィンドウ全体をwc_SlhDsaKey_ImportPublicに渡します。ImportPublicの長さチェックが判別要素となります。ちょうど2*nバイトのウィンドウは生の公開鍵(PK.seed || PK.root)として受け付けられ、全体が消費されます。それ以外の長さは拒否され、この関数はSPKIの解析へ進みます。SPKI入力は常にAlgorithmIdentifier/BIT STRINGのオーバーヘッドを十分に含むため、2*nという生の長さと衝突することはなく、問題なく解析へ進みます。呼び出し側がウィンドウを事前に2*nへ切り詰める必要はありません。
|
||||
|
||||
書き込みが行われる前に検出された失敗(BAD_FUNC_ARG、形式不正なSPKI)では、鍵の状態は変更されません。ImportPublicがkey->skの公開鍵側を設定した後に検出された失敗(SHA-2の事前計算エラー)では、公開鍵側のsk[2*n .. 4*n]が消去され、フラグからWC_SLHDSA_FLAG_PUBLICがクリアされます。呼び出し側が事前に秘密鍵をインポートしていた場合に備え、秘密鍵側はそのまま残されます。key->paramsとinOutIdxは呼び出し前の値に復元されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG input、inOutIdx、keyのいずれかがNULLの場合、またはinSzが0の場合に返されます。
|
||||
\return ASN_PARSE_E DERをSLH-DSA公開鍵として解析できない場合に返されます。
|
||||
\return NOT_COMPILED_IN OIDが、このライブラリに組み込まれていないSLH-DSAのバリアントを指している場合に返されます。
|
||||
|
||||
\param [in] input DERエンコードされた鍵データ。key->paramsが既に設定されている場合は生の2*n公開鍵。
|
||||
\param [in,out] inOutIdx 入力時はinput内の開始オフセット。出力時は解析した鍵の直後まで進みます(失敗時は変更されません)。
|
||||
\param [in,out] key SLH-DSA鍵。パラメータセットはエンコードされたOIDから自動検出されます。ただし生の公開鍵を渡す高速パスでは、既に設定されているパラメータセットがそのまま使用されます。
|
||||
\param [in] inSz inputの全体サイズ(バイト単位)。
|
||||
|
||||
\sa wc_SlhDsaKey_PublicKeyToDer
|
||||
\sa wc_SlhDsaKey_PrivateKeyDecode
|
||||
\sa wc_SlhDsaKey_ImportPublic
|
||||
*/
|
||||
int wc_SlhDsaKey_PublicKeyDecode(const byte* input, word32* inOutIdx,
|
||||
SlhDsaKey* key, word32 inSz);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA秘密鍵を、RFC 9909で定義されたPKCS#8 OneAsymmetricKey形式のDERにエンコードします。privateKey OCTET STRINGには、Ed25519/Ed448で使われる入れ子のOCTET STRINGラッピングを介さず、生の4*nバイト(SK.seed || SK.prf || PK.seed || PK.root)が直接格納されます。
|
||||
|
||||
WOLFSSL_SLHDSA_VERIFY_ONLYが定義されておらず、かつWC_ENABLE_ASYM_KEY_EXPORTが設定されている場合にのみ利用できます。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。書き込みを行わずに必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
|
||||
\return BAD_FUNC_ARG keyまたはkey->paramsがNULLの場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
\return BUFFER_E outputがNULLでなく、inLenが必要なサイズより小さい場合に返されます。
|
||||
\return NOT_COMPILED_IN key->paramsが、パラメータセットが組み込まれていないSLH-DSAのバリアントを指している場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵が設定されたSLH-DSA鍵。
|
||||
\param [out] output DERエンコードを受け取るバッファ。必要なサイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのバイト単位のサイズ(outputがNULLの場合は無視されます)。
|
||||
|
||||
\sa wc_SlhDsaKey_PrivateKeyDecode
|
||||
\sa wc_SlhDsaKey_PrivateKeyToDer
|
||||
\sa wc_SlhDsaKey_PublicKeyToDer
|
||||
*/
|
||||
int wc_SlhDsaKey_KeyToDer(SlhDsaKey* key, byte* output, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA秘密鍵をDERにエンコードします。RFC 9909はSK.seed || SK.prf || PK.seed || PK.rootを単一のOCTET STRINGにまとめるため、SLH-DSAには秘密鍵のみの独立したエンコードが存在しません。この関数はwc_SlhDsaKey_KeyToDerの意図的なエイリアスであり、独立した秘密鍵形式を持つEd25519/Ed448とのAPIの一貫性のために維持されています。
|
||||
|
||||
WOLFSSL_SLHDSA_VERIFY_ONLYが定義されておらず、かつWC_ENABLE_ASYM_KEY_EXPORTが設定されている場合にのみ利用できます。
|
||||
|
||||
戻り値はwc_SlhDsaKey_KeyToDerからそのまま引き継がれます。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
|
||||
\return BAD_FUNC_ARG keyまたはkey->paramsがNULLの場合に返されます。
|
||||
\return MISSING_KEY 秘密鍵が設定されていない場合に返されます。
|
||||
\return BUFFER_E outputがNULLでなく、inLenが必要なサイズより小さい場合に返されます。
|
||||
\return NOT_COMPILED_IN key->paramsが、パラメータセットが組み込まれていないSLH-DSAのバリアントを指している場合に返されます。
|
||||
|
||||
\param [in] key 秘密鍵が設定されたSLH-DSA鍵。
|
||||
\param [out] output DERエンコードを受け取るバッファ。必要なサイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのバイト単位のサイズ(outputがNULLの場合は無視されます)。
|
||||
|
||||
\sa wc_SlhDsaKey_KeyToDer
|
||||
\sa wc_SlhDsaKey_PrivateKeyDecode
|
||||
*/
|
||||
int wc_SlhDsaKey_PrivateKeyToDer(SlhDsaKey* key, byte* output, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup SLH_DSA
|
||||
|
||||
\brief SLH-DSA公開鍵をDERにエンコードします。withAlgが0以外の場合、出力は完全なSubjectPublicKeyInfo構造(AlgorithmIdentifierとBIT STRING)になります。withAlgが0の場合、出力はSPKIのラッピングを伴わない生の公開鍵バイト列になります。
|
||||
|
||||
WC_ENABLE_ASYM_KEY_EXPORTが設定されている場合にのみ利用できます。
|
||||
|
||||
\return 成功した場合、エンコードされたDERのサイズ(バイト単位)を返します。必要なバッファサイズを問い合わせるには、outputにNULLを渡してください。
|
||||
\return BAD_FUNC_ARG keyまたはkey->paramsがNULLの場合に返されます。
|
||||
\return BUFFER_E outputがNULLでなく、inLenが必要なサイズより小さい場合に返されます。
|
||||
\return NOT_COMPILED_IN key->paramsが、パラメータセットが組み込まれていないSLH-DSAのバリアントを指している場合に返されます。
|
||||
|
||||
\param [in] key 公開鍵が設定されたSLH-DSA鍵。
|
||||
\param [out] output DERエンコードを受け取るバッファ。必要なサイズを問い合わせる場合はNULL。
|
||||
\param [in] inLen outputのバイト単位のサイズ(outputがNULLの場合は無視されます)。
|
||||
\param [in] withAlg SubjectPublicKeyInfo(AlgorithmIdentifierを含む)を出力する場合は0以外、生の公開鍵のみを出力する場合は0。
|
||||
|
||||
\sa wc_SlhDsaKey_PublicKeyDecode
|
||||
\sa wc_SlhDsaKey_KeyToDer
|
||||
*/
|
||||
int wc_SlhDsaKey_PublicKeyToDer(SlhDsaKey* key, byte* output, word32 inLen,
|
||||
int withAlg);
|
||||
@@ -0,0 +1,431 @@
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief XmssKeyオブジェクトを初期化します。他のXMSS/XMSS^MT操作を行う前に呼び出さなければなりません。使用が終わったらwc_XmssKey_Free()でリソースを解放してください。
|
||||
|
||||
XMSS(eXtended Merkle Signature Scheme)とそのマルチツリー版であるXMSS^MT(RFC 8391、NIST SP 800-208)は、状態を持つ(STATEFUL)ハッシュベースの署名方式です。wc_XmssKey_Sign()を呼び出すたびに秘密鍵のワンタイムコンポーネントが消費され、ワンタイム鍵を再利用するとこの方式の安全性は完全に失われます。アプリケーションは、署名を行うたびに、次の署名までの間に秘密鍵の状態を永続化しなければなりません。wc_XmssKey_SetWriteCb()およびwc_XmssKey_SetReadCb()を参照してください。
|
||||
|
||||
初期化後、鍵はWC_XMSS_STATE_INITED状態になります。鍵を生成または再読み込みする前に、wc_XmssKey_SetParamStr()でパラメータセットを名前で選択しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するXmssKeyへのポインタ。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。NULLでも構いません。
|
||||
\param [in] devId ハードウェア暗号コールバック用のデバイス識別子。ソフトウェアのみで処理する場合はINVALID_DEVIDを使用します。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
XmssKey key;
|
||||
int ret;
|
||||
|
||||
ret = wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
|
||||
if (ret != 0) {
|
||||
// 鍵の初期化エラー
|
||||
}
|
||||
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");
|
||||
// ... 鍵を使用 ...
|
||||
wc_XmssKey_Free(&key);
|
||||
\endcode
|
||||
|
||||
\sa wc_XmssKey_Free
|
||||
\sa wc_XmssKey_SetParamStr
|
||||
\sa wc_XmssKey_MakeKey
|
||||
*/
|
||||
int wc_XmssKey_Init(XmssKey* key, void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief デバイス側の鍵識別子を指定してXmssKeyを初期化します。wc_XmssKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるバイナリ形式のidも保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
idは鍵オブジェクトへコピーされます。呼び出し側はこの関数から戻った直後に自身のバッファを解放して構いません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合、またはlenが0より大きいにもかかわらずidがNULLの場合に返されます。
|
||||
\return BUFFER_E lenが負の場合、またはXMSS_MAX_ID_LENより大きい場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するXmssKeyへのポインタ。
|
||||
\param [in] id デバイス側の鍵識別子バイト列へのポインタ。
|
||||
\param [in] len idのバイト数。[0, XMSS_MAX_ID_LEN]の範囲内でなければなりません。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_XmssKey_Init
|
||||
\sa wc_XmssKey_InitLabel
|
||||
\sa wc_XmssKey_Free
|
||||
*/
|
||||
int wc_XmssKey_InitId(XmssKey* key, const unsigned char* id, int len,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief デバイス側の鍵ラベルを指定してXmssKeyを初期化します。wc_XmssKey_Init()と同等ですが、暗号コールバックがデバイス上の実際の鍵素材を特定するために使用できるラベル文字列も保存します。wolfSSLがWOLF_PRIVATE_KEY_IDを有効にしてビルドされている場合にのみ利用できます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlabelがNULLの場合に返されます。
|
||||
\return BUFFER_E labelが空の場合、またはXMSS_MAX_LABEL_LENより長い場合に返されます。
|
||||
|
||||
\param [in,out] key 初期化するXmssKeyへのポインタ。
|
||||
\param [in] label NUL終端されたデバイス側の鍵ラベル。
|
||||
\param [in] heap 動的メモリ確保に使用するヒープヒント。
|
||||
\param [in] devId 暗号コールバック用のデバイス識別子。
|
||||
|
||||
\sa wc_XmssKey_Init
|
||||
\sa wc_XmssKey_InitId
|
||||
*/
|
||||
int wc_XmssKey_InitLabel(XmssKey* key, const char* label, void* heap,
|
||||
int devId);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief XMSSまたはXMSS^MTのパラメータセットをRFC 8391の名前で選択します。受け付けられる名前は"XMSS-<hash>_<height>_<n>"(単一ツリー)または"XMSSMT-<hash>_<total_height>/<layers>_<n>"(マルチツリー)の形式で、例えば"XMSS-SHA2_10_256"や"XMSSMT-SHA2_20/2_256"です。実際に受け付けられる名前の集合は、ビルド時に有効化されたハッシュファミリとツリーの高さによって決まります。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはstrがNULLの場合、または指定された名前のパラメータセットが未知であるかコンパイルに含まれていない場合に返されます。
|
||||
\return BAD_STATE_E keyがWC_XMSS_STATE_INITED状態でない場合に返されます。
|
||||
|
||||
\param [in,out] key WC_XMSS_STATE_INITED状態のXmssKeyへのポインタ。
|
||||
\param [in] str パラメータセット名(NUL終端)。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
XmssKey key;
|
||||
|
||||
wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
|
||||
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");
|
||||
\endcode
|
||||
|
||||
\sa wc_XmssKey_GetParamStr
|
||||
\sa wc_XmssKey_MakeKey
|
||||
*/
|
||||
int wc_XmssKey_SetParamStr(XmssKey* key, const char* str);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief この鍵に現在設定されているパラメータセット名を取得します。返されるポインタは静的な文字列を指しているため、呼び出し側が解放してはなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはstrがNULLの場合、またはパラメータセットが選択されていない場合に返されます。
|
||||
|
||||
\param [in] key パラメータセットが選択されたXmssKeyへのポインタ。
|
||||
\param [out] str 静的なパラメータ名文字列へのポインタを受け取ります。
|
||||
|
||||
\sa wc_XmssKey_SetParamStr
|
||||
*/
|
||||
int wc_XmssKey_GetParamStr(const XmssKey* key, const char** str);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 更新された秘密鍵の状態を永続化するためにwolfSSLが呼び出すコールバックを登録します。XMSS/XMSS^MTは状態を持つため、アプリケーションは、署名が成功するたびに、その署名が渡される前に秘密鍵を永続化しなければなりません。そうしなければ、クラッシュや再起動によってワンタイム鍵が再利用され、この方式が破られる可能性があります。
|
||||
|
||||
コールバックはwc_XmssRcコードのいずれかを返します。WC_XMSS_RC_SAVED_TO_NV_MEMORYは永続的な書き込みが完了したことを示します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはwrite_cbがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key XmssKeyへのポインタ。
|
||||
\param [in] write_cb 秘密鍵を永続化するために呼び出されるコールバック。
|
||||
|
||||
\sa wc_XmssKey_SetReadCb
|
||||
\sa wc_XmssKey_SetContext
|
||||
\sa wc_XmssKey_Sign
|
||||
*/
|
||||
int wc_XmssKey_SetWriteCb(XmssKey* key, wc_xmss_write_private_key_cb write_cb);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 永続化された秘密鍵の状態を読み込むためにwolfSSLが呼び出すコールバックを登録します。保存された鍵をメモリに復元して署名を継続するために、wc_XmssKey_Reload()から使用されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはread_cbがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key XmssKeyへのポインタ。
|
||||
\param [in] read_cb 秘密鍵を読み込むために呼び出されるコールバック。
|
||||
|
||||
\sa wc_XmssKey_SetWriteCb
|
||||
\sa wc_XmssKey_Reload
|
||||
*/
|
||||
int wc_XmssKey_SetReadCb(XmssKey* key, wc_xmss_read_private_key_cb read_cb);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 秘密鍵の読み込みコールバックと書き込みコールバックの両方に渡される、不透明なコンテキストポインタを設定します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] key XmssKeyへのポインタ。
|
||||
\param [in] context アプリケーションが定義するポインタ。NULLでも構いません。
|
||||
|
||||
\sa wc_XmssKey_SetReadCb
|
||||
\sa wc_XmssKey_SetWriteCb
|
||||
*/
|
||||
int wc_XmssKey_SetContext(XmssKey* key, void* context);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 新しいXMSS/XMSS^MT鍵ペアを生成します。事前にwc_XmssKey_SetParamStr()でパラメータセットが選択され、読み込みコールバックと書き込みコールバックが登録されていなければなりません。新しく生成された秘密鍵は、この関数が戻る前に書き込みコールバックを介して永続化されます。成功時、鍵はWC_XMSS_STATE_OK状態に遷移します。
|
||||
|
||||
ツリーの高さが大きい場合、鍵生成には時間がかかることがあります。XMSS^MTのバリアントは複数の小さなツリーにコストを分散するため、同等の単一ツリーXMSSパラメータセットに比べて鍵生成が大幅に高速です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return MEMORY_E メモリ確保に失敗した場合に返されます。
|
||||
|
||||
\param [in,out] key コールバックが設定され、WC_XMSS_STATE_PARMSET状態にあるXmssKeyへのポインタ。
|
||||
\param [in] rng 初期化済みのWC_RNGへのポインタ。
|
||||
|
||||
_Example_
|
||||
\code
|
||||
XmssKey key;
|
||||
WC_RNG rng;
|
||||
|
||||
wc_XmssKey_Init(&key, NULL, INVALID_DEVID);
|
||||
wc_XmssKey_SetParamStr(&key, "XMSS-SHA2_10_256");
|
||||
wc_XmssKey_SetWriteCb(&key, my_write_cb);
|
||||
wc_XmssKey_SetReadCb(&key, my_read_cb);
|
||||
wc_XmssKey_SetContext(&key, &my_storage);
|
||||
wc_InitRng(&rng);
|
||||
|
||||
if (wc_XmssKey_MakeKey(&key, &rng) != 0) {
|
||||
// 鍵の生成エラー
|
||||
}
|
||||
\endcode
|
||||
|
||||
\sa wc_XmssKey_Sign
|
||||
\sa wc_XmssKey_Reload
|
||||
*/
|
||||
int wc_XmssKey_MakeKey(XmssKey* key, WC_RNG* rng);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 登録された読み込みコールバックを使用して、以前生成したXMSS/XMSS^MT秘密鍵を永続ストレージから再読み込みし、さらにメッセージへ署名できる状態に鍵を復元します。成功時、鍵はWC_XMSS_STATE_OK状態になります。
|
||||
|
||||
Reloadを呼び出す前に、鍵生成時に選択したものと同じパラメータセットをwc_XmssKey_SetParamStr()で再適用しなければなりません。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return WC_XMSS_RC_* 読み込みコールバックが失敗した場合、対応するエラーが返されます。
|
||||
|
||||
\param [in,out] key パラメータと読み込みコールバックが設定されたXmssKeyへのポインタ。
|
||||
|
||||
\sa wc_XmssKey_MakeKey
|
||||
\sa wc_XmssKey_SetReadCb
|
||||
*/
|
||||
int wc_XmssKey_Reload(XmssKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、エンコードされた秘密鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたXmssKeyへのポインタ。
|
||||
\param [out] len 秘密鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_XmssKey_GetPubLen
|
||||
\sa wc_XmssKey_GetSigLen
|
||||
*/
|
||||
int wc_XmssKey_GetPrivLen(const XmssKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、XMSS/XMSS^MT公開鍵のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたXmssKeyへのポインタ。
|
||||
\param [out] len 公開鍵のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_XmssKey_ExportPubRaw
|
||||
*/
|
||||
int wc_XmssKey_GetPubLen(const XmssKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief この鍵に設定されているパラメータセットにおける、署名のサイズをバイト単位で返します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyまたはlenがNULLの場合に返されます。
|
||||
|
||||
\param [in] key パラメータが設定されたXmssKeyへのポインタ。
|
||||
\param [out] len 署名のサイズ(バイト単位)を受け取ります。
|
||||
|
||||
\sa wc_XmssKey_Sign
|
||||
*/
|
||||
int wc_XmssKey_GetSigLen(const XmssKey* key, word32* len);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief keyが保持するXMSS/XMSS^MT秘密鍵でmsgに署名します。呼び出し時、*sigSzはsigバッファのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
署名が成功するたびに、秘密鍵のワンタイムコンポーネントが1つ消費されます。更新された鍵の状態は、新しい署名が呼び出し側に返される前に、登録された書き込みコールバックを介して永続化されます。書き込みコールバックが失敗した場合、署名の呼び出しも失敗し、署名は返されません。使用可能なワンタイム鍵を使い切ると、鍵はWC_XMSS_STATE_NOSIGS状態に遷移し、以降の署名の試行は失敗します。この状態を事前に検出するにはwc_XmssKey_SigsLeft()を問い合わせてください。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *sigSzが署名のサイズより小さい場合に返されます。
|
||||
\return すべてのワンタイム鍵が使用済みの場合、負のエラーが返されます。
|
||||
|
||||
\param [in,out] key WC_XMSS_STATE_OK状態のXmssKeyへのポインタ。
|
||||
\param [out] sig 署名を受け取るバッファ。
|
||||
\param [in,out] sigSz 入力時: sigのサイズ。出力時: 書き込まれたバイト数。
|
||||
\param [in] msg 署名するメッセージ。
|
||||
\param [in] msgSz msgのバイト単位の長さ。
|
||||
|
||||
\sa wc_XmssKey_Verify
|
||||
\sa wc_XmssKey_SigsLeft
|
||||
\sa wc_XmssKey_SetWriteCb
|
||||
*/
|
||||
int wc_XmssKey_Sign(XmssKey* key, byte* sig, word32* sigSz, const byte* msg,
|
||||
int msgSz);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief この鍵で残り何回のワンタイム署名が可能かを返します。この数が0になると、鍵はそれ以上署名できないため、使用を終了してください。
|
||||
|
||||
\return 成功した場合、残りの署名可能回数(非負の値)を返します。
|
||||
\return 失敗した場合は負のエラーコードが返されます(例: keyがNULLの場合はBAD_FUNC_ARG)。
|
||||
|
||||
\param [in,out] key WC_XMSS_STATE_OK状態のXmssKeyへのポインタ。
|
||||
|
||||
\sa wc_XmssKey_Sign
|
||||
*/
|
||||
int wc_XmssKey_SigsLeft(XmssKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief XmssKeyが保持しているリソースを解放します。NULLポインタを渡しても安全です。この呼び出しの後、鍵はWC_XMSS_STATE_FREED状態になり、再利用する前に再初期化しなければなりません。
|
||||
|
||||
\param [in,out] key 解放するXmssKeyへのポインタ。
|
||||
|
||||
\sa wc_XmssKey_Init
|
||||
*/
|
||||
void wc_XmssKey_Free(XmssKey* key);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief keySrcの公開鍵部分をkeyDstにコピーします。コピー先の鍵は同じパラメータセットを継承し、検証に使用できます。秘密鍵の状態は持たないため、署名はできません。検証者に必要最小限のデータだけを渡す場合に有用です。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyDstまたはkeySrcがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] keyDst 初期化済みのコピー先XmssKeyへのポインタ。
|
||||
\param [in] keySrc 公開鍵を保持するXmssKeyへのポインタ。
|
||||
|
||||
\sa wc_XmssKey_ExportPub_ex
|
||||
\sa wc_XmssKey_ExportPubRaw
|
||||
*/
|
||||
int wc_XmssKey_ExportPub(XmssKey* keyDst, const XmssKey* keySrc);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief wc_XmssKey_ExportPub()と同様ですが、コピー先の鍵は指定されたheapとdevIdで新規に初期化されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG keyDstまたはkeySrcがNULLの場合に返されます。
|
||||
|
||||
\param [in,out] keyDst 内容を設定する対象のXmssKeyへのポインタ。
|
||||
\param [in] keySrc 公開鍵を保持するXmssKeyへのポインタ。
|
||||
\param [in] heap keyDst用のヒープヒント。
|
||||
\param [in] devId keyDst用のデバイス識別子。
|
||||
|
||||
\sa wc_XmssKey_ExportPub
|
||||
*/
|
||||
int wc_XmssKey_ExportPub_ex(XmssKey* keyDst, const XmssKey* keySrc,
|
||||
void* heap, int devId);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief XMSS/XMSS^MT公開鍵を生のバイト列としてエクスポートします。呼び出し時、*outLenはoutのサイズを表します。成功時には書き込まれたバイト数に更新されます。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E *outLenが公開鍵のサイズより小さい場合に返されます。
|
||||
|
||||
\param [in] key XmssKeyへのポインタ。
|
||||
\param [out] out 公開鍵を受け取るバッファ。
|
||||
\param [in,out] outLen 入力時: outのサイズ。出力時: 書き込まれたバイト数。
|
||||
|
||||
\sa wc_XmssKey_ImportPubRaw
|
||||
\sa wc_XmssKey_GetPubLen
|
||||
*/
|
||||
int wc_XmssKey_ExportPubRaw(const XmssKey* key, byte* out, word32* outLen);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief 生のXMSS公開鍵をkeyにインポートします。鍵はWC_XMSS_STATE_INITED状態であり、かつパラメータセットが事前に選択されていなければなりません(生のエンコードにはパラメータセットが含まれないため、呼び出し側が先にwc_XmssKey_SetParamStr()で適用する必要があります)。成功時、鍵はWC_XMSS_STATE_VERIFYONLY状態に遷移します。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E inLenが期待される公開鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたXmssKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列。
|
||||
\param [in] inLen inのバイト単位の長さ。
|
||||
|
||||
\sa wc_XmssKey_ImportPubRaw_ex
|
||||
\sa wc_XmssKey_ExportPubRaw
|
||||
\sa wc_XmssKey_Verify
|
||||
*/
|
||||
int wc_XmssKey_ImportPubRaw(XmssKey* key, const byte* in, word32 inLen);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief wc_XmssKey_ImportPubRaw()と同様ですが、エンコードされた鍵が単一ツリーのXMSSかマルチツリーのXMSS^MTかを明示的に指定します(XMSS^MTの場合は0以外、XMSSの場合は0を渡します)。
|
||||
|
||||
\return 0 成功した場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return BUFFER_E inLenが期待される公開鍵サイズと一致しない場合に返されます。
|
||||
|
||||
\param [in,out] key パラメータセットが設定されたXmssKeyへのポインタ。
|
||||
\param [in] in 生の公開鍵バイト列。
|
||||
\param [in] inLen inのバイト単位の長さ。
|
||||
\param [in] is_xmssmt 鍵がXMSS^MTの場合は0以外、通常のXMSSの場合は0。
|
||||
|
||||
\sa wc_XmssKey_ImportPubRaw
|
||||
*/
|
||||
int wc_XmssKey_ImportPubRaw_ex(XmssKey* key, const byte* in, word32 inLen,
|
||||
int is_xmssmt);
|
||||
|
||||
/*!
|
||||
\ingroup XMSS
|
||||
|
||||
\brief keyが保持する公開鍵を使用して、msgに対するXMSS/XMSS^MT署名を検証します。この関数は署名が有効な場合にのみ0を返します。それ以外の値は署名が拒否されたことを示します。
|
||||
|
||||
\return 0 署名が有効な場合に返されます。
|
||||
\return BAD_FUNC_ARG 必要なポインタのいずれかがNULLの場合に返されます。
|
||||
\return SIG_VERIFY_E (または類似のコード)署名が無効または形式が不正な場合に返されます。
|
||||
|
||||
\param [in,out] key 公開鍵を保持するXmssKeyへのポインタ。
|
||||
\param [in] sig 検証する署名バイト列。
|
||||
\param [in] sigSz sigのバイト単位の長さ。
|
||||
\param [in] msg 署名対象であったメッセージ。
|
||||
\param [in] msgSz msgのバイト単位の長さ。
|
||||
|
||||
\sa wc_XmssKey_Sign
|
||||
\sa wc_XmssKey_ImportPubRaw
|
||||
*/
|
||||
int wc_XmssKey_Verify(XmssKey* key, const byte* sig, word32 sigSz,
|
||||
const byte* msg, int msgSz);
|
||||
Reference in New Issue
Block a user