Key Management and Storage

[xrissoula]

Description

This PR adds a new reference document detailing Polykey’s approach to key management and storage. The document outlines how Polykey securely generates, stores, and manages encryption keys, ensuring data confidentiality, integrity, and availability. It explains the use of symmetric and asymmetric cryptographic methods, key encapsulation mechanisms (KEM), and considerations for securely handling cryptographic keys across different environments.

Changes Introduced

• Created docs/reference/key-encryption-management-storage.md
• Explained symmetric vs. asymmetric encryption and their trade-offs in key management.
• Detailed key encapsulation mechanisms (KEM) and their role in Polykey’s security model.
• Included storage considerations for encrypted keys and how Polykey ensures forward secrecy.
• Addressed trusted identity concerns, including the risks of centralized certificate authorities (CAs).
• Referenced Ed25519 key generation and usage in key management.

Security Considerations

• Man-in-the-middle (MITM) risk in symmetric encryption: Need for secure key exchange channels.
• Public key trust issues: Potential for key fraud or impersonation in asymmetric encryption.
• Key revocation and rotation: Importance of regularly updating and securely storing keys to prevent compromise.
• Centralized CA risks: Issues with relying on external trusted third parties for key authentication.

References

• Polykey Security Model: Hybrid Cryptosystem
• Elliptic Curve Integrated Encryption Scheme (ECIES)
• Ed25519 Key Management (Mozilla blog reference)
• JSON Web Encryption (JWE) for Key Storage

Issues Fixed

• Relates Create Article in Polykey-Docs Explaining the Polykey Elliptic Curve Article #119
• Improved documentation on Polykey’s key security model by adding a dedicated Key Management and Storage reference.
• Clarified the distinction between symmetric and asymmetric encryption in key handling.
• Addressed knowledge gaps in KEM usage within Polykey’s encryption infrastructure.
• Resolved ambiguity around Ed25519/x25519 key generation and usage.
• Expanded on key rotation, revocation, and secure persistence considerations.

Tasks

• 1. Documented Polykey’s key management strategy, covering key generation, storage, and security considerations.
• 2. Explained symmetric vs. asymmetric encryption and their implications for key management.
• 3. Detailed Key Encapsulation Mechanism (KEM) and its role in securely transmitting encryption keys.
• 4. Covered Ed25519 keypair generation, usage, and storage considerations.
• 5. Explained JWK encryption and persistence using Flattened JWE JSON.
• 6. Outlined threats and security risks, including MITM attacks, key impersonation, and CA trust issues.

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