commit b4e964c682bd7deaa456ed0b4a80e1e7af994d11 Author: Cecylia Bocovich <cohosh@torproject.org> Date: Thu Jul 15 11:43:05 2021 -0400 Added some Snowflake library documentation --- README.md | 2 +- doc/using-the-snowflake-library.md | 105 +++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index afc4ddf..0278c04 100644 --- a/README.md +++ b/README.md @@ -43,7 +43,7 @@ You can contribute to Snowflake by running a Snowflake proxy. We have the option #### Using the Snowflake Library with Other Applications -Snowflake can be used as a Go API, and adheres to the [v2.1 pluggable transports specification](). For more information on using the Snowflake Go library, see the [Snowflake library documentation](doc/using-the-snowflake-library). +Snowflake can be used as a Go API, and adheres to the [v2.1 pluggable transports specification](). For more information on using the Snowflake Go library, see the [Snowflake library documentation](doc/using-the-snowflake-library.md). ### Test Environment diff --git a/doc/using-the-snowflake-library.md b/doc/using-the-snowflake-library.md new file mode 100644 index 0000000..9308cdc --- /dev/null +++ b/doc/using-the-snowflake-library.md @@ -0,0 +1,105 @@ +Snowflake is available as a general-purpose pluggable transports library and adheres to the [pluggable transports v2.1 Go API](https://github.com/Pluggable-Transports/Pluggable-Transports-spec/blob/maste...). + +### Client library + +The Snowflake client library contains functions for running a Snowflake client. + +Example usage: + +```Golang +package main + +import ( + "log" + + sf "git.torproject.org/pluggable-transports/snowflake.git/client/lib" +) + +func main() { + + transport, err := sf.NewSnowflakeClient("https://snowflake-broker.example.com", + "https://friendlyfrontdomain.net", + []string{"stun:stun.voip.blackberry.com:3478", "stun:stun.stunprotocol.org:3478"}, + false, 1) + if err != nil { + log.Fatal("Failed to start snowflake transport: ", err) + } + + // transport implements the ClientFactory interface and returns a net.Conn + conn, err := transport.Dial() + if err != nil { + log.Printf("dial error: %s", err) + return + } + defer conn.Close() + + // ... + +} +``` + +### Server library + +The Snowflake server library contains functions for running a Snowflake server. + +Example usage: +```Golang + +package main + +import ( + "log" + "net" + + sf "git.torproject.org/pluggable-transports/snowflake.git/server/lib" + "golang.org/x/crypto/acme/autocert" +) + +func main() { + + // The snowflake server runs a websocket server. To run this securely, you will + // need a valid certificate. + certManager := &autocert.Manager{ + Prompt: autocert.AcceptTOS, + HostPolicy: autocert.HostWhitelist("snowflake.yourdomain.com"), + Email: "you@yourdomain.com", + } + + transport := sf.NewSnowflakeServer(certManager.GetCertificate) + + addr, err := net.ResolveTCPAddr("tcp", "127.0.0.1:443") + if err != nil { + log.Printf("error resolving bind address: %s", err.Error()) + } + ln, err := transport.Listen(addr) + if err != nil { + log.Printf("error opening listener: %s", err.Error()) + } + for { + conn, err := ln.Accept() + if err != nil { + if err, ok := err.(net.Error); ok && err.Temporary() { + continue + } + log.Printf("Snowflake accept error: %s", err) + break + } + go func() { + // ... + + defer conn.Close() + }() + } + + // ... + +} + +``` +### Running your own Snowflake infrastructure + +At the moment we do not have the ability to share Snowfake infrastructure between different types of applications. If you are planning on using Snowflake as a transport for your application, you will need to: + +- Run a Snowflake broker. See our [broker documentation](../broker/) and [installation guide](https://gitlab.torproject.org/tpo/anti-censorship/team/-/wikis/Survival-Guid...) for more information + +- Run Snowflake proxies. These can be run as [standalone Go proxies](../proxy/) or [browser-based proxies](https://gitlab.torproject.org/tpo/anti-censorship/pluggable-transports/snowf...).