Connecting to Twitter API using SSL

Currently, only SSL connections are allowed in Twitter API endpoints. Communicating over SSL preserves user privacy by protecting information between the user and the Twitter API as it travels across the public Internet.

Using OAuth isn’t enough

While OAuth is mandated and protects the user from having their password captured in transit by substituting an OAuth token for the user’s credentials, it’s not enough to ensure complete privacy.

Cipher Selection

Twitter’s servers and your client will negotiate a cipher spec upon connection. When possible, it’s best to use the Twitter supplied cipher default (currently RC4) for session encryption. While other ciphers may offer better performance or security (and may be supported by both your client and Twitter’s servers,) the preferred cipher as negotiated by our servers is typically the best available for communication. We do not recommend overriding the negotiated selection in your code.

Verification

Validating and/or “pinning” the Twitter SSL Certificate in your code

Twitter’s SSL Certificates for api.twitter.com are signed by Verisign. For Assets, such as those on si0.twimg.com (through si4.twimg.com), those certificates are signed by Verisign and/or Contendo depending on the geographically closest CDN server.

Your application should ensure that the certificate chain returned for the all Twitter servers is signed by one of our approved vendors (Verisign EV for twitter.com, Symantec for api.twitter.com, and Digicert for others) and not other CA roots.

As of this writing, api.twitter.com’s certificate is:

As of this writing, api.twitter.com is signed by the Symantec Class 3 Secure Server CA - G4 root certificate with serial: 51:3f:b9:74:38:70:b7:34:40:41:8d:30:93:06:99:ff. Your code should trust this Symantec “G4” root certificate.

Validate against the minimum number of root certificates

Don’t rely on the local operating system to validate the certificate if possible. This can be tampered with by malware, local IT staff, or other bad actors. Validate against the known vendors for api.twitter.com as listed above. Don’t include more certificates in your application’s trusted CA Root store from vendors that Twitter hasn’t listed.

We highly recommend adding all of Symantec’s, Verisign’s and Digicert’s Root Certificates to your trusted CA File. If one of our vendors signs a new key with a different root, your application will continue to work. Remember if you are retrieving assets over SSL, you wil also need to include the SSL root certificates listed in the CDN section, below.

Digicert — https://www.digicert.com/digicert-root-certificates.htm
Verisign — https://www.verisign.com/support/roots.html

Ensure the certificate returned by Twitter and Asset servers are not expired

Validate the “Not After” and “Not Before” attributes of the returned certificate against the current system time in UTC. If it’s expired (or not valid yet), return a warning and/or refuse to respond to the user request at all. Additionally, validate the system clock against a known, valid external time source and inform the user if their clock isn’t set correctly. Many users forget to set their system clock accurately! SSL verification is highly dependent on proper time settings in the host’s operating system.

Check CRLs and the OCSP status

Many applications do not check the Certificate Revocation List for returned certificates or rely on the OS to do so. Ensure that your application or SSL library is configured to force CRL and OCSP (Online Certificate Status Protocol) verification before accepting Twitter’s certificate.

CDNs

Background and Avatar Images and JavaScript served by Twitter come from a variety of CDN (Content Delivery Networks) to improve delivery performance. When serving images you must be careful not to leak information about the user’s connection. For example, if your API connection is via HTTPS, you should also show avatar images from HTTPS. You must also include the CA certificates for all of Twitter’s CDN roots if your code is responsible for making the HTTPS connections to those servers. Alternately, rely on the host operating system or browser for these CA certificates.

You should never mix content in your application. If you mix content, an observer monitoring the network connection could assemble (through traffic analysis) a list of who your user is communicating with, violating the user’s privacy. If connections start in HTTPS, keep them in HTTPS, always.

When showing tweets that contain media, use the media_url_https attribute for the HTTPS url to use when showing images.

Code Examples

When communicating with Twitter, it’s always best to use well-tested and predefined libraries to communicate with the API. If you have to write your own code to communicate with our servers, the following code examples in popular languages will help you to make proper SSL connections with full certificate validation.

Curl / LibCurl

CURL is frequently used for testing web applications and communication with the API. If you’re using libcurl in your applications, you will typically be required to supply your own CACert file, which is a list of accepted X509 root certificates for validation.

Twitter recommends that developers using TLS/SSL connections using libcurl verify that the CURLOPT_SSL_VERIFYPEER option is set to boolean value True (or integer value 1) and ensure that failure to return a successful verification results in a failed connection error rather than the establishment of an untrusted and unsecured connection. We also recommend that the SSL verifydepth be set to maximum (9) when possible.

From the command line, append the capath (or cafile) option to include a file containing the Verisign root CA certificate:

PHP

Ruby

Python

See this Stack Overflow post regarding SSL verification under Python. Depending on the Python version and SSL Library you are using, verification may be supported natively in the library, or you may have to extract the certificate from the connection and perform additional verification steps.

Handling Failure

Since Feb 26, 2014, api.twitter.com is returning 403 status code for all non-SSL incoming traffic. Your client code should be able to handle this error.

Always return a descriptive error message to the user so they can identify where blame should be placed for connection failures. For example, If you connect over TCP yet fail to validate the SSL certificate, identify this issue directly with a descriptive error message such as, “Connect succeeded, but SSL certificate verification failed.” Simply stating “Connection Failed” makes it extremely difficult to debug SSL related issues.

Proper error message production and handling will assist the user in handling these issues.

Provide an Indication of Security Status

If possible, you should show an indication of the current status between your application and Twitter. Some web browsers indicate this by offering a Lock Icon, while others indicate the current connection state with descriptive messaging.