Skip to content

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

L2TP/IPsec VPN for Android

A native Android L2TP/IPsec PSK client that runs entirely in userland — no root, no strongSwan, no kernel xfrm state, no WireGuard proxy. Android removed its built-in L2TP/IPsec support in Android 12, leaving IKEv2/IPsec as the only option; this app puts L2TP/IPsec back on the device for routers that offer nothing else. It was written for an Orange Livebox Pro fibre router, which offers L2TP/IPsec PSK and nothing else.

Every layer of the stack — ISAKMP/IKEv1, ESP, L2TPv2, PPP — is implemented in Kotlin inside the app process, on top of one ordinary UDP socket.

Provenance: this was written entirely by an AI

100 % of this repository was written by Claude (Anthropic's model) — the protocol stack, the Android app, every test, the Docker lab and all of this documentation. It was produced in one extended session from a prompt describing the problem, written against the RFCs rather than ported from an existing L2TP/IPsec implementation. No line was hand-written afterwards.

The human set the goal and the constraints, supplied the hardware, ran the app on a real Galaxy S25+ against a real Orange Livebox Pro, pasted the logcat back, and made the product calls — such as removing the plaintext credential fallback. That loop is what found three defects no test had caught: a reconnect loop that tore the tunnel down 27 ms after it came up, a teardown that never reached the router, and an MTU that ignored the peer's advertised MRU.

What that means if you are considering using it. It has been verified by execution, not merely generated: it establishes a real tunnel against a real router and against a strongSwan lab, and the tests pin the RFC vectors. But no human expert has reviewed the IKEv1 or ESP code. Read it before you trust it, and judge it on the code and the tests rather than on where it came from.

The layering

UDP/4500 datagram                    the only socket, VpnService.protect()ed
  └─ ESP transport mode              RFC 4303 + RFC 3948 UDP encapsulation
      └─ UDP 1701 → 1701             transport mode: there is NO inner IP header
          └─ L2TPv2 data message     RFC 2661
              └─ PPP frame           RFC 1661 / 1332 / 1994 / 2759
                  └─ the user's IP packet, from/to the VpnService TUN

Three consequences drive most of the design, and each is explained in docs/protocol.md:

  • ESP is always UDP-encapsulated. An unprivileged Android app cannot open a raw IP socket, so it can never send IP-protocol-50 ESP. The client forces encapsulation by computing its source NAT-D hash over port 0 — exactly strongSwan's forceencaps=yes. This is a requirement, not an optimisation.
  • There is no inner IP header. ESP runs in transport mode, so the protected data is the UDP/1701 datagram itself. The ICV covers the ESP header, IV and ciphertext but not the IP header, which is why NAT rewriting on the path is harmless.
  • The inner UDP checksum is zero. IPv4 permits it, and it side-steps the RFC 3948 §3.1.2 checksum fix-up. Linux's own L2TP implementation does the same.

Modules

core/         pure Kotlin/JVM — the whole protocol stack, no Android SDK, unit-testable
  util/         bounds-checked big-endian readers/writers, hex helpers, logging seam
  crypto/       DH MODP groups, HMAC PRF and key expansion, CBC ciphers, algorithm vocabulary
  ike/          ISAKMP codec, IKEv1 main/aggressive mode, quick mode, NAT-T, DPD, Delete
  esp/          ESP transport-mode encode/decode, anti-replay window, UDP-encapsulation framing
  net/          IPv4/UDP codecs and the internet checksum
  l2tp/         L2TPv2 AVPs, control channel with Ns/Nr and retransmission, data path
  ppp/          LCP, PAP / CHAP-MD5 / MS-CHAPv2 (with its own MD4), IPCP with RFC 1877 DNS
  tunnel/       VpnConfig, platform seams, MTU budgeting, and L2tpIpsecTunnel which drives it all
app/          Android — VpnService, platform adapters, encrypted profile + credential storage, Compose UI
testserver/   a real strongSwan + xl2tpd + pppd lab in Docker, driven by the live tests

Keeping the stack in a plain JVM module is what makes it testable: the entire client can be driven against a real server from a JUnit test, with ordinary DatagramSockets and an in-memory TUN.

Defaults

Phase Proposal
IKE phase 1 aes256-sha256-modp2048 — AES-256-CBC, HMAC-SHA-256, DH group 14, PSK, main mode
IPsec phase 2 aes256-sha256 — AES-256-CBC + HMAC-SHA-256-128, ESP transport mode, no PFS
PPP auth MS-CHAPv2, then CHAP-MD5, then PAP

These match the Livebox Pro exactly; see docs/interoperability.md.

Building and running

./gradlew :core:test          # protocol unit tests (the live ones self-skip)
./gradlew :app:test           # Android-free app-layer tests
./gradlew :app:assembleDebug  # APK at app/build/outputs/apk/debug/

Requires the Android SDK (compileSdk 37, minSdk 26) and a JDK the Gradle wrapper accepts. The Kotlin Android plugin is deliberately absent from :app — AGP supplies Kotlin for Android modules itself.

A signed release build

./gradlew :app:assembleRelease works out of the box and produces an unsigned APK, which Android will not install. To get an installable one, generate a key and point the build at it. The keystore belongs outside this repository; keystore.properties, *.jks and friends are gitignored as a safety net, not as the plan.

mkdir -p ~/keystores
keytool -genkeypair -v \
    -keystore ~/keystores/l2tpvpn-release.jks \
    -storetype PKCS12 -alias l2tpvpn \
    -keyalg RSA -keysize 4096 -validity 10000

cp keystore.properties.example keystore.properties   # then fill it in
./gradlew :app:assembleRelease

keytool asks for the password interactively, so it never reaches a shell history or a build file. With PKCS12 the key password must equal the store password. Verify the result with apksigner verify --verbose --print-certs app/build/outputs/apk/release/app-release.apk; it should report v2 and v3 signatures.

Keep the key. Android refuses an update signed by a different one, so losing it means uninstall and reinstall — which wipes the saved profiles and their credentials. Leaking it means anyone can sign an update that installs cleanly over yours.

Release builds from CI

.github/workflows/release-apk.yml runs on every push to master: the unit tests and an unsigned assembleRelease in one job, then signing in a second job, then a GitHub release tagged build-<run number> with the APK attached. The newest one is always at https://github.com/Flo354/L2TP-IPSec-VPN-for-Android/releases/latest/download/L2TP-IPSec-VPN.apk, and its release notes give the signing certificate's SHA-256 so a download can be checked with apksigner verify --print-certs.

CI signs with a key of its own, not the one above, kept as secrets of a release environment that only master can use. The signing job never runs code from the repository, so a poisoned build script, test or dependency has no way to reach the key. Because the keys differ, an APK from CI and a local release build will not install over each other.

Read docs/release-pipeline.md before setting it up or changing the workflow. It covers generating the CI key, the three secrets, the repository settings the workflow cannot enforce by itself — without them part of the protection does nothing — and the poisoned pipeline execution threat model behind every rule.

On the device: create a profile — server address, pre-shared key, user name and password — and press Connect. Several profiles can be saved, with one marked active; they can be edited, duplicated and deleted. The advanced section exposes the phase 1 / phase 2 proposals, exchange mode, local identity, PPP authentication list, MTU, DNS override and the IPv6 blackhole. Full field reference in docs/configuration.md.

A saved pre-shared key or password can never be displayed again. The credentials live in a store the UI is handed without a getter, so a screen has no way to read one back; a saved field offers Replace and Clear rather than a masked value. What that protects against, and what it does not, is in docs/security.md.

Status

Verified against the Docker lab in testserver/ (strongSwan + xl2tpd + pppd configured like the target router) and against the real Livebox Pro:

Check Result
Tunnel establishment IKE phase 1 → phase 2 → L2TP → PPP → TUN, end to end
Data path ICMP echo round-trips through the whole stack
PPP authentication PAP, CHAP-MD5 and MS-CHAPv2 all negotiate and authenticate
Rekeying both SAs replaced, by us and by the server, without interrupting traffic
Wrong PSK / wrong password fail fast with distinguishable, actionable errors
Test suite :core and :app both green; the handful of live tests self-skip without the lab
Static analysis :app:lintDebug reports no issues; both modules compile without warnings
Credential storage not verified on a device — read-only review plus plain-JVM tests against a fake store, because AndroidKeyStore does not exist off-device

Known limitations are listed honestly in each document, and collected in docs/architecture.md. The credential handling has its own honest account in docs/security.md.

Documentation

Document What it covers
docs/architecture.md Module layout, the layering, the threading model, the platform seams
docs/protocol.md What is implemented at each layer, with RFCs — and the non-obvious decisions
docs/rekeying.md SA lifetimes, the jittered deadline, make-before-break, what is not covered
docs/android.md VpnService lifecycle, protect(), foreground service, profile storage, reconnect, the traps
docs/configuration.md Every field of VpnConfig and VpnProfile, the two secrets, the validation rules
docs/security.md What protects the credentials, the threat model, the never-reveal guarantee, and what is not claimed
docs/release-pipeline.md The CI release workflow, its signing key, poisoned pipeline execution and the repository settings that keep the key safe
docs/testing.md Hermetic tests, the Docker lab, how to run each suite
docs/troubleshooting.md Getting logs off a device, every TunnelErrorKind, observed symptoms
docs/interoperability.md The Livebox Pro's settings, and what the lab taught us about strongSwan and xl2tpd

docs/README.md is the index, with suggested reading orders.

testserver/CLIENT_NOTES.md holds the raw byte-level findings from the lab and is worth reading before touching anything on the wire.

Licence

MIT. Note the warranty disclaimer that comes with it, and read the provenance note above before deciding what that is worth to you.

About

No description, website, or topics provided.

Resources

Security policy

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages