One of the things TeleSign is working on in Q1 is making our APIs available via a REST interface. Today all of our customers access our APIs via SOAP and we've definitely heard that folks want us to provide our APIs in an alternative form since almost all Web Services today use REST.When developing this API we wanted to make sure we were using best practices from a security perspective and that we were developing the API in a way that would be familiar and easy to implement for developers. Unlike SOAP, which has a specific protocol specification around the exchanging of structured information that can be used to create Web Services or other types of services, REST refers to a general software architecture and this architecture can then be used to create web services. In creating a RESTful API the developer then uses things like RFCs and other web standards to create the interface.
When creating the API one of our key goals other than making the API easy to use, extensible and highly performant was to use the very best practices in securing the interface. To be as secure as possible we've implemented HMAC (Hash-based Message Authentication Code) in our auth process to ensure that both communications are properly authenticated and that they can't be manipulated in transit.
To make HMAC work the first thing we do is allow users to share a secret with us. In this case the secret API-Key is generated automatically by TeleSign (to ensure that the key is truly random and not guessable) and then this key is given to the user in our web portal. In the new web portal users will be able to define expiration times for their keys and even be able to generate multiple keys so that they can rotate their keys with us.
The basic way HMAC authentication works is:
There are a few advantages to this method:
There are two additional items in our HMAC authentication that also offer security to the transaction:
The advantage of adding a “Date” to the signature string is that it limits the time frame, in which, if somehow a transaction is captured between the sender and recipient that that transaction can be replayed. While all communication between the sender and the recipient will be over SSL, it's always possible that there is some compromise in the sender's infrastructure such that data is captured before it is sent over the SSL channel. In this case the addition of Date allows TeleSign to define a window where we will only accept transactions for a given defined Date within a certain window.
The other thing we do to make sure that transaction can't be replayed is provide the customer the option to include a cryptographic nonce in the transaction. With a nonce included in the hash and passed to us as a header we can store the nonce for a set period of time that is the same as the Date window described above. Using the nonce even if a transaction is captured and the attacker is able to replay that transaction in the Date window, that transaction will only be good once if a nonce is included. If we see a duplicate transaction in a Date window with a duplicate nonce we'll know that the transaction is a bogus one and alarm bells will go off.