[tor-commits] [snowflake/main] Added some Snowflake library documentation

[cohosh at torproject.org]

commit b4e964c682bd7deaa456ed0b4a80e1e7af994d11
Author: Cecylia Bocovich <cohosh at 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/master/releases/PTSpecV2.1/Pluggable%20Transport%20Specification%20v2.1%20-%20Go%20Transport%20API.pdf).
+
+### 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 at 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-Guides/Snowflake-Broker-Installation-Guide) 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/snowflake-webext).