## Apache Zeta Components Manual :: Docs For Class ezcAuthenticationTypekeyFilter

### Authentication::ezcAuthenticationTypekeyFilter

### Class ezcAuthenticationTypekeyFilter

Filter to authenticate against TypeKey.

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();
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();
9. $credentials=new ezcAuthenticationIdCredentials ($token);
10. $authentication=new ezcAuthentication ($credentials);
11. $authentication->session=$session;
13. $filter=new ezcAuthenticationTypekeyFilter ();
14. $authentication->addFilter($filter);
15. // add other filters if needed
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($statusas$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();
  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. );

Source for this file: /Authentication/src/filters/typekey/typekey_filter.php

### Implements interfaces:

- ezcAuthenticationDataFetch

    ezcAuthenticationFilter
       |
       --ezcAuthenticationTypekeyFilter

Version: | //autogen//

### 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

##### Exceptions:

Type | Description
--- | ---
`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. );

##### Implementation of:

Method | Description
--- | ---
`ezcAuthenticationDataFetch::fetchData()` | Returns the extra data fetched during the authentication process.

#### 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

##### Exceptions:

Type | Description
--- | ---
`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

##### Implementation of:

Method | Description
--- | ---
`ezcAuthenticationDataFetch::registerFetchData()` | Registers which extra data to fetch during the authentication process.

#### run

int run( ezcAuthenticationIdCredentials $credentials )

Runs the filter and returns a status code when finished.

##### Parameters:

Name | Type | Description
--- | --- | ---
`$credentials` | ezcAuthenticationIdCredentials | Authentication credentials

##### Exceptions:

Type | Description
--- | ---
`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.

Documentation generated by phpDocumentor 1.4.3