[FEATURE] Enhance crypto_utils with PEM Key Loading/Saving Functions

[erik-sv]

Problem Statement

When following the documentation examples for embedding or verifying metadata, users currently need to import functions directly from the cryptography library (specifically serialization.load_pem_private_key, serialization.load_pem_public_key, etc.) to handle PEM key files. This adds an extra dependency import and exposes lower-level cryptographic details, making the initial setup slightly more complex than ideal for the common task of loading/saving pre-generated keys.

Proposed Solution

Introduce helper functions within encypher.core.crypto_utils to encapsulate the logic for loading and saving Ed25519 private and public keys from/to PEM-formatted files.

• New Functions:
  • save_private_key_pem(private_key: ed25519.Ed25519PrivateKey, file_path: str, password: Optional[bytes] = None) -> None
  • load_private_key_pem(file_path: str, password: Optional[bytes] = None) -> ed25519.Ed25519PrivateKey
  • save_public_key_pem(public_key: ed25519.Ed25519PublicKey, file_path: str) -> None
  • load_public_key_pem(file_path: str) -> ed25519.Ed25519PublicKey
• How it would work: Users would import these functions from encypher.core.crypto_utils and call them directly with the file path (and optional password).
• Components affected: Primarily encypher.core.crypto_utils.py and associated tests. Documentation examples (.md files) would be updated to use these helpers.
• Potential impacts: Simplifies user code in documentation and examples. No direct impact on core encoding/decoding logic, as it just provides wrappers.

Alternative Solutions

1. Keep current approach: Continue having documentation examples directly use cryptography.hazmat.primitives.serialization. This works but is less user-friendly.
2. Document cryptography usage more heavily: Add a dedicated section explaining the cryptography functions, but this doesn't simplify the user's code itself.

Use Cases

1. Simplified Key Loading: When setting up metadata embedding or verification, users could simply call private_key = load_private_key_pem("my_key.pem") or public_key = load_public_key_pem("my_public_key.pem") without needing extra imports or file handling boilerplate.
2. Simplified Key Saving: After generating a key pair using generate_key_pair, users could easily save them using save_private_key_pem(...) and save_public_key_pem(...).
3. Cleaner Documentation: Documentation examples become shorter and focus more on EncypherAI's core features.

Implementation Ideas

• Technical approach: Implement the proposed functions within encypher_python_package/encypher/core/crypto_utils.py. These functions will internally use cryptography.hazmat.primitives.serialization to perform the actual loading/saving operations.
• Required changes: Modify crypto_utils.py, add unit tests for the new functions, and update all documentation examples (.md files in docs/package/) to use these new helper functions.
• Potential challenges: Ensuring robust error handling for file I/O, incorrect passwords, and malformed PEM files.

Additional Context

This feature request arises from the recent documentation refactoring effort focused on improving key management examples. The refactoring highlighted the boilerplate code needed for PEM handling, which these helper functions aim to eliminate for the end-user.