tlskit/spec.md

tlskit — spec

The short contract for working on the shared HTTP/TLS client. README.md explains its use; this file says what it promises to the apps that copy it.

Goal

Let Android 2.2/2.3 apps reach modern https:// servers (TLS 1.2, today's roots, SNI), which the system's own TLS 1.0 stack can't.

Users

Copied into: Plexamp Lite, Podlite, Noticias Lite, Calendar Lite (by hand, under android/org/gingercal/net), AcasaLite, Tenda Lite and WikipeLite. The apps carry copies, not a dependency.

What it provides

• net/Http.java: HTTP/1.1 on Bouncy Castle TLS 1.2 (renamed com.minamp.bc), keep-alive pooling, session resumption, chunked bodies.
• net/CertVerifier.java: host name, validity dates, chain up to a bundled Mozilla root (trust anchors must be CAs); optionally one pinned leaf certificate (SHA-256), with the fingerprint shown to the user. Untrusted errors carry the chain.
• net/AssetRoots.java + roots/: Mozilla's roots as assets/roots/<sha1(subject)>-<n>.der; loaded roots are kept in memory and a failed read is retried.
• net/Threads.java: threads with a 256 KB stack; network work must run on one.
• net/DiagLog.java: connection log with tokens removed from URLs.

Must not break

• Must run on Dalvik for API 8: no newer Java or Android APIs.
• Must not clash with the old Bouncy Castle inside Android (keep the com.minamp.bc rename).
• Never log tokens or passwords.
• A change here is not done until it has been reinstalled into every app above and each one rebuilt (and released through Tenda).

Workflow

• ./install.sh <app dir> <java package> copies net/ into the app's package and roots/ into its assets/.
• Bouncy Castle sources come from Plexamp Lite's tools/setup_toolchain.sh (~/android-toolchain/bcsrc); roots are regenerated with Plexamp Lite's tools/make_roots.py.
• Test: test/KitTest.java on a desktop JVM against real FreshRSS, Nextcloud and Audiobookshelf servers.