Add diagnostic notice with network ID (prefix only)

MobileLibrary/Android/PsiphonTunnel/PsiphonTunnel.java

@@ -373,6 +373,9 @@ public class PsiphonTunnel extends Psi.PsiphonProvider.Stub {
 
         // The network ID contains potential PII. In tunnel-core, the network ID
         // is used only locally in the client and not sent to the server.
+        //
+        // See network ID requirements here:
+        // https://godoc.org/github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon#NetworkIDGetter
 
         String networkID = "UNKNOWN";
 

MobileLibrary/iOS/PsiphonTunnel/PsiphonTunnel/PsiphonTunnel.m

@@ -1094,6 +1094,9 @@
 
     // The network ID contains potential PII. In tunnel-core, the network ID
     // is used only locally in the client and not sent to the server.
+    //
+    // See network ID requirements here:
+    // https://godoc.org/github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon#NetworkIDGetter
 
     NSMutableString *networkID = [NSMutableString stringWithString:@"UNKNOWN"];
     NetworkStatus status = [[Reachability reachabilityForInternetConnection] currentReachabilityStatus];

MobileLibrary/psi/psi.go

@@ -28,6 +28,7 @@ import (
 	"context"
 	"encoding/json"
 	"fmt"
+	"strings"
 	"sync"
 
 	"github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon"
@@ -325,3 +326,26 @@ func (d *loggingDeviceBinder) BindToDevice(fileDescriptor int) error {
 	}
 	return err
 }
+
+type loggingNetworkIDGetter struct {
+	p PsiphonProvider
+}
+
+func newLoggingNetworkIDGetter(p PsiphonProvider) *loggingNetworkIDGetter {
+	return &loggingNetworkIDGetter{p: p}
+}
+
+func (d *loggingNetworkIDGetter) GetNetworkID() string {
+	networkID := d.p.GetNetworkID()
+
+	// All PII must appear after the initial "-"
+	// See: https://godoc.org/github.com/Psiphon-Labs/psiphon-tunnel-core/psiphon#NetworkIDGetter
+	logNetworkID := networkID
+	index := strings.Index(logNetworkID, "-")
+	if index != -1 {
+		logNetworkID = logNetworkID[:index]
+	}
+	psiphon.NoticeInfo("GetNetworkID: %s", logNetworkID)
+
+	return networkID
+}

psiphon/config.go

@@ -186,35 +186,38 @@ type Config struct {
 	UpstreamProxyCustomHeaders http.Header
 
 	// NetworkConnectivityChecker is an interface that enables tunnel-core to
-	// call into the host application to check for network connectivity. This
-	// parameter is only applicable to library deployments.
+	// call into the host application to check for network connectivity. See:
+	// NetworkConnectivityChecker doc.
+	//
+	// This parameter is only applicable to library deployments.
 	NetworkConnectivityChecker NetworkConnectivityChecker
 
 	// DeviceBinder is an interface that enables tunnel-core to call into the
-	// host application to bind sockets to specific devices. This is used for
-	// VPN routing exclusion. This parameter is only applicable to library
-	// deployments.
+	// host application to bind sockets to specific devices. See: DeviceBinder
+	// doc.
+	//
+	// This parameter is only applicable to library deployments.
 	DeviceBinder DeviceBinder
 
 	// IPv6Synthesizer is an interface that allows tunnel-core to call into
-	// the host application to synthesize IPv6 addresses from IPv4 ones. This
-	// is used to correctly lookup IPs on DNS64/NAT64 networks. This parameter
-	// is only applicable to library deployments.
+	// the host application to synthesize IPv6 addresses. See: IPv6Synthesizer
+	// doc.
+	//
+	// This parameter is only applicable to library deployments.
 	IPv6Synthesizer IPv6Synthesizer
 
 	// DnsServerGetter is an interface that enables tunnel-core to call into
 	// the host application to discover the native network DNS server
-	// settings. This parameter is only applicable to library deployments.
+	// settings. See: DnsServerGetter doc.
+	//
+	// This parameter is only applicable to library deployments.
 	DnsServerGetter DnsServerGetter
 
 	// NetworkIDGetter in an interface that enables tunnel-core to call into
 	// the host application to get an identifier for the host's current active
-	// network. The identifier is a free-form string that should indicate the
-	// network type and identify; for example "WIFI-<BSSID>" or
-	// "MOBILE-<MCC/MNC>". As this network ID is personally identifying, it is
-	// only used locally in the client to determine network context and is not
-	// sent to the Psiphon server. This parameter is only applicable to
-	// library deployments.
+	// network. See: NetworkIDGetter doc.
+	//
+	// This parameter is only applicable to library deployments.
 	NetworkIDGetter NetworkIDGetter
 
 	// TransformHostNames specifies whether to use hostname transformation

psiphon/net.go

@@ -97,29 +97,54 @@ type DialConfig struct {
 }
 
 // NetworkConnectivityChecker defines the interface to the external
-// HasNetworkConnectivity provider
+// HasNetworkConnectivity provider, which call into the host application to
+// check for network connectivity.
 type NetworkConnectivityChecker interface {
 	// TODO: change to bool return value once gobind supports that type
 	HasNetworkConnectivity() int
 }
 
 // DeviceBinder defines the interface to the external BindToDevice provider
+// which calls into the host application to bind sockets to specific devices.
+// This is used for VPN routing exclusion.
 type DeviceBinder interface {
 	BindToDevice(fileDescriptor int) error
 }
 
 // DnsServerGetter defines the interface to the external GetDnsServer provider
+// which calls into the host application to discover the native network DNS
+// server settings.
 type DnsServerGetter interface {
 	GetPrimaryDnsServer() string
 	GetSecondaryDnsServer() string
 }
 
-// IPv6Synthesizer defines the interface to the external IPv6Synthesize provider
+// IPv6Synthesizer defines the interface to the external IPv6Synthesize
+// provider which calls into the host application to synthesize IPv6 addresses
+// from IPv4 ones. This is used to correctly lookup IPs on DNS64/NAT64
+// networks.
 type IPv6Synthesizer interface {
 	IPv6Synthesize(IPv4Addr string) string
 }
 
-// NetworkIDGetter defines the interface to the external GetNetworkID provider
+// NetworkIDGetter defines the interface to the external GetNetworkID
+// provider, which returns an identifier for the host's current active
+// network.
+//
+// The identifier is a string that should indicate the network type and
+// identity; for example "WIFI-<BSSID>" or "MOBILE-<MCC/MNC>". As this network
+// ID is personally identifying, it is only used locally in the client to
+// determine network context and is not sent to the Psiphon server. The
+// identifer will be logged in diagnostics messages; in this case only the
+// substring before the first "-" is logged, so all PII must appear after the
+// first "-".
+//
+// NetworkIDGetter.GetNetworkID should always return an identifier value, as
+// logic that uses GetNetworkID, including tactics, is intended to proceed
+// regardless of whether an accurate network identifier can be obtained. By
+// convention, the provider should return "UNKNOWN" when an accurate network
+// identifier cannot be obtained. Best-effort is acceptable: e.g., return just
+// "WIFI" when only the type of the network but no details can be determined.
 type NetworkIDGetter interface {
 	GetNetworkID() string
 }