Add cooperative PBKDF2 compare operations

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.

[zekageri]

Summary

Adds a stateful PBKDF2 comparison API so password verification can be split into bounded work slices instead of one monolithic mbedTLS call.

KnotCompareOperation operation;
KnotResult begin = knot.beginCompare(operation, password, encodedHash);
KnotStepResult step = operation.step(iterationBudget);
while (step.inProgress()) {
// Return control to FreeRTOS or Worker.
step = operation.step(iterationBudget);
}

Root cause

The existing compare() implementation holds Knot's global mutex while mbedtls_pkcs5_pbkdf2_hmac_ext() performs the complete PBKDF2 workload. At production costs this can monopolize the caller task, exceed responsiveness budgets, and prevent request cancellation or CPU budgeting.

Changes

• Adds KnotCompareOperation, KnotStepResult, and KnotStepStatus.
• Adds C-string and binary-safe beginCompare() overloads.
• Carries PBKDF2 iteration state, U, accumulated T, derived-key block, salt, expected hash, password copy, and reusable HMAC context between calls.
• Limits each step() to the caller-provided iteration budget.
• Supports cancellation and operation reuse.
• Securely clears password and PBKDF2 state on success, failure, cancellation, reuse, and destruction.
• Releases Knot's mutex after validation and state snapshot; no mutex is held between steps or while the caller sleeps.
• Preserves the existing $knot$v1$c<cost>$<salt>$<hash> format and synchronous compare() API.
• Adds an mbedTLS HMAC backend context and matching OpenSSL host-test backend.
• Adds a cooperative example and API/memory documentation.

Validation

• Cooperative known-vector match and mismatch.
• Bounded iteration progress.
• Cancellation and terminal state.
• Operation reuse after completion/cancellation.
• Completion after Knot is deinitialized, proving the operation owns its state after beginCompare().
• Invalid input and zero-budget failure paths.
• Existing synchronous comparison compatibility.
• Local host build with -Wall -Wextra -pedantic.
• Local ASan/UBSan cooperative lifecycle run.

The PR CI also runs the existing host suite, cooperative tests, sanitizers, and the ESP32 example build matrix.