fronted

README

fronted  

To install:

go get github.com/getlantern/fronted

For docs:

godoc github.com/getlantern/fronted

See ddftool for more details on how to generate and tests fronting domains for the supported CDNs.

[!NOTE] Since the masquerade domains and IP addresses can change, tests might fail and they need to be updated. You can basically ping some of the masquerade domains (from default_masquerade.go) and update the IPs accordingly.

To generate an updated domain fronting configuration file, just run:

./updateFrontedConfig.bash

Documentation

Index

• Constants
• Variables
• func SetLogger(logger *slog.Logger)
• func Vet(m *Masquerade, pool *x509.CertPool, testURL string) bool
• type CA
• type Front
• type Fronted
  • func ConfigureCachingForTest(t *testing.T, cacheFile string) Fronted
  • func ConfigureForTest(t *testing.T) Fronted
  • func ConfigureHostAlaisesForTest(t *testing.T, hosts map[string]string) Fronted
  • func NewFronted(options ...Option) Fronted
• type Masquerade
• type Option
  • func WithCacheFile(file string) Option
  • func WithConfigURL(configURL string) Option
  • func WithCountryCode(cc string) Option
  • func WithEmbeddedConfigName(name string) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithPanicListener(panicListener func(string)) Option
• type Provider
  • func NewProvider(hosts map[string]string, testURL string, masquerades []*Masquerade, ...) *Provider
  • func (p *Provider) Lookup(hostname string) string
  • func (p *Provider) ValidateResponse(res *http.Response) error
• type ResponseValidator
  • func NewStatusCodeValidator(reject []int) ResponseValidator
• type SNIConfig

Constants

const (
	NumWorkers = 10 // number of worker goroutines for verifying
)

Variables

var DefaultAkamaiMasquerades = []*Masquerade{
	{
		Domain:    "a248.e.akamai.net",
		IpAddress: "104.117.247.143",
	},
	{
		Domain:    "a248.e.akamai.net",
		IpAddress: "23.47.194.73",
	},
}

var DefaultCloudfrontMasquerades = []*Masquerade{}/* 999 elements not displayed */

var DefaultTrustedCAs = []*CA{
	{
		CommonName: "Amazon Root CA 1",
		Cert:       "-----BEGIN CERTIFICATE-----\nMIIDQTCCAimgAwIBAgITBmyfz5m/jAo54vB4ikPmljZbyjANBgkqhkiG9w0BAQsF\nADA5MQswCQYDVQQGEwJVUzEPMA0GA1UEChMGQW1hem9uMRkwFwYDVQQDExBBbWF6\nb24gUm9vdCBDQSAxMB4XDTE1MDUyNjAwMDAwMFoXDTM4MDExNzAwMDAwMFowOTEL\nMAkGA1UEBhMCVVMxDzANBgNVBAoTBkFtYXpvbjEZMBcGA1UEAxMQQW1hem9uIFJv\nb3QgQ0EgMTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALJ4gHHKeNXj\nca9HgFB0fW7Y14h29Jlo91ghYPl0hAEvrAIthtOgQ3pOsqTQNroBvo3bSMgHFzZM\n9O6II8c+6zf1tRn4SWiw3te5djgdYZ6k/oI2peVKVuRF4fn9tBb6dNqcmzU5L/qw\nIFAGbHrQgLKm+a/sRxmPUDgH3KKHOVj4utWp+UhnMJbulHheb4mjUcAwhmahRWa6\nVOujw5H5SNz/0egwLX0tdHA114gk957EWW67c4cX8jJGKLhD+rcdqsq08p8kDi1L\n93FcXmn/6pUCyziKrlA4b9v7LWIbxcceVOF34GfID5yHI9Y/QCB/IIDEgEw+OyQm\njgSubJrIqg0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNVHQ8BAf8EBAMC\nAYYwHQYDVR0OBBYEFIQYzIU07LwMlJQuCFmcx7IQTgoIMA0GCSqGSIb3DQEBCwUA\nA4IBAQCY8jdaQZChGsV2USggNiMOruYou6r4lK5IpDB/G/wkjUu0yKGX9rbxenDI\nU5PMCCjjmCXPI6T53iHTfIUJrU6adTrCC2qJeHZERxhlbI1Bjjt/msv0tadQ1wUs\nN+gDS63pYaACbvXy8MWy7Vu33PqUXHeeE6V/Uq2V8viTO96LXFvKWlJbYK8U90vv\no/ufQJVtMVT8QtPHRh8jrdkPSHCa2XV4cdFyQzR1bldZwgJcJmApzyMZFo6IQ6XU\n5MsI+yMRQ+hDKXJioaldXgjUkK642M4UwtBV8ob2xJNDd2ZhwLnoQdeXeGADbkpy\nrqXRfboQnoZsG4q5WTP468SQvvG5\n-----END CERTIFICATE-----\n",
	},
	{
		CommonName: "DigiCert Global Root G2",
		Cert:       "-----BEGIN CERTIFICATE-----\nMIIDjjCCAnagAwIBAgIQAzrx5qcRqaC7KGSxHQn65TANBgkqhkiG9w0BAQsFADBh\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3\nd3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBH\nMjAeFw0xMzA4MDExMjAwMDBaFw0zODAxMTUxMjAwMDBaMGExCzAJBgNVBAYTAlVT\nMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j\nb20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IEcyMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEAuzfNNNx7a8myaJCtSnX/RrohCgiN9RlUyfuI\n2/Ou8jqJkTx65qsGGmvPrC3oXgkkRLpimn7Wo6h+4FR1IAWsULecYxpsMNzaHxmx\n1x7e/dfgy5SDN67sH0NO3Xss0r0upS/kqbitOtSZpLYl6ZtrAGCSYP9PIUkY92eQ\nq2EGnI/yuum06ZIya7XzV+hdG82MHauVBJVJ8zUtluNJbd134/tJS7SsVQepj5Wz\ntCO7TG1F8PapspUwtP1MVYwnSlcUfIKdzXOS0xZKBgyMUNGPHgm+F6HmIcr9g+UQ\nvIOlCsRnKPZzFBQ9RnbDhxSJITRNrw9FDKZJobq7nMWxM4MphQIDAQABo0IwQDAP\nBgNVHRMBAf8EBTADAQH/MA4GA1UdDwEB/wQEAwIBhjAdBgNVHQ4EFgQUTiJUIBiV\n5uNu5g/6+rkS7QYXjzkwDQYJKoZIhvcNAQELBQADggEBAGBnKJRvDkhj6zHd6mcY\n1Yl9PMWLSn/pvtsrF9+wX3N3KjITOYFnQoQj8kVnNeyIv/iPsGEMNKSuIEyExtv4\nNeF22d+mQrvHRAiGfzZ0JFrabA0UWTW98kndth/Jsw1HKj2ZL7tcu7XUIOGZX1NG\nFdtom/DzMNU+MeKNhJ7jitralj41E6Vf8PlwUHBHQRFXGU7Aj64GxJUTFy8bJZ91\n8rGOmaFvE7FBcf6IKshPECBV1/MUReXgRPTqh5Uykw7+U0b6LJ3/iyK5S9kJRaTe\npLiaWN0bfVKfjllDiIGknibVb63dDcY3fe0Dkhvld1927jyNxF1WW6LZZm6zNTfl\nMrY=\n-----END CERTIFICATE-----\n",
	},
	{
		CommonName: "DigiCert Global Root CA",
		Cert:       "-----BEGIN CERTIFICATE-----\nMIIDrzCCApegAwIBAgIQCDvgVpBCRrGhdWrJWZHHSjANBgkqhkiG9w0BAQUFADBh\nMQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3\nd3cuZGlnaWNlcnQuY29tMSAwHgYDVQQDExdEaWdpQ2VydCBHbG9iYWwgUm9vdCBD\nQTAeFw0wNjExMTAwMDAwMDBaFw0zMTExMTAwMDAwMDBaMGExCzAJBgNVBAYTAlVT\nMRUwEwYDVQQKEwxEaWdpQ2VydCBJbmMxGTAXBgNVBAsTEHd3dy5kaWdpY2VydC5j\nb20xIDAeBgNVBAMTF0RpZ2lDZXJ0IEdsb2JhbCBSb290IENBMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA4jvhEXLeqKTTo1eqUKKPC3eQyaKl7hLOllsB\nCSDMAZOnTjC3U/dDxGkAV53ijSLdhwZAAIEJzs4bg7/fzTtxRuLWZscFs3YnFo97\nnh6Vfe63SKMI2tavegw5BmV/Sl0fvBf4q77uKNd0f3p4mVmFaG5cIzJLv07A6Fpt\n43C/dxC//AH2hdmoRBBYMql1GNXRor5H4idq9Joz+EkIYIvUX7Q6hL+hqkpMfT7P\nT19sdl6gSzeRntwi5m3OFBqOasv+zbMUZBfHWymeMr/y7vrTC0LUq7dBMtoM1O/4\ngdW7jVg/tRvoSSiicNoxBN33shbyTApOB6jtSj1etX+jkMOvJwIDAQABo2MwYTAO\nBgNVHQ8BAf8EBAMCAYYwDwYDVR0TAQH/BAUwAwEB/zAdBgNVHQ4EFgQUA95QNVbR\nTLtm8KPiGxvDl7I90VUwHwYDVR0jBBgwFoAUA95QNVbRTLtm8KPiGxvDl7I90VUw\nDQYJKoZIhvcNAQEFBQADggEBAMucN6pIExIK+t1EnE9SsPTfrgT1eXkIoyQY/Esr\nhMAtudXH/vTBH1jLuG2cenTnmCmrEbXjcKChzUyImZOMkXDiqw8cvpOp/2PV5Adg\n06O/nVsJ8dWO41P0jmP6P6fbtGbfYmbW0W5BjfIttep3Sp+dWOIrWcBAI+0tKIJF\nPnlUkiaY4IBIqDfv8NZ5YBberOgOzW6sRBc4L0na4UU+Krk2U886UAb3LujEV0ls\nYSEY1QSteDwsOoBrp+uvFRTp2InBuThs4pFsiv9kuXclVzDAGySj4dzp30d8tbQk\nCAUw7C29C79Fv1C5qfPrmAESrciIxpg0X40KPMbp1ZWVbd4=\n-----END CERTIFICATE-----\n",
	},
	{
		CommonName: "GlobalSign",
		Cert:       "-----BEGIN CERTIFICATE-----\nMIIDXzCCAkegAwIBAgILBAAAAAABIVhTCKIwDQYJKoZIhvcNAQELBQAwTDEgMB4G\nA1UECxMXR2xvYmFsU2lnbiBSb290IENBIC0gUjMxEzARBgNVBAoTCkdsb2JhbFNp\nZ24xEzARBgNVBAMTCkdsb2JhbFNpZ24wHhcNMDkwMzE4MTAwMDAwWhcNMjkwMzE4\nMTAwMDAwWjBMMSAwHgYDVQQLExdHbG9iYWxTaWduIFJvb3QgQ0EgLSBSMzETMBEG\nA1UEChMKR2xvYmFsU2lnbjETMBEGA1UEAxMKR2xvYmFsU2lnbjCCASIwDQYJKoZI\nhvcNAQEBBQADggEPADCCAQoCggEBAMwldpB5BngiFvXAg7aEyiie/QV2EcWtiHL8\nRgJDx7KKnQRfJMsuS+FggkbhUqsMgUdwbN1k0ev1LKMPgj0MK66X17YUhhB5uzsT\ngHeMCOFJ0mpiLx9e+pZo34knlTifBtc+ycsmWQ1z3rDI6SYOgxXG71uL0gRgykmm\nKPZpO/bLyCiR5Z2KYVc3rHQU3HTgOu5yLy6c+9C7v/U9AOEGM+iCK65TpjoWc4zd\nQQ4gOsC0p6Hpsk+QLjJg6VfLuQSSaGjlOCZgdbKfd/+RFO+uIEn8rUAVSNECMWEZ\nXriX7613t2Saer9fwRPvm2L7DWzgVGkWqQPabumDk3F2xmmFghcCAwEAAaNCMEAw\nDgYDVR0PAQH/BAQDAgEGMA8GA1UdEwEB/wQFMAMBAf8wHQYDVR0OBBYEFI/wS3+o\nLkUkrk1Q+mOai97i3Ru8MA0GCSqGSIb3DQEBCwUAA4IBAQBLQNvAUKr+yAzv95ZU\nRUm7lgAJQayzE4aGKAczymvmdLm6AC2upArT9fHxD4q/c2dKg8dEe3jgr25sbwMp\njjM5RcOO5LlXbKr8EpbsU8Yt5CRsuZRj+9xTaGdWPoO4zzUhw8lo/s7awlOqzJCK\n6fBdRoyV3XpYKBovHd7NADdBj+1EbddTKJd+82cEHhXXipa0095MJ6RMG3NzdvQX\nmcIfeg7jLQitChws/zyrVQ4PkX4268NXSb7hLi18YIvDQVETI53O9zJrlAGomecs\nMx86OyXShkDOOyyGeMlhLxS67ttVb9+E7gUJTb0o2HLO02JQZR7rkpeDMdmztcpH\nWD9f\n-----END CERTIFICATE-----\n",
	},
}

Functions

func SetLogger

func SetLogger(logger *slog.Logger)

SetLogger sets the logger to use by fronted.

func Vet

func Vet(m *Masquerade, pool *x509.CertPool, testURL string) bool

Vet vets the specified Masquerade, verifying certificate using the given CertPool. This is used in genconfig.

Types

type CA

type CA struct {
	CommonName string
	Cert       string // PEM-encoded
}

CA represents a certificate authority

type Front

type Front interface {
	// contains filtered or unexported methods
}

Create a masquerade interface for easier testing.

type Fronted

type Fronted interface {
	NewConnectedRoundTripper(ctx context.Context, addr string) (http.RoundTripper, error)

	// Close closes any resources, such as goroutines that are testing fronts.
	Close()
	// contains filtered or unexported methods
}

Interface for sending HTTP traffic over domain fronting.

func ConfigureCachingForTest

func ConfigureCachingForTest(t *testing.T, cacheFile string) Fronted

func ConfigureForTest

func ConfigureForTest(t *testing.T) Fronted

ConfigureForTest configures fronted for testing using default masquerades and certificate authorities.

func ConfigureHostAlaisesForTest

func ConfigureHostAlaisesForTest(t *testing.T, hosts map[string]string) Fronted

func NewFronted

func NewFronted(options ...Option) Fronted

