Path

ez components / documentation / api reference / 2009.2.1 / authentication


eZ Components 2009.2.1

Authentication: ezcAuthenticationTypekeyFilter

[ Tutorial ] [ Rfcs ] [ Security ] [ Class tree ] [ Element index ] [ ChangeLog ] [ Credits ]

Class: ezcAuthenticationTypekeyFilter

Filter to authenticate against TypeKey. [source]

Implemented Interfaces

The filter deals with the validation of information returned by the TypeKey server in response to a login command.
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.  
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"Locationhttps://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.       );

Parents

ezcAuthenticationFilter
   |
   --ezcAuthenticationTypekeyFilter

Constants

STATUS_SIGNATURE_EXPIRED = 3 Login is outside of the timeframe.
STATUS_SIGNATURE_INCORRECT = 2 Signature verification was incorect.
STATUS_SIGNATURE_MISSING = 1 The request does not contain the needed information (like $_GET['sig']).

Inherited Constants

From ezcAuthenticationFilter:
ezcAuthenticationFilter::STATUS_OK    Successful authentication.

Properties

ezcAuthenticationBignumLibrary read/write  $lib
The wrapper for the PHP extension to use for big number operations. This will be autodetected in the constructor, but you can specify your own wrapper before calling run().

Member Variables

protected array(string=>mixed) $data = array()
Holds the extra data fetched during the authentication process.

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).
Usually it has this structure:
 1.  array'name' => array'john' ),
 2.         'nick' => array'John Doe' ),
 3.         'email' => array'john.doe@example.com' // or not set
 4.       );

Inherited Member Variables

From ezcAuthenticationFilter:
protected  ezcAuthenticationFilter::$options

Method Summary

public ezcAuthenticationTypekeyFilter __construct( [$options = null] )
Creates a new object of this class.
protected bool checkSignature( $msg, $r, $s, $keys )
Checks the information returned by the TypeKey server.
public array(string=>mixed) fetchData( )
Returns the extra data which was fetched during the authentication process.
protected array(string=>string) fetchPublicKeys( $file )
Fetches the public keys from the specified file or URL $file.
public void registerFetchData( [$data = array()] )
Registers the extra data which will be fetched by the filter during the authentication process.
public int run( $credentials )
Runs the filter and returns a status code when finished.

Inherited Methods

From ezcAuthenticationFilter :
public ezcAuthenticationFilterOptions ezcAuthenticationFilter::getOptions()
Returns the options of this class.
public abstract int ezcAuthenticationFilter::run()
Runs the filter and returns a status code when finished.
public void ezcAuthenticationFilter::setOptions()
Sets the options of this class to $options.

Methods

__construct

ezcAuthenticationTypekeyFilter __construct( [ezcAuthenticationTypekeyOptions $options = null] )
Creates a new object of this class.

Parameters

Name Type Description
$options ezcAuthenticationTypekeyOptions Options for this class

Throws

ClassDescription
ezcBaseExtensionNotFoundException if neither of the PHP gmp and bcmath extensions are installed

checkSignature

bool checkSignature( string $msg, string $r, string $s, array(string=>string) $keys )
Checks the information returned by the TypeKey server.

Parameters

Name Type Description
$msg string Plain text signature which needs to be verified
$r string First part of the signature retrieved from TypeKey
$s string Second part of the signature retrieved from TypeKey
$keys array(string=>string) Public keys retrieved from TypeKey

fetchData

array(string=>mixed) fetchData( )
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.       );

fetchPublicKeys

array(string=>string) fetchPublicKeys( string $file )
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 )

Parameters

Name Type Description
$file string The public keys file or URL

Throws

ClassDescription
ezcAuthenticationTypekeyPublicKeysInvalidException if the keys fetched from the TypeKey public keys file are invalid
ezcAuthenticationTypekeyPublicKeysMissingException if the keys from the TypeKey public keys file could not be fetched

registerFetchData

void registerFetchData( [ $data = array()] )
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).

Parameters

Name Type Description
$data array(string) A list of attributes to fetch during authentication

run

int run( ezcAuthenticationIdCredentials $credentials )
Runs the filter and returns a status code when finished.

Parameters

Name Type Description
$credentials ezcAuthenticationIdCredentials Authentication credentials

Throws

ClassDescription
ezcAuthenticationTypekeyException if the keys from the TypeKey public keys file could not be fetched

Redefinition of

Method Description
ezcAuthenticationFilter::run() Runs the filter and returns a status code when finished.

Last updated: Tue, 23 Mar 2010