<!-- Copyright (c) 2026 defconxt. All rights reserved. -->
<!-- Licensed under AGPL-3.0 — see LICENSE file for details. -->
---
name: implementing-end-to-end-encryption
description: >-
  Design and implement end-to-end encryption for messaging, file sharing,
  and data-at-rest scenarios. Covers Signal Protocol, X3DH key agreement,
  envelope encryption, client-side encryption patterns, and key management
  for E2EE systems.
domain: cybersecurity
subdomain: cryptography
tags:
  - e2ee
  - signal-protocol
  - double-ratchet
  - x3dh
  - envelope-encryption
  - key-exchange
  - messaging
version: "1.0"
author: defconxt
license: AGPL-3.0
metadata:
  mitre-attack: ["T1573"]
---

# Implementing End-to-End Encryption

## Overview

End-to-end encryption ensures only communicating parties can read messages —
the service provider cannot decrypt content even with full server access.
This skill covers protocol design (Signal/Double Ratchet), key agreement
(X3DH), envelope encryption for data at rest, and implementation patterns
that maintain forward secrecy and post-compromise security.

## Prerequisites

| Requirement | Install |
|---|---|
| OpenSSL 3.x | `apt install openssl` |
| Python 3.10+ with cryptography | `pip install cryptography` |
| age encryption | `apt install age` / `brew install age` |
| gpg | `apt install gnupg` |

## Key Concepts

### X25519 Key Exchange

```bash
# Generate X25519 key pairs
openssl genpkey -algorithm X25519 -out alice_private.pem
openssl pkey -in alice_private.pem -pubout -out alice_public.pem
openssl genpkey -algorithm X25519 -out bob_private.pem
openssl pkey -in bob_private.pem -pubout -out bob_public.pem

# Derive shared secret
openssl pkeyutl -derive -inkey alice_private.pem \
  -peerkey bob_public.pem -out shared_secret.bin

# Verify both sides derive the same secret
openssl pkeyutl -derive -inkey bob_private.pem \
  -peerkey alice_public.pem -out shared_secret_bob.bin
diff shared_secret.bin shared_secret_bob.bin && echo "Keys match"
```

### Envelope Encryption

```bash
# Generate a data encryption key (DEK)
openssl rand -out dek.bin 32

# Encrypt DEK with key encryption key (KEK) using RSA-OAEP
openssl pkeyutl -encrypt -inkey kek_public.pem -pubin \
  -in dek.bin -out dek_encrypted.bin \
  -pkeyopt rsa_padding_mode:oaep -pkeyopt rsa_oaep_md:sha256
```

### File Encryption with age

```bash
# Generate identity
age-keygen -o key.txt

# Encrypt for a recipient
age -r age1pubkey... -o secret.age plaintext.txt

# Decrypt
age -d -i key.txt -o plaintext.txt secret.age
```

### GPG Encryption

```bash
# Symmetric encryption (AES-256)
gpg --symmetric --cipher-algo AES256 -o encrypted.gpg plaintext.txt

# Asymmetric encryption
gpg --encrypt --recipient user@example.com -o encrypted.gpg plaintext.txt

# Decrypt
gpg --decrypt encrypted.gpg > plaintext.txt
```

## Common Failures

| Failure | Cause | Fix |
|---|---|---|
| No forward secrecy | Static key pairs for all messages | Ephemeral key exchange per session |
| Key distribution insecure | Public keys over untrusted channel | Key verification (safety numbers) |
| DEK reuse | Same DEK for multiple files | Unique DEK per encryption operation |
| Missing authentication | Encryption without MAC | Use AES-GCM or ChaCha20-Poly1305 |

## Workflow

1. **Design** — Define threat model and select E2EE protocol
2. **Key Generation** — Generate identity and ephemeral key pairs
3. **Key Exchange** — Implement secure key agreement (X3DH/ECDH)
4. **Encrypt** — Implement message/file encryption with AEAD
5. **Verify** — Test decryption, rotation, and forward secrecy
6. **Audit** — Review for cryptographic correctness

## Verification

| Check | Method |
|---|---|
| Forward secrecy | Compromising long-term key won't decrypt past messages |
| Authenticated encryption | All ciphertext uses AEAD |
| Unique keys per message | Ephemeral or ratcheted keys used |
| Key verification | Users can verify peer identity out-of-band |

## References

- [Signal Protocol Specification](https://signal.org/docs/)
- [RFC 7748 — X25519 Key Agreement](https://datatracker.ietf.org/doc/html/rfc7748)
- [RFC 5116 — AEAD Interface](https://datatracker.ietf.org/doc/html/rfc5116)
- [age Encryption Tool](https://age-encryption.org/)
