Linux + iPhone Continuity / iMessage / SMS
docs: clarify TLS use
Zack Bartel384c0b8d9934
diff --git a/.github/SECURITY.md b/.github/SECURITY.mdindex 7c3f0db..d8ae973 100644--- a/.github/SECURITY.md+++ b/.github/SECURITY.md@@ -54,7 +54,7 @@ Check what you are running with `tether --version` and compare against theThe parts of Tether where a bug is a security bug:-- **Pairing and mTLS.** Certificate and key handling+- **Pairing and TLS.** Certificate and key handling(`~/.config/tether/cert.pem`, `key.pem`, `known_hosts.json`), the pairingapproval flow, and anything that lets an unpaired peer be trusted, or apaired peer be impersonated.diff --git a/README.md b/README.mdindex 2b325ab..e291bf7 100644--- a/README.md+++ b/README.md@@ -50,7 +50,7 @@ There are two ways tether communicates with the iPhone:You can use either or both, depending on your needs.-Connections use Mutually Authenticated TLS (mTLS), restricting TCP traffic securely using X.509 RSA certificates.+Connections run over TLS 1.2 and both sides present a self-signed X.509 certificate.### OTP HandlingStreamline two-factor authentication across your devices:@@ -229,7 +229,7 @@ make install## Components-1. **`tetherd`**: A background process running on Linux manages Bluetooth, TCP+mTLS, and Wayland integration.+1. **`tetherd`**: A background process running on Linux manages Bluetooth, TCP+TLS with pinned device certificates, and Wayland integration.2. **`tether`**: A CLI to communicate with the daemon. This also allows the WebExtension to interface with the daemon via native messaging.diff --git a/docs/PROTOCOL.md b/docs/PROTOCOL.mdindex 676d9d5..202cdde 100644--- a/docs/PROTOCOL.md+++ b/docs/PROTOCOL.md@@ -124,9 +124,13 @@ For local Unix clients, `tetherd` returns `file_status` once the stream has been----## 3. Device Pairing (mTLS)+## 3. Device Pairing (TLS + fingerprint pinning)-Because the `tetherd` daemon natively binds to `0.0.0.0:5134` over TCP, it explicitly employs OpenSSL **Mutually Authenticated TLS (mTLS)** to natively reject malicious local-network payloads.+The `tetherd` daemon binds `0.0.0.0:5134` and speaks TLS 1.2. Both sides present a self-signed X.509 certificate; there is no CA in this system, so certificates are **not** validated against any trust anchor.++Access control is trust-on-first-use fingerprint pinning. After the handshake the daemon takes the SHA-256 fingerprint of the peer's certificate and looks it up in `known_hosts.json`. A client whose fingerprint is not pinned may only send `pair_request` — any other command is answered with `{"command":"error","message":"unauthorized"}`.++TLS still verifies the peer's `CertificateVerify` signature, so a pinned fingerprint proves the peer holds the matching private key. An attacker on the same network cannot impersonate a paired device without that key, but they can open a connection and sit at the pairing prompt.### `pair_request` (Untrusted Client -> Daemon)@@ -151,7 +155,7 @@ Because the `tetherd` daemon natively binds to `0.0.0.0:5134` over TCP, it expli}```-Once explicitly paired (via `tether --accept <fingerprint>`), native mTLS fingerprint-matching activates permanently, unblocking future payload operations instantly!+Once paired (via `tether --accept <fingerprint>`), the fingerprint is written to `known_hosts.json`. Later connections presenting that certificate are treated as paired and may issue any command.---@@ -165,7 +169,7 @@ Instructs the daemon to perform a synchronous mDNS scan (3 seconds) in a backgro**Response**: The daemon broadcasts a `discovery_result` payload asynchronously containing an array of active `devices`.### `pair_request` (Local Client -> Daemon)-Instructs the daemon to asynchronously reach out to a specific host to initiate an mTLS pairing request.+Instructs the daemon to asynchronously reach out to a specific host to initiate a TLS pairing request.**Payload**: `{"command": "pair_request", "host": "192.168.1.5", "port": 5134}`### `accept_device` (Local Client -> Daemon)diff --git a/docs/man/man8/tetherd.8.in b/docs/man/man8/tetherd.8.inindex f5d3d5b..0269fdd 100644--- a/docs/man/man8/tetherd.8.in+++ b/docs/man/man8/tetherd.8.in@@ -7,7 +7,7 @@ tetherd \- Tether background daemon for iOS/Wayland integration.B tetherdis a background daemon that manages the connection between a Linux Waylandcompositor and an iOS device running the Tether app. It handles clipboard-synchronization, file transfers, and secure device pairing using mTLS.+synchronization, file transfers, and device pairing using TLS with pinned certificates.The daemon advertises its presence on the local network using mDNS (Bonjour)and listens for incoming connections on TCP port 5134 by default. It also@@ -21,8 +21,9 @@ The UNIX domain socket used for local communication.\fB$XDG_RUNTIME_DIR/tether/tetherd.lock\fRAdvisory lock file to ensure only one instance of the daemon is running..TP-\fB$XDG_CONFIG_HOME/tether/certs/\fR-Directory containing the mTLS certificates and keys.+\fB~/.config/tether/\fR+Directory containing the TLS certificate (\fBcert.pem\fR), private key (\fBkey.pem\fR),+and pinned device fingerprints (\fBknown_hosts.json\fR)..SH SEE ALSO.BR tether (1),.BR tether-gtk (1)diff --git a/src/core/src/crypto.cpp b/src/core/src/crypto.cppindex ae3b3c4..c0a8e27 100644--- a/src/core/src/crypto.cpp+++ b/src/core/src/crypto.cpp@@ -68,7 +68,9 @@ namespace tether {if (!SSL_CTX_check_private_key(server_ctx_))return false;- // Mutually Authenticate, but accept anything to allow pairing request processing+ // Require a peer certificate but accept any chain: both peers are self-signed and there is+ // no CA. Identity comes from pinning the peer's fingerprint against known_hosts.json in+ // TcpServer::handle_client.SSL_CTX_set_verify(server_ctx_, SSL_VERIFY_PEER | SSL_VERIFY_FAIL_IF_NO_PEER_CERT, [](int, X509_STORE_CTX*) { return 1; });@@ -84,6 +86,7 @@ namespace tether {SSL_CTX_use_certificate_file(client_ctx_, cert_path_.c_str(), SSL_FILETYPE_PEM);SSL_CTX_use_PrivateKey_file(client_ctx_, key_path_.c_str(), SSL_FILETYPE_PEM);+ // Same as the server context: the chain is not validated, the peer's pinned fingerprint is.SSL_CTX_set_verify(client_ctx_, SSL_VERIFY_PEER, [](int, X509_STORE_CTX*) { return 1; });// Derive my fingerprint