Skip to content

Correct and modernize the wolfProvider manual against current wolfProvider sources - #280

Open
aidangarske wants to merge 4 commits into
wolfSSL:masterfrom
aidangarske:wolfprovider-manual-modernize
Open

Correct and modernize the wolfProvider manual against current wolfProvider sources#280
aidangarske wants to merge 4 commits into
wolfSSL:masterfrom
aidangarske:wolfprovider-manual-modernize

Conversation

@aidangarske

@aidangarske aidangarske commented Aug 29, 2026

Copy link
Copy Markdown
Member

wolfProvider manual general updates

Copilot AI lite review requested due to automatic review settings August 29, 2026 00:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@aidangarske aidangarske self-assigned this Aug 29, 2026
@aidangarske
aidangarske marked this pull request as ready for review August 31, 2026 15:46

@yosuke-wolfssl yosuke-wolfssl left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewing the src-ja/ half, against the English in this same PR and against the PR
description.

The new Japanese reads well — chapter 7's replace-default section is fluent and faithful.
The issue is coverage: three chapters the PR description claims to have fixed did not get
translated, and the rest was translated from an intermediate draft, so parts of the JA
manual now contradict the EN manual beside it.

1. Claimed in the PR description, but not present in src-ja/

Chapter PR description says src-ja/ actually has
chapter05.md "corrects every enum to WP_LOG_LEVEL_* / WP_LOG_COMP_*, adds DEBUG/TRACE, fixes the default mask, documents the compile-time filters" Only the quote characters changed. Still wolfProvider_LogType, WP_LOG_ERROR, WP_LOG_COMPONENTS_ALL, and PROVIDER_ctrl_cmd() / 「エンジン制御コマンド」 in 6 places
chapter08.md "corrects the entry points, the four provider params, the capability set, and the teardown behavior" Source-file table only; all five ### subsections EN has (wolfprov_teardownwolfprov_query) are missing
chapter11.md "notes validated FIPS/FIPS-Ready reject PQC/LMS" That paragraph is not in the JA chapter

Two knock-on effects worth noting:

  • chapter05.md is now internally inconsistent — the typedef was renamed to
    wolfProv_Logging_cb, but the surrounding text still registers it via the
    "set_logging_cb" エンジン制御コマンド, and the EN no longer describes it that way.
  • chapter08.md keeps 「OSSLパラメータに関する注意(後述):」, a forward reference to
    sections that exist only in the EN file.

2. Translation fidelity

chapter04.md — the JA is stronger than the EN in a FIPS context, and drops EN's
qualifiers:

  • 「完全なFIPS適合を実現するには」 for "For broader FIPS coverage" → suggest
    「FIPS適合の範囲を広げるため」
  • 「…フォールバックすることを防ぎます」 for "reduces the risk of … silently falling back"
    → suggest 「…リスクを低減します」
  • EN says replace-default needs both --enable-replace-default and an OpenSSL
    built with wolfProvider's provider replacement, and points at
    scripts/build-wolfprovider.sh --replace-default. The JA says only 「置き換え用デフォルト
    モード (--enable-replace-default) でビルドされます」, so a JA reader will think the
    configure flag alone is enough.
  • EN's closing caveat 「これ自体がシステム全体のFIPS適合を保証するものではありません」 is
    dropped, and the JA still carries the old third paragraph
    (「FIPSで検証されたアルゴリズム、モード、および鍵サイズ…のみが含まれます」) that the EN
    softened in this PR.

chapter03.md

  • Line 342 says WP_HAVE_SEED; the EN table says WP_HAVE_SEED_SRC.
  • The EN deleted ## Building on WinCE. The JA kept 「## WinCE上でのビルド」 (line 207) and
    also added the new 「## Windows上でのビルド (Visual Studio)」 (line 240), so the JA
    manual carries two incompatible Windows sections.
  • Not carried over: the user_settings.h removal from the package layout, the IDE/
    description, the reworked OpenSSL build block and "latest patch release" note,
    --enable-sha3 / --enable-shake256, the --enable-sp quoting fix, the expanded
    WOLFPROVIDER_USER_SETTINGS row, and the LD_LIBRARY_PATH fix (JA line 173 still has
    the old /usr/local/ssl: form).
  • The build examples drifted: EN openssl-3.5.4, JA openssl-3.5.0.

chapter06.md — the platform lists differ. JA: Linux / macOS / Windows / Windows CE.
EN: Linux / macOS / Windows / Android / Apple platforms. The JA also lacks EN's new
threading caveat about the logging setters and FIPS-check state being unsynchronised
process globals.

3. JA translated from the pre-revision EN

Commit 2 translated the English, commit 3 revised the English without re-syncing. Two of
these now say the opposite of the EN:

  • chapter11.md LMS rationale — JA keeps 「OpenSSL 3.6のプロバイダーABIがLMSを検証専用として
    定義しているため」, which commit 3 replaced with the key-type-contract + design-choice
    framing.
  • chapter11.md provider.conf — JA: 「関係のない操作が…選択されないことを保証するものでは
    ありません」. EN now says only libwolfprov is activated, so unsupported operations fail
    rather than falling back.
  • chapter09.md — JA says FIPS is additionally verified 「Jenkinsパイプライン」; EN now says
    dedicated FIPS / FIPS-Ready GitHub Actions workflows.
  • chapter11.md also misses the OPENSSL_TAG=openssl-3.6.2 build commands, the "not
    3.6.0" note, and the make check correction.

4. Minor

  • chapter07.md uses *…* italics on Japanese text in 5 places. The JA PDF is built with
    CJKmainfont="Noto Sans CJK JP", which has no italic face — use **…** or 「…」.
  • chapter08.md mixes 「プロバイダー」 and 「プロバイダ」 within the same table (new rows vs
    existing rows). 「プロバイダ」may be natural one.
  • chapter11.md line 252: 「selectionの処理」 — untranslated word; at least 「selection の処理」.
    Its code comments are also left in English, while chapter03.md translates them.

Suggestion

Worth running make pdf html with DOC_LANG=JA before merge too — chapter11.md is new
on the JA side and the Makefile change moves it into the JA SOURCES list.

@yosuke-wolfssl yosuke-wolfssl left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good to me.
Let's give @padelsbach a chance to review this.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants