Update call names; update & improve docs on library usage

[PropzSaladaz]

Description

This PR is mostly about improving call readability & improving documentation on library usage:

• API Rename (getSharesRaw $\to$ getThresholdSharesRaw):

  • Renamed on TEDecryptSet to accurately reflect that it returns a threshold-bounded subset ($t$ shares) for reconstruction rather than all collected shares.
  • Updated callers in ThresholdEncryption.cpp and tests in test_TE_wrappers.cpp.

• Docs Improvements (using-threshold-encryption.md):

  • Clarified 1-based participant indexing (1 <= index <= n; 0 is rejected).
  • Updated code examples to use EncryptMetaData for TE and AES AAD.
  • Added decrypt_set.canMerge() check prior to share combination.
  • Recommended validateAndDecrypt(...) to eliminate double-decryption overhead.
  • Added wire serialization (toBytes/fromBytes, toString) and batch/parallel API references.

• Thread-Safety Documentation (AesGcmCipher.h):

  • Documented that AesGcmCipher is not thread-safe and requires single-threaded use or external synchronization.

  Fixes Clarify threshold decryption share handling and update usage docs #335

[Copilot]

Copilot review overview

🟡 Changes recommended

Remaining deleted-API calls break test compilation, and documentation inconsistencies should be corrected.

Get a fresh assessment by requesting another Copilot review.

Review effort: Lite
Findings: 1 · 2

Open (3)

• Replace deleted addDecryptShare calls in removal test · New
• aes_key scoped too narrowly for later documentation examples · New
• Update brief to describe threshold-sized share subset · New

What changed in this PR

This PR renames threshold-encryption APIs, limits reconstruction shares to the threshold, and expands usage and thread-safety documentation.

Changes:

• Renamed share-management and combination APIs.
• Updated callers, tests, samples, and benchmarks.
• Expanded TE/DKG, serialization, batch API, and AES thread-safety guidance.

File	Summary
tools/​decryptMessage.cpp	Updated decryption API usage.
threshold_encryption/​ThresholdEncryption.h	Renamed combination APIs; brief still incorrectly refers to all shares.
threshold_encryption/​ThresholdEncryption.cpp	Implemented renamed combination methods.
threshold_encryption/​threshold_encryption.cpp	Updated helper documentation; contains an “auxiliar” typo.
threshold_encryption/​TEDecryptSet.h	Renamed share-management and raw-share APIs.
threshold_encryption/​TEDecryptSet.cpp	Implemented validated insertion and threshold-limited export.
threshold_encryption/​AesGcmCipher.h	Documented thread-safety requirements.
test/​test_TE_wrappers.cpp	Updated tests, but remaining calls to deleted addDecryptShare prevent compilation.
test/​test_encrypt_message.cpp	Updated combination API usage.
test/​te_sample_sgx.cpp	Updated validated share workflow.
docs/​usage/​using-threshold-encryption.md	Expanded guidance; examples have an aes_key scope issue and overly broad indexing statement.
docs/​usage/​using-distributed-key-generation.md	Updated DKG usage guidance.
benchmarks/​bench_te.cpp	Updated benchmark API usage.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.