Encryption Algorithms and Security Considerations Documentation

[xrissoula]

Description

This PR introduces a new reference document: Encryption Algorithms and Security Considerations. This document outlines the cryptographic algorithms used within Polykey, detailing their security properties, implementation rationale, and best practices for secure usage. The goal is to ensure clarity on why specific encryption algorithms were chosen and to provide a security model reference for developers and security professionals.

This document will help Polykey users understand:

• The difference between symmetric and asymmetric encryption in the Polykey ecosystem
• How encryption algorithms are applied for securing data and communication
• The security implications and trade-offs of different cryptographic approaches
• Best practices for secure key management and cryptographic hygiene

Issues Fixed

Relates: #119

Tasks

• 1. Add encryption-algorithms.md to docs/reference/
• 2. Document Polykey’s encryption model, including symmetric and asymmetric cryptography
• 3. Explain the use of ECIES, AES-GCM, Ed25519, and their cryptographic properties
• 4. Discuss nonce reuse risks, key rotation, and cryptographic best practices
• 5. Ensure proper frontmatter formatting for integration into the documentation system
• 6. Proofread for technical accuracy and clarity
• 7. Verified consistency with existing Polykey documentation
• 8. Ensured correct Markdown formatting and frontmatter compliance
• 9. Checked for any missing security considerations
• 10. Confirmed smooth readability for both security professionals and general developers

Final checklist

• Domain specific tests
• Full tests
• Updated inline-comment documentation
• Lint fixed
• Squash and rebased
• Sanity check the final build

[xrissoula]

This PR is closed in favor of #135