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

TypeKey is used by many bloggers to authenticate users prior to commenting. TypeKey is used in this way to combat comment spam. Application developers use TypeKey as an outsourced identity service. In other words, applications that require users to login prior to accessing the information within their account can have users login to TypeKey first and subsequently retrieve the user’s identity from TypeKey. This helps to speed up the development process as well as giving an application an instant user base of over several hundred thousand users.

The TypeKey Protocol

The following provides developers with the details necessary to implement a TypeKey enabled web site or application. Implementing the TypeKey protocol from scratch is not always necessary. Developers should consult the list of TypeKey implementations to see a TypeKey library already exists for their platform or development environment.

Versioning

This document describes version 1.1 of the TypeKey Authentication Protocol. Developers can designate the TypeKey protocol version they are utilizing in the requests they send to the TypeKey service. This allows for 100% backwards compatibility for all applications as the protocol evolves. If no version number is specified then the TypeKey service will respond using the most recent version of the TypeKey Authentication Profile.

Security

Listed below are the mechanisms used to make the TypeKey Authentication Protocol more secure:

• Authentication takes place over an encrypted SSL connect via HTTPS. HTTPS provides a secure channel through which a client and server can communicate.
• Embedded within the authentication response is a timestamp for which the authentication token should be valid. Clients, when properly implemented, should inspect this timestamp to protect against a “reply attack.”
• Authentication tokens are digitally signed by the TypeKey Authentication service so that clients can be sure that the authentication token they received came from an authentic TypeKey Authentication service.
• Only services with a valid TypeKey Token can utilize the TypeKey Authentication service.

Privacy

The following details how the TypeKey Authentication Service respects the privacy of every users’ personal information.

• The TypeKey Authentication service will not share a user’s email address with a service without that user’s express permission. An authenticating user can specify to share their email address with everyone by default, or can elect to share their email address on a case-by-case basis.
• The TypeKey Authentication service will at most only share the following information about an authenticating user: * The user’s display name (e.g. “Byrne Reese”) * The user’s nickname (e.g. reese99) ** The user’s email address, but only if expressly permitted

Implementation

TypeKey authentication is based on secure digital cryptography techniques including the Digital Signature Algorithm [4] and the Secure Hash Algorithm [1].

TypeKey Tokens

Applications using the TypeKey Authentication Protocol must first obtain a “TypeKey Token” that uniquely identifies the application and the URLs for which that token is allowed to operate.

To obtain, login to TypeKey and view your “Account Preferences.” Under “Weblog Preferences” you will find your TypeKey token and a list of URLs for which that token is valid.

Web Interface

To invite a user to login, add a link in your app to the following URL:

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

Include the following query string parameters:

• t – Required. The TypeKey token generated when you registered your app.
• _return – Required. 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 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.
• need_email - 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 acceptable to pass the email address.
• v - Optional. A value that identifies the version of the TypeKey protocol. If this value is not present, TypeKey will default to the most recent version of the protocol.

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, the TypeKey service will redirect the user’s browser back the to the URL specified by the _return query string parameter. TypeKey will also append the following parameters to the return to URL identifying the newly authenticated user:

• email - The user’s email address. If the authenticating user chose not to share their an email address with third parties then this parameter will contain the SHA1 hash [1] of the string “mailto:”. This is the same identifier used in the mbox_sha1sum field of the FOAF file format [2].
• name - This parameter supplies the user’s unique login name. The login should be unique within the scope of the auth service. Typically this parameter is not displayed publicly to the user, but rather is used to construct URLs to TypeKey user profile pages.
• nick - The user’s “display name,” or nickname. This is the name a 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 Unix epoch (1970-01-01 00:00:00 UTC). Note: 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 TypeKey DSA signature used to clients to verify the authenticity of the identity returned by TypeKey.

Creating the Signature

Signatures are used by the TypeKey service to certify the authenticity of a TypeKey identity. A client uses that signature to then verify the authenticity of a TypeKey identity it receives.

A DSA signature is generated from a string resulting from the concatenation of the following values, separated by double-colons:

• The user’s email address
• The user’s display name
• The user’s nickname or username
• The current timestamp
• The application’s TypeKey token, or the value passed to TypeKey using the ‘t’ parameter.

Example:

To give an example, if the authenticating user had the following properties:

• Name - “Napoleon Bonaparte”
• E-mail - napoleon@france.fr
• Username – napster

And the same authenticating user came from an application with a TypeKey token of “hql3XGNq1fB1cSjlCZ3i” on August 8, 2001 at 7:00pm then the DSA signature would be generated from the following string:

napoleon@france.fr::Napolon Bonaparte::napster::1000000800::hql3XGNq1fB1cSjlCZ3i

Verifying the Signature

To verify the signature contained with the sig parameter, a TypeKey client needs to perform the following steps:

1. Retrieve the TypeKey public DSA key from the following URL: http://www.typekey.com/extras/regkeys.txt
2. Verify that the time stamp contained within the ‘ts’ parameter is within a reasonably small window from “now.”
3. Construct the DSA “message” using the values given in the URL
4. Use the DSA verification algorithm to verify the signature.

The key should change only very occasionally, 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 de-serialized.

The “message” which has been signed is the concatenation of the five 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 fetched 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 white space. The fields are separated from their names by a ‘=’ character. An example is available in this text file. References

References

• [1] Secure Hash Standard, FIPS 180-1
• [2] FOAF Vocabulary Specification
• [3] Digital Signature Standard, FIPS 186
• [4] Digital Signature Algorithm, Wikipedia entry
• [5] RFC 1305, Network Time Protocol
• [6] RFC 3548, The Base16, Base32, and Base64 Data Encodings