Feel free to use SSL to protect communications between Twilio and your web application. Just specify an HTTPS url. Note: Twilio cannot currently handle self signed certificates.
Twilio supports HTTP Basic and Digest Authentication. This allows you to password protect your TwiML URLs on your web server so that only you and Twilio can access them. You may provide a username and password via the following URL format.
https://username:password@www.myserver.com/my_secure_document
Twilio will authenticate to your web server using the provided username and password and will remain logged in for the duration of the call. It is highly recommended that you use HTTP Authentication in conjunction with SSL. For more information on Basic and Digest Authentication, refer to your web server documentation.
If your application exposes sensitive data, or is possibly mutative to your data, then you may want to be sure that the HTTP requests to your web application are indeed coming from Twilio, and not a malicious third party. To allow you this level of security, Twilio cryptographically signs its requests. Here's how it works:
Then, on your end, if you want to verify the authenticity of the request, you can re-assemble the data string by going through the exact same process. If our two hashes match, then the request was authentic. You can then be sure that all the data used to construct the hash, including the full URL, query string and POST parameters were all sent to you by Twilio. Here's how you would perform the validation on your end:
Let's walk through an example request. Let's say Twilio made a POST to your page:
https://mycompany.com/myapp.php?foo=1&bar=2
And let's say Twilio posted some digits from a <Gather> to that url, in addition to all the usual POST fields
Create a string that is your URL with the full query string:
https://mycompany.com/myapp.php?foo=1&bar=2
Sort the list of POST variables by the parameter name (using Unix-style case-sensitive sorting order):
Append each POST variable, name and value, to the string with no delimiters:
https://mycompany.com/myapp.php?foo=1&bar=2CallSidCA1234567890ABCDECaller+14158675309Digits1234From+14158675309To+18005551212
Hash the resulting string using HMAC-SHA1, using your AuthToken as the key. Let's suppose your AuthToken is 12345. Then take the hash value returned from the following function call (or its equivalent in your language of choice):
hmac_sha1(https://mycompany.com/myapp.php?foo=1&bar=2CallSidCA1234567890ABCDECaller+14158675309Digits1234From+14158675309To+18005551212, 12345)
Now take the Base64 encoding of the hash value (so it's only ASCII characters):
HpS7PBa1Agvt4OtO+wZp75IuQa0=
Compare that to the hash Twilio sent in the X-Twilio-Signature HTTP header. Match them up FTW!
Here is an example written in PHP:
<?php
// This function calculates the HMAC hash of the data with the key passed in
// Note: hash_hmac requires PHP 5 >= 5.1.2 or PECL hash:1.1-1.5
// Or http://pear.php.net/package/Crypt_HMAC/
function calculate_twilio_signature($key, $data) {
$sig = base64_encode(hash_hmac("sha1", $data, $key, true));
return $sig;
}
// this function assembles the data to sign from the $_SERVER and $_POST superglobals
function build_twilio_data_string() {
// Our data string starts with the full URL
// Note, that if your URL uses an implied "index" document (index.php), then apache
// often adds a slash to the SCRIPT_URI while Twilio's original request will not have a slash
// Example: if Twilio requested http://mycompany.com/twilio
// and that url is handled by an index.php script
// Apache/PHP will report the URI as being: http://mycompany.com/twilio/
// But the hash should be calculated without the trailing slash
// Also note, if you're using URL rewriting, then you should check to see that
// PHP is reporting your SCRIPT_URI and QUERY_STRING correctly.
$string_to_sign = $_SERVER['SCRIPT_URI'];
// if there's a query string, add it here along with the question mark
if(strlen($_SERVER['QUERY_STRING']))
$string_to_sign .= "?{$_SERVER['QUERY_STRING']}";
// Now, if it's a POST, then we need to add the POST parameters
// alphabetized to the data string
if(isset($_POST)) {
// copy the post data
$data = $_POST;
// sort the array by keys
ksort($data);
// append them to the data string in order with no delimiters
foreach($data AS $key=>$value)
$string_to_sign .= "$key$value";
}
return $string_to_sign;
}
// Use your Twilio AuthToken here. Case matters.
$MY_KEY = "1234567890ABCDEF";
// Get the signature sent by twilio in the HTTP Headers
// PHP exposes HTTP headers in the $_SERVER superglobal array
// in all upper case, with underscores instead of dashes, with the word "HTTP_" prefixed
$expected_signature = $_SERVER["HTTP_X_TWILIO_SIGNATURE"];
// Build the data string to sign
$data_to_sign = build_twilio_data_string();
// sign it
$calculated_signature = calculate_twilio_signature($MY_KEY, $data_to_sign);
// if signatures match, then it's authenticated
if($calculated_signature == $expected_signature)
echo "Match!";
else
echo "Uh oh";
?>
All of the official Twilio Helper Libraries ship with a Utilities class which facilitates request validation. Head over to the libraries page to download the library for your language of choice.
Just a friendly reminder to keep your AuthToken secure. It not only enables access to the REST API, but also to request signatures.