Kindling

Kindling

Get the first bytes through a censored network.

Kindling is a Go library that fetches small things, like config files, through firewalls that block everything you'd normally try. It races several circumvention techniques at once and hands your request to whichever connects first. You get back an ordinary http.Client.

One request, every route at once

Domain fronting, proxyless dialing and the AMP cache start connecting at once, and the first to connect carries the request. The Soar DNS tunnel starts only if all three fail.

Illustrative timings.

● The bootstrap problem

Before a VPN can connect, it has to phone home

Every circumvention app starts the same way: it needs a config file, a list of servers, or a login check before it can do anything else. On a censored network that first request is the easiest one to block, because it goes to a known address before any tunnel is up.

Kindling exists for that one request. It isn't a VPN and doesn't carry your traffic. It gets a few kilobytes in and out reliably, so the app that uses it can get going.

  1. App opensNo servers known yet, nothing cached on a fresh install.
  2. Fetch config · kindlingRaced over every technique that might work on this network.
  3. Pick a proxyNow the app knows where its servers are.
  4. Tunnel upNormal traffic flows through the app's own protocols.
● Transports

Four ways through, and room for yours

Each technique beats a different kind of blocking. None works everywhere, which is why kindling runs them together.

domainfrontTier 1

Domain fronting

Connects to a large CDN under an innocuous server name, then asks for the real origin inside the encrypted request. Blocking it means blocking the CDN. Kindling only counts a front as connected after a real TLS handshake, so a dead front can't win the race.

streaming okconfig refreshed remotely
smartTier 1

Proxyless dialing

The Outline SDK smart dialer connects straight to the destination and searches for a trick that gets past DNS and SNI blocking:

  • DNS over HTTPS through a dozen resolvers
  • TCP stream splitting and out-of-order segments
  • TLS record fragmentation
ampTier 1

AMP cache

Rides Google's AMP cache, a technique introduced by David Fifield, with Lantern's implementation. Censors that need Google can't block it cleanly. Request bodies are capped, so kindling routes only small requests here.

bodies ≤ 6,000 bytesno streaming
soarLast resort

Soar DNS tunnel

Soar carries the request inside DNS queries through whatever resolvers the network allows, including in Russia, where UDP is intercepted, and in China, where forged answers are injected. It's slower than the others, so kindling holds it back: it joins after 8 seconds without a response, or at once if every tier 1 transport has failed.

works when only DNS doesconnects in under 1 s
WithTransport(…)Tier 1 by default

Your transport

Anything that can return an http.RoundTripper can join the race. Implement the Transport interface, returning 0 from MaxLength() and RequestTimeout() for no cap and the default timeout, and add an optional Priority() int to race in a later tier or StartDelay() time.Duration to join late. Kindling handles the racing, retries and timeouts.

● How the race works

Race the connections, send the request once

Filter

Transports that can't carry this request are skipped: a body over a transport's size cap, or a streaming request on a transport that can't stream.

Race a tier

Every transport in the first tier starts connecting at once. Transports pre-connect, so the race measures real reachability on this network.

Send once

The first transport to connect gets the request. Requests are sent one at a time, so a POST can't hit the server twice. The one exception is a replay-safe request once a transport has joined late: from then on, each connection sends as soon as it's up, so a request that's hanging doesn't hold up the rest.

Fall back

If the whole tier fails, the next tier starts at once. A transport with a start delay also joins once its delay passes, so a tier that hangs instead of failing doesn't hold it up. That's how Soar stays out of the way on networks where faster routes work, and still arrives where they don't.

RequestConnection failsTransport error, 5xx or 403Other 4xx
GET, HEADnext transportnext transportreturned as-is
POST, PUT, DELETE…next transportreturned as-isreturned as-is
with X-Kindling-Idempotentnext transportnext transportreturned as-is
A connection that never came up carried no body, so it's always safe to try the next one. Once a body has crossed the wire, kindling replays it only when the method is safe or you set X-Kindling-Idempotent. A 403 counts as a failure because CDN fronts often send one when they refuse a country on one path only.
● Code

An http.Client that finds its own way out

go get github.com/getlantern/kindling, pick your transports, and use the client like any other.

Using kindling
k, err := kindling.NewKindling("myapp",
	kindling.WithDomainFronting(df),
	kindling.WithProxyless("raw.githubusercontent.com"),
	kindling.WithAMPCache(ampClient),
	kindling.WithDNSTunnel(soarClient), // last resort
)
if err != nil {
	return err
}

