Synopsis

TypeKey Authentication Protocol, Version 1.1

Summary

TypeKey is an authentication service that alllows distributed applications to handle log-ins in a simple and secure way, so that users only need one login across many TypeKey-enabled sites.

Applications that want to use the TypeKey service need to register for a TypeKey account. Doing so produces a token which the application can use to identify itself to TK, and this token is tied to a URL or set of URLs for which it can be used.

Versioning

This document describes version 1.1 of the TypeKey Authentication Protocol. TypeKey will behave according to this specification if the version string passed in the v parameter of the URL is 1.1.

Implementation

TypeKey authentication is based on secure digital cryptography techniques including the Digital Signature Algorithm and the Secure Hash Algorithm. Users can be confident that TypeKey-enabled apps have no access to their passwords or other sensitive profile information.

Apps can be confident that identity is hard to fake and measures are in place to prevent automated registration.

Interface

To invite a user to login, add a link in your app to

https://www.typekey.com/t/typekey/login

and include the following CGI parameters:

t
The TypeKey token generated when you registered your app.
need_email
This parameter is optional. If it is present and set to a non-zero value, TypeKey will pass the user's email address to the application as part of the authentication response.
Passing the email is done at the discretion of the user; The user will be presented with a page asking whether it is accetable to pass the email address.
_return
Once the user's identity has been ascertained, TypeKey redirects the user's browser to this URL. Several CGI parameters are appended, which contain the information that guarantees the the user's identity. These parameters are documented below under ``Parameters Passed to the Application''
Note that the _return parameter must lie within one of the URLs associated with the TypeKey Site Token.
v
A value that identifies the version of the TypeKey protocol. If this value is not present, it effectively has the value 1.
An application can expect that the TypeKey interface will be remain compatible over time for any given v parameter. However, Six Apart reserves the right to discontinue support for older versions. When a version is discontinued, TypeKey will display a message to the user.

TypeKey Response

Once the user has signed in with a valid TypeKey username and password, TypeKey will redirect the user's browser back the value given by the application in the _return parameteer, and TypeKey will append the following parameters which express the authentication.

email
The user's email address. If the user chose not to pass an email address, this field will contain the SHA1 hash [1] of the string ``mailto:<email>''. This is the same identifier used in the mbox_sha1sum field (http://xmlns.com/foaf/0.1/#term_mbox_sha1sum) of the FOAF file format [2].
name
This field supplies the user's unique login name. The login should be unique within the scope of the auth service. This is simply used to create the link to the unique profile page. Other than that, it's normally not displayed anywhere on the website, although MT template writers may use it in other ways.
nick
The user's ``display name'': the name by which the user wants to be known publicly. This field is not required to be unique amongst TypeKey users, and a single user's display name may change over time.
ts
This is the timestamp when the signature was generated, expressed as seconds since the epoch (1970-01-01 00:00:00 UTC). The application should ensure that the timestamp was generated within n seconds of the time it processes the auth response, where n is a reasonably small window, but large enough that typical network latencies and processing times will allow an end user's browser to receive the HTTP response from TypeKey and make the redirected request to the application server. The server running the application should be time-synchronized using NTP [5]. The exact size of this window will depend on the context of the application's use.
sig
The DSA signature of the string formed by concatenating the following values, separated by double-colons:
```
   <email>::<name>::<nick>::<ts>::<site-token>
```
<site-token> is the parameter <t> that was passed to TypeKey.

To give an example, if I was ``Napoleon Bonaparte'' <napoleon@france.fr> with a login name of 'napster', and I logged in from an app with TypeKey token hql3XGNq1fB1cSjlCZ3i at 2001-09-08 19:00:00 (or 1000000800 seconds from the epoch), sig would be the signature for this string:
```
  napoleon@france.fr::Napolon Bonaparte::napster::1000000800::hql3XGNq1fB1cSjlCZ3i
```
A DSA signature consists of two components, known as r and s. To serialize this signature for passing in the sig parameter, TypeKey encodes each piece, r and s, as Base64 [6], and the two are joined by a colon, as follows:
```
sig=<r-base64>:<s-base64>
```
Note that care must be taken to ensure that the component values are properly URL-decoded in order to validate the signature. The cleartext string which is not been URL-encoded.

Verifying the Signature

To verify the signature in the sig parameter, an application needs to take the following steps:

Fetch the TypeKey public DSA key
Verify that the ts parameter is within a small window of 'now.'
Construct the DSA ``message'' using the values given in the URL
Use the DSA verification algorithm to verify the signature.

Applications can fetch the public key from the following URL:

   http://www.typekey.com/extras/regkeys.txt

The key should change only very occassionally, and applications should cache the key thus fetched for a period of at least 24 hours. The key returned from this URL is serialized as described under ``Format of the DSA key,'' below, and will need to be deserialized.

The ``message'' which has been signed is the concatenation of the four fields:

   <email>::<name>::<nick>::<ts>::<site-token>

An application should construct this string and use the DSA verification algorithm to verify that sig is a signature of this message, using the key fetcheed from the public-key URL, above. If so, the browser which submitted this value is controlled by a user who knows the password for the Typekey account with the given fields.

Format of the DSA key

A public key for the Digital Signature Algorithm consists of four fields: p, q, g, and pub_key. When MT searches for a DSA key, it expects the four fields to be given in decimal, on one line of text, separated by whitespace. The fields are separated from their names by a '=' character. For example:

p=11671236708387678327224206536086899180337891539414163231548040398520841845883184000627860280911468857014406210406182985401875818712804278750455023001090753 g=8390523802553664927497849579280285206671739131891639945934584937465879937204060160958306281843225586442674344146773393578506632957361175802992793531760152 q=1096416736263180470838402356096058638299098593011 pub_key=10172504425160158571454141863297493878195176114077274329624884017831109225358009830193460871698707783589128269392033962133593624636454152482919340057145639

References

[1]

Secure Hash Standard, FIPS 180-1: http://www.itl.nist.gov/fipspubs/fip180-1.htm

[2]

FOAF Vocabulary Specification: http://xmlns.com/foaf/0.1/

[3]

Digital Dignature Standard, FIPS 186: http://www.itl.nist.gov/fipspubs/fip186.htm

[4]

Digital Signature Algorithm, Wikipedia entry: http://en.wikipedia.org/wiki/Digital_Signature_Algorithm

[5]

RFC 1305, Network Time Protocol: http://www.itl.nist.gov/fipspubs/fip186.htm

[6]

RFC 3548, The Base16, Base32, and Base64 Data Encodings http://www.faqs.org/rfcs/rfc3548.html