# DDR-0021: Cryptography Library Selection for E27 Implementation

Status: Approved
Date: 2025-12-22
Applies to: elkm1/elke27_lib (E27 only)

Related ADRs:
- ADR-0006: E27 Cryptographic Model and Key Handling
- ADR-0008: Separation of Link, Presentation, and Application Layers

Related DDRs:
- DDR-0003: E27 Message Layer Architecture
- DDR-0015: E27 Link Layer Framing and Deframing
- DDR-0020: Silent Failure Behavior on Invalid Credentials

---

Context

The Elk E27 protocol relies on AES-128-CBC encryption with strict requirements:

- Fixed IV usage for specific message classes (e.g., API_LINK_IV = 00..0F)
- Explicit control over padding (no implicit PKCS#7)
- Precise byte-order transformations (32-bit word endianness swaps)
- Deterministic behavior across platforms

The original Node-RED prototype used Node.js crypto primitives. A production Python implementation requires a stable, well-maintained cryptography library that allows explicit control of these behaviors.

---

Decision

The E27 implementation SHALL use the Python “cryptography” package for all symmetric cryptographic operations.

Specifically:
- AES-128-CBC mode
- Explicit IV management
- Manual padding and unpadding
- Explicit encryptor and decryptor lifecycle control

Deprecated or alternative libraries such as pycrypto, pycryptodome, or implicit crypto helpers are explicitly excluded.

---

Rationale

The cryptography package is:
- The Python community standard for symmetric cryptography
- Actively maintained and security-audited
- Explicit in its behavior, avoiding hidden padding or byte manipulation
- Widely supported across Home Assistant deployment environments

Using cryptography ensures protocol correctness, portability, and long-term maintainability.

---

Consequences

- presentation.py, hello.py, and related modules depend on cryptography
- Build and runtime environments must include the cryptography package
- All padding, IV usage, and endian transformations must be explicitly implemented in code

This decision is binding for all E27 cryptographic operations.
