⚠️ Warning: This code is in early stages and is not guaranteed to be stable. If you are interested in integrating with it, we'd love your feedback.

The Outline SDK allows you to:

• Create tools to protect against network-level interference.
• Add network-level interference protection to existing apps, such as content or communication apps.

We are working on a new DNS library that will let people bypass DNS-based blocking by using alternative resolvers and ports, and encrypted DNS (DNS-over-HTTPS and DNS-over-TLS).

The Outline SDK offers several strategies for evading SNI-based blocking:

At the TCP layer:

• TCP stream fragmentation with transport/split
• TLS record fragmentation with transport/tlsfrag

At the application layer:

• Domain-fronting and SNI hiding with transport/tls

The Outline SDK offers two protocols to create connections over proxies:

• Shadowsocks, available in transport/shadowsocks. Easily create servers in the cloud using the Outline Manager.
• SOCKS5, available in transport/socks5. You can leverage a local SOCKS5 proxy that tunnels connections over SSH.

Use the network package to create TUN-based VPNs using transport-layer proxies (often called "tun2socks").

Choose from one of the following methods to integrate the Outline SDK into your project:

• Generated Mobile Library: For Android, iOS, and macOS apps. Uses gomobile bind to generate Java and Objective-C bindings.
• Side Service: For desktop and Android apps. Runs a standalone Go binary that your application communicates with (not available on iOS due to subprocess limitations).
• Go Library: Directly import the SDK into your Go application. API Reference.
• Generated C Library: Generate C bindings using go build.

The Outline Client uses a generated mobile library on Android, iOS and macOS (based on Cordova) and a side service on Windows and Linux (based on Electron).

Below we provide more details on each integration approach. For more details about setting up and using Outline SDK features, see the Discussions tab.

To integrate the SDK into a mobile app, follow these steps:

1. Create a Go library: Create a Go package that wraps the SDK functionalities you need.
2. Generate mobile library: Use gomobile bind to generate Android Archives (AAR) and Apple Frameworks with Java and Objective-C bindings.
   • Android examples: Outline Android Archive, Intra Android Archive.
   • Apple examples: Outline iOS Framework, Outline macOS Framework.
3. Integrate into your app: Add the generated library to your app. For more details, see Go Mobile's SDK applications and generating bindings.

Note: You must use gomobile bind on the package you create, not directly on the SDK packages.

An easy way to integrate with the SDK in a mobile app is by using the x/mobileproxy library to run a local web proxy that you can use to configure your app's networking libraries.

To integrate the SDK as a side service, follow these steps:

1. Define IPC mechanism: Choose an inter-process communication (IPC) mechanism (for example, sockets, standard I/O).
2. Build the service: Create a Go binary that includes the server-side of the IPC and used the SDK.
   • Examples: Outline Electron backend code, Outline Windows Client backend build, Outline Linux Client backend build.
3. Bundle the service: Include the Go binary in your application bundle.
   • Examples: Outline Windows Client, Outline Linux Client
4. Start the service: Launch the Go binary as a subprocess from your application.
   • Example: Outline Electron Clients
5. Service Calls: Add code to your app for communication with the service.

To integrate the Outline SDK as a Go library, you can directly import it into your Go application. See the API Reference for what's available.

This approach is suitable for both command-line and GUI-based applications. You can build GUI-based applications in Go with frameworks like Wails, Fyne.io, Qt for Go, or Go Mobile app.

For examples, see x/examples.

This approach is suited for applications that require C bindings. It is similar to the Generated Mobile Library approach, where you need to first create a Go library to generate bindings for.

Steps:

1. Create a Go library: Create a Go package that wraps the SDK functionalities you need. Functions to be exported must be marked with //export, as described in the cgo documentation.
2. Generate C library: Use go build with the appropriate -buildmode flag. Anternatively, you can use SWIG.
3. Integrate into your app: Add the generated C library to your application, according to your build system.

You can find detailed steps at the tutorial Go for beginners: Getting started.

The Outline SDK has several command-line utilities that illustrate the usage of the SDK, but are also valuable for debugging and trying the different strategies without having to build an app.

They all take a -transport flag with a config that specifies what transport should be used to establish connections. The config format can be found in x/config.

The resolve tool resolves a domain name, similar to dig:

$ go run github.com/Jigsaw-Code/outline-sdk/x/examples/resolve@latest -type A -transport "tls" -resolver 8.8.8.8:853 -tcp getoutline.org.
216.239.34.21
216.239.32.21
216.239.38.21
216.239.36.21

The fetch tool fetches a URL, similar to curl. The example below would bypass blocking of meduza.io in Russia:

$ go run github.com/Jigsaw-Code/outline-sdk/x/examples/fetch@latest -transport "tlsfrag:1" -method HEAD -v -address "cloudflare.net" https://meduza.io/ 
[DEBUG] 2023/12/28 18:44:56.490836 main.go:105: Cf-Ray: [83cdac8ecdccc40e-EWR]
[DEBUG] 2023/12/28 18:44:56.491231 main.go:105: Alt-Svc: [h3=":443"; ma=86400]
[DEBUG] 2023/12/28 18:44:56.491237 main.go:105: Date: [Thu, 28 Dec 2023 23:44:56 GMT]
[DEBUG] 2023/12/28 18:44:56.491241 main.go:105: Connection: [keep-alive]
[DEBUG] 2023/12/28 18:44:56.491247 main.go:105: Strict-Transport-Security: [max-age=31536000; includeSubDomains; preload]
[DEBUG] 2023/12/28 18:44:56.491251 main.go:105: Cache-Control: [max-age=0 no-cache, no-store]
[DEBUG] 2023/12/28 18:44:56.491257 main.go:105: X-Content-Type-Options: [nosniff]
[DEBUG] 2023/12/28 18:44:56.491262 main.go:105: Server: [cloudflare]
[DEBUG] 2023/12/28 18:44:56.491266 main.go:105: Content-Type: [text/html; charset=utf-8]
[DEBUG] 2023/12/28 18:44:56.491270 main.go:105: Expires: [Thu, 28 Dec 2023 23:44:56 GMT]
[DEBUG] 2023/12/28 18:44:56.491273 main.go:105: Cf-Cache-Status: [DYNAMIC]

The http2transport tool runs a local proxy that creates connections according to the transport. It's effectively a circumvention tool.

The example below is analogous to the previous fetch example.

Start the local proxy:

$ go run github.com/Jigsaw-Code/outline-sdk/x/examples/http2transport@latest -transport "tlsfrag:1" -localAddr localhost:8080
2023/12/28 18:50:48 Proxy listening on 127.0.0.1:8080

Using the proxy with curl:

$ curl -p -x http:https://localhost:8080 --connect-to ::cloudflare.net: https://meduza.io --head
HTTP/1.1 200 Connection established

HTTP/2 200 
date: Thu, 28 Dec 2023 23:51:01 GMT
content-type: text/html; charset=utf-8
strict-transport-security: max-age=31536000; includeSubDomains; preload
expires: Thu, 28 Dec 2023 23:51:01 GMT
cache-control: max-age=0
cache-control: no-cache, no-store
cf-cache-status: DYNAMIC
x-content-type-options: nosniff
server: cloudflare
cf-ray: 83cdb579bbec4376-EWR
alt-svc: h3=":443"; ma=86400

The test-connectivity tool is useful to test connectivity to a proxy. It uses DNS resolutions over TCP and UDP using the transport to test if there is stream and datagram connectivity.

$ go run github.com/Jigsaw-Code/outline-sdk/x/examples/test-connectivity@latest -transport "$OUTLINE_KEY" && echo success || echo failure
{"resolver":"8.8.8.8:53","proto":"tcp","time":"2023-12-28T23:57:45Z","duration_ms":39,"error":null}
{"resolver":"8.8.8.8:53","proto":"udp","time":"2023-12-28T23:57:45Z","duration_ms":17,"error":null}
{"resolver":"[2001:4860:4860::8888]:53","proto":"tcp","time":"2023-12-28T23:57:45Z","duration_ms":31,"error":null}
{"resolver":"[2001:4860:4860::8888]:53","proto":"udp","time":"2023-12-28T23:57:45Z","duration_ms":16,"error":null}
success