snowflake/doc/using-the-snowflake-library.md

Snowflake is available as a general-purpose pluggable transports library and adheres to the pluggable transports v2.1 Go API.

Client library

The Snowflake client library contains functions for running a Snowflake client.

Example usage:

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:

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 and installation guide for more information

• Run Snowflake proxies. These can be run as standalone Go proxies or browser-based proxies.