The filter deals with the validation of information returned by the TypeKey server in response to a login command.

Specifications: http://www.sixapart.com/typekey/api

In order to access a protected page, user logs in by using a request like:

• https://www.typekey.com/t/typekey/login? t=391jbj25WAQANzJrKvb5& _return=http://example.com/login.php

where:

• t = TypeKey token generated for each TypeKey account. It is found at https://www.typekey.com/t/typekey/prefs. This value is also used as a session key, so it must be passed to the page performing the TypeKey authentication via the _return URL.
• _return = the URL where to return after user logs in with his TypeKey username and password. The URL can contain query arguments, such as the value t which can be used as a session key.

The login link can also contain these 2 optional values:

• v = TypeKey version to use. Default is 1.
• need_email = the mail address which was used to register with TypeKey. It needs to be set to a value different than 0 in order to get the email address of the user when calling fetchData() after the authentication process has been completed.

So the TypeKey authentication filter will run in the _return page and will verify the signature and the other information in the URL.

The application link (eg. http://example.com) must be registered in the TypeKey preferences page (https://www.typekey.com/t/typekey/prefs) in one of the 5 lines from "Your Weblog Preferences", otherwise TypeKey will not accept the login request.

The link returned by TypeKey after user logs in with his TypeKey username and password looks like this:

• http://example.com/typekey.php? ts=1177319974&email=5098f1e87a608675ded4d933f31899cae6b4f968& name=ezc&nick=ezctest& sig=I9Dop72+oahY82bpL7ymBoxdQ+k=:Vj/t7oZVL2zMSzwHzdOWop5NG/g=

where:

• ts = timestamp (in seconds) of the TypeKey server time at login. The TypeKey filter compares this timestamp with the application server's timestamp to make sure the login is in a reasonable time window (specified by the validity option). Don't use a too small value for validity, because servers are not always synchronized.
• email = sha1 hash of "mailto:$mail", where $mail is the mail address used to register with TypeKey.
• nick = TypeKey nickname/display name.
• sig = signature which must be validated by the TypeKey filter.

For more information on the login request and the TypeKey response link see http://www.sixapart.com/typekey/api.

Example of use (authentication + input form):

 1.  <?php
 2.  // no headers should be sent before calling $session->start()
 3.   $session = new ezcAuthenticationSession();
 4.  $session->start();
 5.  
 6.  // $token is used as a key in the session to store the authenticated state between requests
 7.   $token = isset( $_GET['token'] ) ? $_GET['token'] : $session->load();
 8.  
 9.  $credentials = new ezcAuthenticationIdCredentials( $token );
10.  $authentication = new ezcAuthentication( $credentials );
11.  $authentication->session = $session;
12.  
13.  $filter = new ezcAuthenticationTypekeyFilter();
14.  $authentication->addFilter( $filter );
15.  // add other filters if needed
16.  
16.  
17.  if ( !$authentication->run() )
18.  {
19.      // authentication did not succeed, so inform the user
20.           $status = $authentication->getStatus();
21.      $err = array(
22.               'ezcAuthenticationTypekeyFilter' => array(
23.                   ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_INCORRECT => 'Signature returned by TypeKey is incorrect',
24.                   ezcAuthenticationTypekeyFilter::STATUS_SIGNATURE_EXPIRED => 'The signature returned by TypeKey expired'
25.                   ),
26.               'ezcAuthenticationSession' => array(
27.                   ezcAuthenticationSession::STATUS_EMPTY => '',
28.                   ezcAuthenticationSession::STATUS_EXPIRED => 'Session expired'
29.                   )
30.               );
31.      foreach ( $status as $line )
32.      {
33.          list( $key, $value ) = each( $line );
34.          echo $err[$key][$value] . "\n";
35.      }
36.  ?>
37.  <!-- OnSubmit hack to append the value of t to the _return value, to pass
38.       the TypeKey token after the TypeKey request -->
39.  <form method="GET" action="https://www.typekey.com/t/typekey/login" onsubmit="document.getElementById('_return').value += '?token=' + document.getElementById('t').value;">
40.  TypeKey token: <input type="text" name="t" id="t" />
41.  <input type="hidden" name="_return" id="_return" value="http://localhost/typekey.php" />
42.  <input type="submit" />
43.  </form>
44.  <?php
45.  }
46.  else
47.  {
48.      // authentication succeeded, so allow the user to see his content
49.           echo "<b>Logged-in</b>";
50.  }
51.  ?>

Another method, which doesn't use JavaScript, is using an intermediary page which saves the token in the session, then calls the TypeKey login page:

• original file is modified as follows:

  1.  <form method="GET" action="save_typekey.php">
  2.  TypeKey token: <input type="text" name="t" id="t" />
  3.  <input type="hidden" name="_return" id="_return" value="http://localhost/typekey.php" />
  4.  <input type="submit" />
  5.  </form>
  

• intermediary page:

   1.  <?php
   2.  // no headers should be sent before calling $session->start()
   3.   $session = new ezcAuthenticationSession();
   4.  $session->start();
   5.  
   6.  // $token is used as a key in the session to store the authenticated state between requests
   7.   $token = isset( $_GET['t'] ) ? $_GET['t'] : $session->load();
   8.  if ( $token !== null )
   9.  {
  10.      $session->save( $token );
  11.  }
  12.  $url = isset( $_GET['_return'] ) ? $_GET['_return'] : null;
  13.  $url .= "?token={$token}";
  14.  header( "Location: https://www.typekey.com/t/typekey/login?t={$token}&_return={$url}" );
  15.  ?>
  

Extra data can be fetched from the TypeKey server during the authentication process. Different from the other filters, for TypeKey there is no registration needed for fetching the extra data, because all the possible extra data is available in the response sent by the TypeKey server.

To be able to get the email address of the user, need_email must be set to a value different than 0 in the initial request sent to the TypeKey server (along with the t and _return values). Example:

• https://www.typekey.com/t/typekey/login?t=<token>&_return=<url>&need_email=1

Example of fetching the extra data after the initial request has been sent:

1.  // after run()
2.  // $filter is an ezcAuthenticationTypekeyFilter object
3.   $data = $filter->fetchData();

The $data array contains name (TypeKey username), nick (TypeKey display name) and optionally email (if the user allowed the sharing of his email address in the TypeKey profile page; otherwise it is not set).

1.  array( 'name' => array( 'john' ),
2.         'nick' => array( 'John Doe' ),
3.         'email' => array( 'john.doe@example.com' ) // or not set
4.             );

ezcAuthenticationFilter
   |
   --ezcAuthenticationTypekeyFilter

1.  array( 'name' => array( 'john' ),
2.         'nick' => array( 'John Doe' ),
3.         'email' => array( 'john.doe@example.com' ) // or not set
4.             );

Creates a new object of this class.

Checks the information returned by the TypeKey server.

Returns the extra data which was fetched during the authentication process.

The TypeKey extra data is an array containing the values for name (the TypeKey username), nick (the TypeKey display name) and email (the email address of the user, fetched only if the initial request to the TypeKey server contains need_email, and the user allowed the sharing of his email address).

Example of returned array:

1.  array( 'name' => array( 'john' ),
2.         'nick' => array( 'John Doe' ),
3.         'email' => array( 'john.doe@example.com' ) // or not set
4.             );

Fetches the public keys from the specified file or URL $file.

The file must be composed of space-separated values for p, g, q, and pub_key, like this: p=<value> g=<value> q=<value> pub_key=<value>

The format of the returned array is:

1.    array( 'p' => p_val, 'g' => g_val, 'q' => q_val, 'pub_key' => pub_key_val )

Registers the extra data which will be fetched by the filter during the authentication process.

For TypeKey there is no registration needed, because all the possible extra data is available in the response sent by the TypeKey server. So a call to this function is not needed.

To be able to get the email address of the user, need_email must be set to a value different than 0 in the initial request sent to the TypeKey server (along with the t and _return values).

Runs the filter and returns a status code when finished.