Wednesday, May 18, 2011

Google REST Web Service Security C# URL Authentication

Google URL Signing

To access certain Google API web services a Client ID and a digital signature is required. A Client ID and a cryptographic key (used to generate a unique digital signature) are provided by Google once consumers have created an account. Before a REST web service request can be made, a digital signature must be generated and passed in as part of the URL, this process is known as URL signing. The cryptographic key, sometimes called shared secret/signing key must be kept secret and is never passed in as part of a URL request.

The following are required before a digital signature can be generated:

1) Construct request URL, the URL must be percent-encoded/URL encoded to ensure it is valid.

Constructing a valid URL

A URL is made up of reserved and unreserved characters. Reserved characters in a URL have a specific purpose, for example a ‘/ ’ separates the different parts of a URL. If a ‘/ ’ is required in a URL for any other purpose, then it must be percent-encoded to distinguish it from its reserved counterparts. Percent-encoded reserved characters are always preceded by a ‘%’ to indicate percent-encoding.

The following are reserved characters:

! * ' ( ) ; : @ & = + $ , / ? % # [ ]

To percent-encode a URL’s reserved characters, use the pair of hex digits which corresponds to each reserved character’s ASCII value, finish by preceding each hex digit pair with a ‘%’. If any reserved character is non-ASCII then use the pair of hex digits which corresponds to its UTF-8 character instead.

For example, to percent-encode a '/ ':

a) convert to or look up the ASCII value for a ‘/ ’, the ASCII value is 47

b) next look up the pair of hex digits which correspond to this ASCII value, the hex digit pair is 2F

The address parameter contains spaces, spaces are not allowed in a URL, it also contains a '&'. This URL must be encoded by replacing spaces with a '+', and replacing '&' with the two hex digits corresponding to its ASCII value.

Google provides a C# method for developers called ‘Sign’, this method accepts two string parameters and returns the signed URL request in full as a string. When calling this method the full URL and the signing key are passed in as the two parameters of type string, see the method below.

In some cases SSL (Secure Socket Layer) is used to provide transport level security when making requests. In these situations change the protocol from ‘http’ to ‘https’, before making the request.

Google Maps API Web Services require URL Authentication, documentation is provided on the URL signing process, how to produce valid URL's, SSL Access and processing XML results. See the following link for more information: