# 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.