mobile

README

Mobile API

This package is a mobile API for the dnsproxy.

We are using gomobile to build mobile bindings as it is explained in the documentation.

How to build

You will need go v1.11 or newer.

To build the Android library:

$ export ANDROID_HOME=PATH_TO_ANDROID_SDK
$ make clean
$ make android

To build the iOS library (please note that you need to execute it on macOS):

$ make clean
$ make ios

TODO

There is a known issue with gomobile not supporting go modules. Unfortunately, until this issue is resolved, we have to use a complicated make file

• Android library build
• iOS library build
• Update the build script once go modules support is added to gomobile

Documentation

Overview

Package mobile contains a simple mobile API for github.com/AdguardTeam/dnsproxy

Index

• Constants
• func ConfigureDNSRequestProcessedListener(l DNSRequestProcessedListener)
• func ConfigureLogger(verbose bool, stderrRedirectPath string, w LogWriter) error
• func SetLogLevel(verbose bool)
• func TestUpstream(address string, bootstrap string, timeout int) error
• type Config
• type DNSProxy
  • func (d *DNSProxy) Addr() string
  • func (d *DNSProxy) Resolve(packet []byte) ([]byte, error)
  • func (d *DNSProxy) Restart(config *Config) error
  • func (d *DNSProxy) Start() error
  • func (d *DNSProxy) Stop() error
• type DNSRequestProcessedEvent
• type DNSRequestProcessedListener
• type DNSStamp
  • func ParseDNSStamp(stampStr string) (*DNSStamp, error)
• type FilteringConfig
• type LogWriter
• type LogWriterAdapter
  • func (w *LogWriterAdapter) Write(p []byte) (n int, err error)

Constants

const (
	BlockTypeRule          = iota // Respond with NXDomain for Network filtering rules and with IP for Host rules
	BlockTypeNXDomain      = iota // Respond with NXDomain for all kind of filtering rules
	BlockTypeUnspecifiedIP = iota // Respond with Unspecified IP for Network filtering rules
)

Functions

func ConfigureDNSRequestProcessedListener

func ConfigureDNSRequestProcessedListener(l DNSRequestProcessedListener)

ConfigureDNSRequestProcessedListener configures a global listener for the DNSRequestProcessedEvent events

func ConfigureLogger

func ConfigureLogger(verbose bool, stderrRedirectPath string, w LogWriter) error

ConfigureLogger function is called from mobile API to write dnsproxy log into mobile log You need to create object that implements LogWriter interface and set it as argument of this function

func SetLogLevel

func SetLogLevel(verbose bool)

SetLogLevel function is called from mobile API and changes log level without LogWriter and srderrRedirect reconfiguration

func TestUpstream

func TestUpstream(address string, bootstrap string, timeout int) error

TestUpstream checks if upstream is valid and available If it is, no error is returned. Otherwise this method returns an error with an explanation. * address - see upstream.AddressToUpstream for examples * bootstrap - an optional bootstrap DNS. You can pass multiple addresses by separating them with a newline * timeout - timeout in milliseconds

Types

type Config

type Config struct {
	ListenAddr        string // IP address to listen to
	ListenPort        int    // Port to listen to
	BootstrapDNS      string // A list of bootstrap DNS (i.e. 8.8.8.8:53 each on a new line)
	Fallbacks         string // A list of fallback resolvers that will be used if the main one is not available (i.e. 1.1.1.1:53 each on a new line)
	Upstreams         string // A list of upstream resolvers (each on a new line)
	Timeout           int    // Default timeout for all resolvers (milliseconds)
	CacheSize         int    // Maximum number of elements in the cache. Default size: 1000
	AllServers        bool   // If true, parallel queries to all configured upstream servers are enabled
	MaxGoroutines     int    // Maximum number of parallel goroutines that process the requests
	SystemResolvers   string // A list of system resolvers for ipv6-only network (each on new line). We need to specify it to use dns.Client instead of default net.Resolver
	DetectDNS64Prefix bool   // If true, DNS64 prefix detection is enabled
}

Config is the DNS proxy configuration which uses only the subset of types that is supported by gomobile In Java API this structure becomes an object that needs to be configured and set as field of DNSProxy

type DNSProxy

type DNSProxy struct {
	Config          *Config          // Proxy configuration
	FilteringConfig *FilteringConfig // Filtering configuration

	sync.RWMutex
	// contains filtered or unexported fields
}

DNSProxy represents a proxy with it's configuration

func (*DNSProxy) Addr

func (d *DNSProxy) Addr() string

Addr gets the address proxy is currently listening to

func (*DNSProxy) Resolve

func (d *DNSProxy) Resolve(packet []byte) ([]byte, error)

Resolve resolves the specified DNS request using the configured (and started) dns proxy packet - DNS query bytes returns response or error

func (*DNSProxy) Restart

func (d *DNSProxy) Restart(config *Config) error

Restart proxy with new configuration without filteringEngine recreation

func (*DNSProxy) Start

func (d *DNSProxy) Start() error

Start starts the DNS proxy

func (*DNSProxy) Stop

func (d *DNSProxy) Stop() error

Stop stops the DNS proxy

type DNSRequestProcessedEvent

type DNSRequestProcessedEvent struct {
	Domain string // Queried domain name
	Type   string // Query type

	StartTime    int64  // Time when dnsproxy started processing request (epoch in milliseconds)
	Elapsed      int    // Time elapsed on processing
	Answer       string // DNS Answers string representation
	UpstreamAddr string // Address of the upstream used to resolve

	BytesSent     int // Number of bytes sent
	BytesReceived int // Number of bytes received

	FilteringRule string // Filtering rule text
	FilterListID  int    // Filter list ID
	Whitelist     bool   // True if filtering rule is whitelist

	Error string // If not empty, contains the error text (occurred while processing the DNS query)
}

DNSRequestProcessedEvent represents DNS processed event

type DNSRequestProcessedListener

type DNSRequestProcessedListener interface {
	DNSRequestProcessed(e *DNSRequestProcessedEvent)
}

DNSRequestProcessedListener is a callback interface that can be configured from by the client library

type DNSStamp

type DNSStamp struct {
	Proto        int    // Protocol (0x00 for plain, 0x01 for DNSCrypt, 0x02 for DOH, 0x03 for DOT
	ServerAddr   string // Server address
	ProviderName string // Provider name
	Path         string // Path (for DOH)
}

DNSStamp is mobile-friendly DNS stamp structure

func ParseDNSStamp

func ParseDNSStamp(stampStr string) (*DNSStamp, error)

ParseDNSStamp parses a DNS stamp string and returns a stamp instance or an error

type FilteringConfig

type FilteringConfig struct {
	FilteringRulesFilesJSON   string // Filtering rules files JSON (list of "id": filterListID, "path": "path/to/filter")
	FilteringRulesStringsJSON string // Filtering rules string JSON (list of "id": filterListID, "content": "filtering rules one per line")
	BlockType                 int    // Block type for filtering rules
}

FilteringConfig is the filteringEngine configuration

type LogWriter

type LogWriter interface {
	Write(s string)
}

LogWriter interface should be implemented inside project that will use dnsproxy mobile API to write dnsproxy log into mobile log

type LogWriterAdapter

type LogWriterAdapter struct {
	// contains filtered or unexported fields
}

LogWriterAdapter between go log and LogWriter

func (*LogWriterAdapter) Write

func (w *LogWriterAdapter) Write(p []byte) (n int, err error)