Forward proxy

TL;DR: If your network environment requires it, we offer a mechanism to provide you with a set of stable or static IP address ranges for your firewall. As well as a way to bypass HTTPS restriction.

---

We rotate our load balance servers often. This means that the IP addresses for our API endpoints are always changing. For the vast majority of our customers, this works very well. However, there are a few customers (perhaps you) who have specific security or other compliance-based requirements. To accommodate these situations we have created a cluster of forward proxy servers.

Our forward proxy servers provide a set of stable IP address ranges that change in a predictable, controlled manner. Address changes are much less frequent (perhaps only a few times per year) and never occur without advance notice of at least two (2) calendar weeks. As long as you monitor the contract file described below you will always be aware of changes before they happen.

The notification contract

The following JSON document must be actively monitored for changes to determine what IP ranges are and will be used in production:

https://proxy.api.smarty.com/ip-ranges.json

Here is an example of an entry in the ip-ranges document:

{
	"cidr":"45.76.9.153/32",
	"class": "ipv4",
	"published": "2017-07-01",
	"enabled": "2017-07-01",
	"retired": "2017-09-18",
	"facility": "vultr-ewr"
}

Key	Example value	Description
cidr	45.76.9.153/32 or 0:0:0:0:0:ffff:2d4c:999/128	IP address using cidr notation.
class	ipv4 or ipv6	Whether the IP is using the IPv4 or IPv6 class.
published	2017-07-01	The date when the IP address was added to the ip-ranges.json document. Date format: YYYY-MM-DD
enabled	2017-07-01	The date when the IP address was (or will be) put into service. Date format: YYYY-MM-DD
retired	2017-09-18 or null	The date on which the IP address was (or will be) retired. The value of this key will default to null unless the address has been retired. This date may be in the future.
facility	vultr-ewr	The a label that helps group a set of entries together in a similar location, e.g. aws-us-east-1. This label should be considered opaque and may hint at a physical geography.

Making a request through the proxy

Here is an example curl session making a request through the proxy. Notice that even though the request appears to be sent to the proxy over an insecure connection (http) a secure TLS handshake is established with the target (via the proxy), ensuring a secure transmission.

curl -v --proxy http://proxy.api.smarty.com:80/ 'https://us-street.api.smarty.com/street-address?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&street=1600+amphitheatre+pkwy&city=mountain+view&state=CA&candidates=10'
	*   Trying 45.77.145.98...
	* TCP_NODELAY set
	* Connected to proxy.api.smarty.com (45.77.145.98) port 80 (#0)
	* Establish HTTP proxy tunnel to us-street.api.smarty.com:443
	> CONNECT us-street.api.smarty.com:443 HTTP/1.1
	> Host: us-street.api.smarty.com:443
	> User-Agent: curl/7.54.0
	> Proxy-Connection: Keep-Alive
	>
	< HTTP/1.1 200 OK
	<
	* Proxy replied OK to CONNECT request
	* ALPN, offering h2
	* ALPN, offering http/1.1
	* Cipher selection: ALL:!EXPORT:!EXPORT40:!EXPORT56:!aNULL:!LOW:!RC4:@STRENGTH
	* successfully set certificate verify locations:
	*   CAfile: /etc/ssl/cert.pem
	CApath: none
	* TLSv1.2 (OUT), TLS handshake, Client hello (1):
	* TLSv1.2 (IN), TLS handshake, Server hello (2):
	* TLSv1.2 (IN), TLS handshake, Certificate (11):
	* TLSv1.2 (IN), TLS handshake, Server key exchange (12):
	* TLSv1.2 (IN), TLS handshake, Server finished (14):
	* TLSv1.2 (OUT), TLS handshake, Client key exchange (16):
	* TLSv1.2 (OUT), TLS change cipher, Client hello (1):
	* TLSv1.2 (OUT), TLS handshake, Finished (20):
	* TLSv1.2 (IN), TLS change cipher, Client hello (1):
	* TLSv1.2 (IN), TLS handshake, Finished (20):
	* SSL connection using TLSv1.2 / ECDHE-RSA-AES128-GCM-SHA256
	* ALPN, server did not agree to a protocol
	* Server certificate:
	*  subject: OU=Domain Control Validated; OU=PositiveSSL Multi-Domain; CN=smartystreets.com
	*  start date: Oct 26 00:00:00 2017 GMT
	*  expire date: Jan 24 23:59:59 2019 GMT
	*  subjectAltName: host "us-street.api.smarty.com" matched cert's "*.api.smarty.com"
	*  issuer: C=GB; ST=Greater Manchester; L=Salford; O=COMODO CA Limited; CN=COMODO RSA Domain Validation Secure Server CA
	*  SSL certificate verify ok.
	> GET /street-address?auth-id=YOUR+AUTH-ID+HERE&auth-token=YOUR+AUTH-TOKEN+HERE&street=1600+amphitheatre+pkwy&city=mountain+view&state=CA&candidates=10 HTTP/1.1
	> Host: us-street.api.smarty.com
	> User-Agent: curl/7.54.0
	> Accept: */*
	>
	< HTTP/1.1 200 OK
	< Content-Length: 829
	< Content-Type: application/json; charset=utf-8
	< Date: Thu, 06 Sep 2018 23:05:35 GMT
	< Strict-Transport-Security: max-age=31536000; includeSubDomains
	<
	* Connection #0 to host proxy.api.smarty.com left intact
	[{"input_index":0,"candidate_index":0,"delivery_line_1":"1600 Amphitheatre Pkwy","last_line":"Mountain View CA 94043-1351","delivery_point_barcode":"940431351000","components":{"primary_number":"1600","street_name":"Amphitheatre","street_suffix":"Pkwy","city_name":"Mountain View","state_abbreviation":"CA","zipcode":"94043","plus4_code":"1351","delivery_point":"00","delivery_point_check_digit":"0"},"metadata":{"record_type":"S","zip_type":"Standard","county_fips":"06085","county_name":"Santa Clara","carrier_route":"C909","congressional_district":"18","rdi":"Commercial","elot_sequence":"0094","elot_sort":"A","latitude":37.42357,"longitude":-122.08661,"precision":"Zip9","time_zone":"Pacific","utc_offset":-8,"dst":true},"analysis":{"dpv_match_code":"Y","dpv_footnotes":"AABB","dpv_cmra":"N","dpv_vacant":"N","active":"N"}}]

Troubleshooting

"My corporate firewall policies require traffic on port 443, but my code is not connecting to your proxy."

We have had reports that some frameworks do not support TLS proxies. In these instances we recommend using the free/open source stunnel application as a local proxy. stunnel listens on localhost (127.0.0.1) and forwards traffic that it receives to port 443 of a fixed IP proxy server. This should allow frameworks/applications to connect over port 80 to a local resource and have their traffic routed properly through the Smarty proxy servers.

Here is a sample configuration file called stunnel.conf that can be used after installing stunnel. There is an installable version available for Windows, Linux, and Mac.

; foreground = yes
; debug = info

options = -NO_SSLv3

[proxy.api.smarty.com]
client = yes
accept = 127.0.0.1:8080
connect = proxy.api.smarty.com:443