NewFronted creates a new Fronted instance with the given cache file. At this point it does not have the actual IPs, domains, etc of the fronts to try. defaultProviderID is used when a front without a provider is encountered (eg in a cache file)

type Masquerade

type Masquerade struct {
	// Domain: the domain to use for domain fronting
	Domain string

	// IpAddress: pre-resolved ip address to use instead of Domain (if
	// available)
	IpAddress string

	// SNI: the SNI to use for this masquerade
	SNI string

	// VerifyHostname is used for checking if the certificate for a given hostname is valid.
	// This is used for verifying if the peer certificate for the hostnames that are being fronted are valid.
	VerifyHostname *string
}

Masquerade contains the data for a single masquerade host, including the domain and the root CA.

type Option

type Option func(*fronted)

Option is a functional option type that allows us to configure the fronted client.

func WithCacheFile

func WithCacheFile(file string) Option

WithCacheFile sets the file to use for caching domains that have successfully connected.

func WithConfigURL

func WithConfigURL(configURL string) Option

WithConfigURL sets the URL from which to continually fetch updated domain fronting configurations.

func WithCountryCode

func WithCountryCode(cc string) Option

WithCountryCode sets the country code to use for fronting, which is particularly relevant for the SNI to use when connecting to the fronting domain.

func WithEmbeddedConfigName

func WithEmbeddedConfigName(name string) Option

Allows tests to override the embedded configuration name.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient sets the HTTP client to use for fetching the fronted configuration. For example, the client could be censorship-resistant in some way.

func WithPanicListener

func WithPanicListener(panicListener func(string)) Option

WithPanicListener sets a listener for panics that occur in the fronted.

type Provider

type Provider struct {
	// Specific hostname mappings used for this provider.
	// remaps certain requests to provider specific host names.
	HostAliases map[string]string

	// Allow unaliased pass-through of hostnames
	// matching these patterns.
	// eg "*.cloudfront.net" for cloudfront provider
	// would permit all .cloudfront.net domains to
	// pass through without alias. Only suffix
	// patterns and exact matches are supported.
	PassthroughPatterns []string

	// Url used to vet masquerades for this provider
	TestURL     string
	Masquerades []*Masquerade

	// VerifyHostname is used for checking if the certificate for a given hostname is valid.
	// This attribute is only being defined here so it can be sent to the masquerade struct later.
	VerifyHostname *string

	// FrontingSNIs is a map of country code the the SNI config to use for that country.
	FrontingSNIs map[string]*SNIConfig
}

A Direct fronting provider configuration.

func NewProvider

func NewProvider(hosts map[string]string, testURL string, masquerades []*Masquerade, passthrough []string, frontingSNIs map[string]*SNIConfig, verifyHostname *string, countryCode string) *Provider

Create a Provider with the given details

func (*Provider) Lookup

func (p *Provider) Lookup(hostname string) string

Lookup the host alias for the given hostname for this provider

func (*Provider) ValidateResponse

func (p *Provider) ValidateResponse(res *http.Response) error

Validate a fronted response. Returns an error if the response failed to reach the origin, eg if the request was rejected by the provider.

type ResponseValidator

type ResponseValidator func(*http.Response) error

A validator for fronted responses. Returns an error if the response failed to reach the origin, eg if the request was rejected by the provider.

func NewStatusCodeValidator

func NewStatusCodeValidator(reject []int) ResponseValidator

Create a new ResponseValidator that rejects any response with a given list of http status codes.

type SNIConfig

type SNIConfig struct {
	UseArbitrarySNIs bool
	ArbitrarySNIs    []string
}