https://github.com/merlos/openme
Open your firewall with a single encrypted packet. Nothing else is ever visible.
https://github.com/merlos/openme
android apple-watch iphone linux macos single-packet-authorization windows
Last synced: 3 months ago
JSON representation
Open your firewall with a single encrypted packet. Nothing else is ever visible.
- Host: GitHub
- URL: https://github.com/merlos/openme
- Owner: merlos
- License: mit
- Created: 2023-07-15T05:25:34.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-03-18T03:56:44.000Z (4 months ago)
- Last Synced: 2026-03-18T09:28:40.263Z (4 months ago)
- Topics: android, apple-watch, iphone, linux, macos, single-packet-authorization, windows
- Language: Swift
- Homepage: https://openme.merlos.org
- Size: 621 KB
- Stars: 5
- Watchers: 1
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Security: docs/security/index.qmd
Awesome Lists containing this project
README
# openme
> Open your firewall with a single encrypted packet. Nothing else is ever visible.
openme is a **Single Packet Authentication (SPA)** tool. To a port scanner, every port is always closed. Only clients holding a valid Ed25519 key can send a knock that temporarily opens a firewall rule — and the knock itself looks like random noise on the wire.
```
Client Server (port always CLOSED to scanners)
│ │
│──── 165 bytes of encrypted UDP ────>│ verify signature
│ │ decrypt payload
│ │ open firewall rule for 30s
│<══════════ SSH / HTTPS / etc. ══════│
```
---
## Repository Layout
```
openme/
├── cli/ Go server daemon + cross-platform CLI
├── apple/
│ ├── OpenMeKit/ Swift package — shared SPA client library (iOS, macOS, watchOS)
│ ├── openme-ios/ iOS app (SwiftUI, Profiles, QR/YAML import, knock widget)
│ ├── openme-macos/ macOS app (SwiftUI menu-bar, Profiles, AppleScript post-knock)
│ ├── openme-watch/ watchOS app (WatchConnectivity sync from iPhone)
│ ├── openme-widget/ iOS/macOS WidgetKit widget (one-tap knock from home screen)
│ └── openme.xcworkspace/
├── android/
│ ├── openmekit/ Kotlin library — SPA protocol, profile storage, YAML/QR import
│ └── app/ Android app (Jetpack Compose, Material 3)
├── windows/
│ ├── OpenMeKit/ .NET client library (Kotlin-equivalent)
│ ├── openme-windows/ WPF system-tray application
│ └── OpenMeKit.Tests/
├── c/
│ └── openmelib/ Pure C99 SPA client library (ESP32, Arduino, Linux, macOS, Windows)
├── docs/ Quarto documentation site → openme.merlos.org/docs/
└── website/ Marketing landing page → openme.merlos.org
```
---
## Getting Started with the CLI
### Install
```bash
# Build from source (requires Go 1.21+)
git clone https://github.com/merlos/openme
cd openme/cli
go mod download
go build -o openme ./cmd/openme
sudo mv openme /usr/local/bin/
```
Pre-built binaries for Linux, macOS and Windows are available on the [Releases](https://github.com/merlos/openme/releases) page.
### Server setup
```bash
# 1. Initialise — generates keys and writes /etc/openme/config.yaml
sudo openme init --server myserver.example.com
# 2. Register a client
sudo openme add alice
# 3. Start the server
sudo openme serve
```
`openme add alice` prints a ready-to-use client config block and an optional QR code. Copy it to `~/.openme/config.yaml` on the client machine.
### Client usage
```bash
# Check the server is reachable
openme status
# Send a knock (opens firewall for your source IP)
openme knock
# Knock a named profile, then SSH automatically
openme knock home
# Knock to open for a specific IP instead of your source IP
openme knock --ip 10.0.0.5
```
See [cli/README.md](cli/README.md) for the full CLI reference, configuration options, and cross-compilation instructions.
---
## Documentation
The full documentation is published at **[openme.merlos.org/docs](https://openme.merlos.org/docs)**.
| Section | Description |
|---------|-------------|
| [Protocol](https://openme.merlos.org/docs/protocol/) | Wire format, cryptographic design, security properties |
| [Getting Started](https://openme.merlos.org/docs/getting-started/) | Step-by-step server and client setup |
| [Configuration](https://openme.merlos.org/docs/configuration/) | All config options for server and client |
| [Security Model](https://openme.merlos.org/docs/security/) | Threat model, what is and isn't protected |
| [FAQ](https://openme.merlos.org/docs/faq/) | Common questions |
| [For Developers](https://openme.merlos.org/docs/developer/) | Documentation For developers |
To build and preview the docs locally:
```bash
cd docs
quarto preview
```
---
## Platform Status
| Platform | Status | Notes |
|----------|--------|-------|
| Linux (CLI + server) | ✅ Active | iptables & nftables |
| macOS (CLI client) | ✅ Active | Cross-compiled from Go |
| Windows (CLI client) | ✅ Active | Cross-compiled from Go |
| Windows GUI | ✅ Active | WPF system-tray app (.NET 8) |
| macOS GUI | ✅ Active | SwiftUI menu bar app |
| Android | ✅ Active | Jetpack Compose app |
| iOS | ✅ Active | SwiftUI app (iPhone/iPad) |
---
## Contributing
Each platform has its own subdirectory, build toolchain and README. Start with the directory most relevant to what you want to work on. All cryptographic protocol changes should be discussed in an issue first.
## License
MIT — see [LICENSE](LICENSE).