[JA] Add missing Japanese dox_comments for 7 API groups

doc/dox_comments/header_files-ja/doxygen_groups.h

@@ -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 ECC​​SIの概要
     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

doc/dox_comments/header_files-ja/puf.h

@@ -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);