client := k.NewHTTPClient()
resp, err := client.Get(configURL)
if err != nil {
	return err
}
defer resp.Body.Close()
Bring your own
type Transport interface {
	// Return a pre-connected RoundTripper.
	NewRoundTripper(ctx context.Context,
		addr string) (http.RoundTripper, error)
	MaxLength() int                // max body, 0 = no limit
	IsStreamable() bool            // can carry text/event-stream
	Name() string
	RequestTimeout() time.Duration // 0 = kindling's default
}

// Optional: race in a later tier.
//   Priority() int
kindling.WithTransport(myTransport)

Add fuel to the fire

Got a technique that gets through somewhere? Wrap it as a Transport and open a pull request. Note any server-side pieces it needs, and every tool built on kindling gets the new route.

● FAQ

Questions people ask about Kindling

What is Kindling?

Kindling is an open-source Go library from Lantern that sends and receives small amounts of data, like configuration files, through censoring firewalls. It races several circumvention techniques (domain fronting, proxyless dialing and Google's AMP cache, with the Soar DNS tunnel held back as a last resort) and sends the request over whichever connects first. Your code gets back an ordinary Go http.Client.

Is Kindling a VPN?

No. Kindling doesn't carry your browsing. It gets a circumvention app's first requests, such as fetching its configuration or its list of servers, through a censored network, so the app can start its own tunnel. If you want a VPN, download Lantern.

Which circumvention techniques does Kindling use?

Four, plus any you add. Domain fronting reaches the real origin through a large CDN under another server name. Proxyless dialing uses the Outline SDK's smart dialer, which tries DNS over HTTPS, TCP stream splitting and TLS record fragmentation to get past DNS and SNI blocking. The AMP cache transport uses Lantern's amp library to go through Google's AMP cache. Soar, a DNS tunnel, is the last resort.

How does Kindling choose which technique to use?

It doesn't choose in advance. Every transport in the first tier without a start delay begins connecting at the same time, so the race measures what actually works on the network the app is on, and the first to connect carries the request. If every transport in the tier fails, the next tier joins at once, and a transport with a start delay joins when its delay passes. WithRaceObserver reports how each race went: which transport won, and what happened to each one tried.

When does Kindling use the DNS tunnel?

Only as a last resort. DNS tunnelling keeps working under heavy censorship but is slow, so Soar joins the race 8 seconds into a request, or as soon as every faster transport has failed, whichever comes first. The delay is there because censored networks often drop packets instead of refusing connections, so the faster transports can hang rather than fail. WithStartDelay changes it.

Will Kindling send a POST request twice?

Not unless you say it's safe. A request that isn't safe to replay is sent once, on the first transport to connect, and its response is returned whatever it is. Failing to connect always moves on to the next transport, because no body was sent. GET and HEAD requests, and requests with the X-Kindling-Idempotent header, also move on after a transport error, a 5xx or a 403, so set that header only on a POST the server can safely receive twice. Other 4xx responses are returned as they are.

How much data can Kindling send?

Kindling is built for small requests, such as config fetches and status checks, not bulk traffic. Each transport declares its own limits: the AMP cache takes request bodies up to 6,000 bytes and can't stream, so Kindling skips it for larger bodies and for streaming requests (those with Accept: text/event-stream).

How does Kindling relate to the Outline SDK?

Kindling's proxyless transport is the Outline SDK smart dialer, which connects straight to the destination and searches for a DNS and TLS strategy that gets through. Kindling races it alongside domain fronting, the AMP cache and DNS tunnelling, so the request has other routes on networks where no proxyless strategy works.

Why not just use domain fronting?

Each technique beats a different kind of blocking, and none works everywhere. A domain front fails if that CDN path is blocked or refuses the client's country. Proxyless dialing works best for widely used services whose addresses aren't blocked. The AMP cache only carries small requests. Kindling runs them together, so one blocked route doesn't fail the request.

How do I use Kindling in a Go program?

Run go get github.com/getlantern/kindling, create a client with kindling.NewKindling and the transports you want (WithDomainFronting, WithProxyless, WithAMPCache, WithDNSTunnel), then call NewHTTPClient() and use the result like any http.Client. See the code examples.

Can I add my own circumvention technique?

Yes. Anything that can return a pre-connected http.RoundTripper can join the race: implement the Transport interface and pass it to WithTransport. Add Priority() int to race in a later tier, or StartDelay() time.Duration to join late. Pull requests for new techniques are welcome on GitHub.

Does Lantern use Kindling?

Yes. Lantern's client backend, radiance, uses Kindling to fetch its configuration. Kindling is meant for any circumvention tool written in Go that needs to fetch configuration reliably on startup.

Is Kindling open source?

Yes. Kindling is written in Go and released under the Apache License 2.0 at github.com/getlantern/kindling.

Who makes Kindling?

The Lantern team, at Brave New Software Project, Inc., which makes the Lantern VPN and censorship-circumvention app.