Dev: SM: V2 Authentication

From AAT Wiki
Jump to: navigation, search

URL Authentication

Requests to certain Map services now require digital signatures using a cryptographic key we provide to you for that purpose. The signing process combines a URL and a private key together using an encryption algorithm, creating a unique signature. This unique signature allows our web services to verify that any site generating requests that use your API Key are authorized to do so. The signature is also unique per URL, ensuring that requests that use your API Key cannot be modified without requiring a new signature to be generated.

Signed requests can retrieve results when sent from an unregistered URL.

We encourage you to begin converting all of your applications to incorporate signing of URL requests as we roll this feature out to additional web services.

Building a Valid URL

You may think that a "valid" URL is self-evident, but that's not quite the case. A URL entered within an address bar in a browser, for example, may contain special characters (e.g. "上海+中國"); the browser needs to internally translate those characters into a different encoding before transmission. By the same token, any code that generates or accepts UTF-8 input might treat URLs with UTF-8 characters as "valid", but would also need to translate those characters before sending them out to a web server. This process is called URL-encoding.

We need to translate special characters because all URLs need to conform to the syntax specified by the W3 Uniform Resource Identifier specification. In effect, this means that URLs must contain only a special subset of ASCII characters: the familiar alphanumeric symbols, and some reserved characters for use as control characters within URLs. The table below summarizes these characters:

SetcharactersURL usage
Alphanumeric
 a   b   c   d   e   f   g   h   i   j   k   l  m  
 n   o   p   q   r   s   t   u   v   w   x   y   z   
 A   B   C   D   E   F   G   H   I   J   K   L   M   
 N   O   P   Q   R   S   T   U   V   W   X   Y   Z
 0  1   2   3   4   5   6   7   8   9
Text strings, scheme usage (http), port (8080), etc.
Unreserved - _ . ~ Text strings
Reserved ! * ' ( ) ; : @ & = + $ , / ? % # [ ] Control characters and/or Text Strings


When building a valid URL, you must ensure that it contains only those characters shown above. Conforming a URL to use this set of characters generally leads to two issues, one of omission and one of substitution:

   * Characters that you wish to handle exist outside of the above set. For example, characters in foreign languages such as 上海+中國 need to be encoded using the above characters. 

By popular convention, spaces (which are not allowed within URLs) are often represented using the plus '+' character as well.

   * Characters exist within the above set as reserved characters, but need to be used literally. For example, ? is used within URLs to indicate the beginning of the query string; 

if you wish to use the string "? and the Mysterions," you'd need to encode the '?' character.

All characters to be URL-encoded are encoded using a '%' character and a two-character hex value corresponding to their UTF-8 character. For example, 上海+中國 in UTF-8 would be URL-encoded as %E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B. The string ? and the Mysterians would be URL-encoded as %3F+and+the+Mysterians.

Converting a URL that you receive from user input is sometimes tricky. For example, a user may enter an address as "5th&Main St." Generally, you should construct your URL from its parts, treating any user input as literal characters.

Additionally, URLs are limited to 2048 characters for all web services. For most services, this character limit will seldom be approached. However, note that certain services have several parameters that may result in long URLs.

The URL Signing Process

Signing a URL involves generating a signature using a private key shared between you and Streetmaps, which you attach to any HTTP (or HTTPS) requests. See How Do I Get My Private Key? below. You generate this signature for a URL using the private key, which creates a hash that is unique to that URL and the private key. If the URL differs in any way from that used to generate the signature, the service will reject the request as invalid.

Note: attempting to access a web service with an invalid signature will result in a HTTP 403 (Forbidden) error. As you convert your applications to use URL signing, make sure to test your signatures to ensure they initiate a valid request. You should first test whether the original URL is valid (See Building a Valid URL above) as well as test whether you generate the correct signatures (See Generating Valid Signatures below).

How Do I Get My Private Key?

You will find your cryptographic URL-signing key once you log into the API section of our maps [(https://www.streetmaps.co.za/api).] API Keys are issued to all Streetmaps API users, and to developers who apply to use the service. This private key is unique to your API Key. For that reason, please keep your key secure. This key — though used to generate the signature — should not be passed within any requests, stored on any websites, or posted to any public forum. Anyone obtaining this key "in the clear" could spoof requests using your identity.

Note that this cryptographic key is not the same as the (freely available) API Key.

Generating Valid Signatures

To aid debugging, make sure that your URLs are already valid before you sign them! Doing so allows you to focus on correcting invalid signatures if you discover errors when signing your URLs. See Building Valid URLs for more information.

The following steps outline the process you should use to sign a valid URL:

  1. Construct your URL, making sure to include your client and sensor parameters. Note that any non-standard characters will need to be URL-encoded:
       https://www.streetmaps.co.za/api/search?s1=village+road,+kloof&key=YOURAPIKEY        
     Note: all streetmaps services require UTF-8 character encoding (which implicitly includes ASCII). Make sure that if your applications operate using other character sets, that they construct URLs using UTF-8 and properly URL-encode them beforehand.
  2. Strip off the domain portion of the request, leaving only the path and the query:
       /api/search?s1=village+road,+kloof&key=YOURAPIKEY        
  3. Retrieve your private key, which is encoded in a modified Base64 for URLs *, and sign the URL above using the HMAC-SHA1 algorithm. You may need to decode this key into its original binary format. Note that in most cryptographic libraries, the resulting signature will be in binary format.
  4.Encode the resulting binary signature using the modified Base64 for URLs * to convert this signature into something that can be passed within a URL.
  5.Attach this signature to the URL within a signature parameter:
       https://www.streetmaps.co.za/api/search?s1=village+road,+kloof&key=YOURAPIKEY&signature=base64signature

To get the code to create the Signiture plase refer to http://gmaps-samples.googlecode.com/svn/trunk/urlsigning/index.html for your desired scripting language