Document Client Config options

internal/client/config.go

@@ -17,28 +17,70 @@ import (
 )
 
 // RawConfig represents the fields in the config json file
-// nullable means if it's empty, a default value will be chosen in ProcessRawConfig
 // jsonOptional means if the json's empty, its value will be set from environment variables or commandline args
 // but it mustn't be empty when ProcessRawConfig is called
 type RawConfig struct {
-	ServerName       string
-	ProxyMethod      string
+	// Required fields
+	// ServerName is the domain you appear to be visiting
+	// to your Firewall or ISP
+	ServerName string
+	// ProxyMethod is the name of the underlying proxy you wish
+	// to connect to, as determined by your server. The value can
+	// be any string whose UTF-8 ENCODED byte length is no greater than
+	// 12 bytes
+	ProxyMethod string
+	// UID is a 16-byte secret string unique to an authorised user
+	// The same UID can be used by the same user for multiple Cloak connections
+	UID []byte
+	// PublicKey is the 32-byte public Curve25519 ECDH key of your server
+	PublicKey []byte
+	// RemoteHost is the Cloak server's hostname or IP address
+	RemoteHost string // jsonOptional
+
+	// Optional Fields
+	// EncryptionMethod is the cryptographic algorithm used to
+	// encrypt data on the wire.
+	// Valid values are `aes-128-gcm`, `aes-256-gcm`, `chacha20-poly1305`, and `plain`
+	// Defaults to `aes-256-gcm`
 	EncryptionMethod string
-	UID              []byte
-	PublicKey        []byte
-	NumConn          int
-	LocalHost        string   // jsonOptional
-	LocalPort        string   // jsonOptional
-	RemoteHost       string   // jsonOptional
-	RemotePort       string   // jsonOptional
-	AlternativeNames []string // jsonOptional
-	// defaults set in ProcessRawConfig
-	UDP           bool   // nullable
-	BrowserSig    string // nullable
-	Transport     string // nullable
-	CDNOriginHost string // nullable
-	StreamTimeout int    // nullable
-	KeepAlive     int    // nullable
+	// NumConn is the amount of underlying TLS connections to establish with Cloak server.
+	// Cloak multiplexes any number of incoming connections to a fixed number of underlying TLS connections.
+	// If set to 0, a special singleplex mode is enabled: each incoming connection will correspond to exactly one
+	// TLS connection
+	// Defaults to 4
+	NumConn *int
+	// UDP enables UDP semantics, where packets must fit into one unit of message (below 16000 bytes by default),
+	// and packets can be received out of order. Though reliable delivery is still guaranteed.
+	UDP bool
+	// BrowserSig is the browser signature to be used. Options are `chrome` and `firefox`
+	// Defaults to `chrome`
+	BrowserSig string
+	// Transport is either `direct` or `cdn`. Under `direct`, the client connects to a Cloak server directly.
+	// Under `cdn`, the client connects to a CDN provider such as Amazon Cloudfront, which in turn connects
+	// to a Cloak server.
+	// Defaults to `direct`
+	Transport string
+	// CDNOriginHost is the CDN Origin's (i.e. Cloak server) real hostname or IP address, which is encrypted between
+	// the client and the CDN server, and therefore hidden to ISP or firewalls. This only has effect when Transport
+	// is set to `cdn`
+	// Defaults to RemoteHost
+	CDNOriginHost string
+	// StreamTimeout is the duration, in seconds, for a stream to be automatically closed after the last write.
+	// Defaults to 300
+	StreamTimeout int
+	// KeepAlive is the interval between TCP KeepAlive packets to be sent over the underlying TLS connections
+	// Defaults to -1, which means no TCP KeepAlive is ever sent
+	KeepAlive int
+	// RemotePort is the port Cloak server is listening to
+	// Defaults to 443
+	RemotePort string
+
+	// LocalHost is the hostname or IP address to listen for incoming proxy client connections
+	LocalHost string // jsonOptional
+	// LocalPort is the port to listen for incomig proxy client connections
+	LocalPort string // jsonOptional
+	// AlternativeNames is a list of ServerName Cloak may randomly pick from for different sessions
+	AlternativeNames []string
 }
 
 type RemoteConnConfig struct {
@@ -187,6 +229,8 @@ func (raw *RawConfig) ProcessRawConfig(worldState common.WorldState) (local Loca
 		auth.EncryptionMethod = mux.EncryptionMethodAES128GCM
 	case "chacha20-poly1305":
 		auth.EncryptionMethod = mux.EncryptionMethodChaha20Poly1305
+	case "":
+		auth.EncryptionMethod = mux.EncryptionMethodAES256GCM
 	default:
 		err = fmt.Errorf("unknown encryption method %v", raw.EncryptionMethod)
 		return
@@ -195,15 +239,21 @@ func (raw *RawConfig) ProcessRawConfig(worldState common.WorldState) (local Loca
 	if raw.RemoteHost == "" {
 		return nullErr("RemoteHost")
 	}
+	var remotePort string
 	if raw.RemotePort == "" {
-		return nullErr("RemotePort")
+		remotePort = "443"
+	} else {
+		remotePort = raw.RemotePort
 	}
-	remote.RemoteAddr = net.JoinHostPort(raw.RemoteHost, raw.RemotePort)
-	if raw.NumConn <= 0 {
+	remote.RemoteAddr = net.JoinHostPort(raw.RemoteHost, remotePort)
+	if raw.NumConn == nil {
+		remote.NumConn = 4
+		remote.Singleplex = false
+	} else if *raw.NumConn <= 0 {
 		remote.NumConn = 1
 		remote.Singleplex = true
 	} else {
-		remote.NumConn = raw.NumConn
+		remote.NumConn = *raw.NumConn
 		remote.Singleplex = false
 	}