5.8 KiB
Open Madrid
An open implementation of Apple's madrid protocol (iMessage).
This repository is a clean-room, plain-old-open-source implementation of the iMessage protocol in Kotlin: the binary and XML property-list codecs, the APNs "courier" push client, the IDS identity service, the encryption envelope, and the full registration/activation chain.
Unlike open-absinthe, whose public repository contains a mock placeholder and no actual functionality, everything here is readable, and licensed.
Why another project?
Unlike other projects, Open Madrid's is a permissively licensed (Apache-2.0), dependency-light, fully readable implementation of the protocol. Facts about the protocol live in a spec (docs/imessage-protocol-spec.md). Almost every existing route to iMessage is closed in some way:
| Project | What it is | The catch |
|---|---|---|
| Open-Madrid | Kotlin open-source implementation | None |
| rustpush | The maintained engine (Rust) | SSPL license |
| pypush | The original Python PoC | SSPL license |
| imessagego | Go implementation | AGPL (the only ordinary open-source license in the space) |
| BlueBubbles | A working client | Needs a Mac running 24/7 to relay and decrypt |
| OpenBubbles | The validation-data layer | Depends on closed-source open-absinthe |
What is validated
- The parsers handle real Apple bytes. The actual 405-entry IDS bag and 65-entry APNs bag, captured from a registered device, are committed as test fixtures and decoded with exact-value assertions.
- Two live, unauthenticated probes against Apple succeeded: both bag endpoints return valid
plists this stack parses, and the certificate pinning validates Apple's real TLS chains. A
recurring drift check ships with the repo (
:engine:runProbe). - The courier's auth model is settled: the TLS handshake succeeds, then the server demands
the Albert client certificate (a TLS 1.3 post-handshake
certificate_requiredalert). - The registration chain runs end-to-end against scripted Apple responses (a full dry-run test).
- The protocol around it is proven live by this project's private sibling implementation:
a working device-identity chain (Apple's validation endpoint, key establishment, the 645-byte
validation blob), and — as of 2026-09-29 — the full GSA login against Apple's live endpoints
with a real Apple ID: SRP, trusted-device 2FA, the PET delivery (both live-confirmed
channels), and the delegate sign-in request shape. Those findings are folded into the spec
here (rev 25). The sign-in itself is currently refused by Apple with
ICLOUD_UNSUPPORTED_DEVICE(a device-identity-bound iCloud-activation limit) — recorded as the spec's first documented live refusal, not a protocol gap.
What is not validated (yet)
- Nothing has registered a real device or sent a real message. First live activation is the next milestone.
- The crypto envelopes have round-trip tests but no known-answer vectors captured from a live device.
- A few wire details remain capture-bound guesses, tracked in the spec's open-questions checklist.
- PQ3 (Apple's newer post-quantum encryption) is unsupported (today).
Keeping the license clean (read this before contributing)
This is a clean-room: contributors never read the source of rustpush, pypush, imessagego, or their forks. Two roles, kept strictly apart:
- Readers study the existing projects. Their only output is the spec, a plain-language protocol notes with cited sources.
- Writers work only from the spec, Apple's own documentation, and recordings of their own device's traffic. Don't open the other projects' source, don't read their diffs or issues when debugging, and don't paste their identifiers into commits or issues.
Why: it keeps this code fully open, acceptable to F-Droid and other distribution channels, and safe to embed anywhere.
The Apple-material rule
No Apple-derived code or binary ships in this repository. This includes the IMDAppleServices framework and Apple's FairPlay identity. The bundled identity under
registration/src/main/resources/imessage/fairplay/ is a synthetic placeholder (generated, self-signed, for tests only). Live activation requires Apple's real FairPlay identity and registration framework, which each user stages themselves.
Building
Standalone — no sibling checkouts required:
./gradlew build # all modules + the full test suite
./gradlew :engine:runProbe # the live drift check (unauthenticated bag/cert probes)
License
Support my work by leaving me a tip or sponsoring me. A little goes a long way.