Documentation

 

Forward Proxy

tl;dr: We have IP addresses that do not change and your connection through the forward proxy is always 100% secure.


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 (probably you) who, for a variety of reasons, have a difficult time with this setup. To accommodate these situations we created a cluster of forward proxy servers.

Our forward proxy servers provide IP addresses that do not change. And by "do not change" we mean "do not change nearly as often". They can and will still change, but rarely instead of often, and never without plenty of advance notice. In order to ensure that we do not throw off your groove, we have a contract in place. As long as you monitor that contract you can always be aware of changes before they happen.

The Contract

The contract is a JSON document located at the following URL:

https://proxy.api.smartystreets.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"
keyexample valuedescription
cidr45.76.9.153/32 or 0:0:0:0:0:ffff:2d4c:999/128IP address using cidr notation.
classipv4 or ipv6Whether the IP is using the IPv4 or IPv6 class.
published2017-07-01The date when the IP address was added to the ip-ranges.json document. Date format: YYYY-MM-DD
enabled2017-07-01The date when the IP address was (or will be) put into service. Date format: YYYY-MM-DD
retired2017-09-18 or nullThe 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.
facilityvultr-ewrThe 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,

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.smartystreets.com:80/ 'https://us-street.api.smartystreets.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.smartystreets.com (45.77.145.98) port 80 (#0)
* Establish HTTP proxy tunnel to us-street.api.smartystreets.com:443
> CONNECT us-street.api.smartystreets.com:443 HTTP/1.1
> Host: us-street.api.smartystreets.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.smartystreets.com" matched cert's "*.api.smartystreets.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.smartystreets.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.smartystreets.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

If you have trouble... shoot it.

"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 SmartyStreets 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.smartystreets.com]
client = yes
accept = 127.0.0.1:8080
connect = proxy.api.smartystreets.com:443
This site uses cookies for analytics, personalized content, and ads. By continuing to browse this site, you agree to this use.