extlib/Auth/OpenID/Interface.php

   1 <?php
   2
   3 /**
   4  * This file specifies the interface for PHP OpenID store implementations.
   5  *
   6  * PHP versions 4 and 5
   7  *
   8  * LICENSE: See the COPYING file included in this distribution.
   9  *
  10  * @package OpenID
  11  * @author JanRain, Inc. <openid@janrain.com>
  12  * @copyright 2005-2008 Janrain, Inc.
  13  * @license http://www.apache.org/licenses/LICENSE-2.0 Apache
  14  */
  15
  16 /**
  17  * This is the interface for the store objects the OpenID library
  18  * uses. It is a single class that provides all of the persistence
  19  * mechanisms that the OpenID library needs, for both servers and
  20  * consumers.  If you want to create an SQL-driven store, please see
  21  * then {@link Auth_OpenID_SQLStore} class.
  22  *
  23  * Change: Version 2.0 removed the storeNonce, getAuthKey, and isDumb
  24  * methods, and changed the behavior of the useNonce method to support
  25  * one-way nonces.
  26  *
  27  * @package OpenID
  28  * @author JanRain, Inc. <openid@janrain.com>
  29  */
  30 class Auth_OpenID_OpenIDStore {
  31     /**
  32      * This method puts an Association object into storage,
  33      * retrievable by server URL and handle.
  34      *
  35      * @param string $server_url The URL of the identity server that
  36      * this association is with. Because of the way the server portion
  37      * of the library uses this interface, don't assume there are any
  38      * limitations on the character set of the input string. In
  39      * particular, expect to see unescaped non-url-safe characters in
  40      * the server_url field.
  41      *
  42      * @param Association $association The Association to store.
  43      */
  44     function storeAssociation($server_url, $association)
  45     {
  46         trigger_error("Auth_OpenID_OpenIDStore::storeAssociation ".
  47                       "not implemented", E_USER_ERROR);
  48     }
  49
  50     /*
  51      * Remove expired nonces from the store.
  52      *
  53      * Discards any nonce from storage that is old enough that its
  54      * timestamp would not pass useNonce().
  55      *
  56      * This method is not called in the normal operation of the
  57      * library.  It provides a way for store admins to keep their
  58      * storage from filling up with expired data.
  59      *
  60      * @return the number of nonces expired
  61      */
  62     function cleanupNonces()
  63     {
  64         trigger_error("Auth_OpenID_OpenIDStore::cleanupNonces ".
  65                       "not implemented", E_USER_ERROR);
  66     }
  67
  68     /*
  69      * Remove expired associations from the store.
  70      *
  71      * This method is not called in the normal operation of the
  72      * library.  It provides a way for store admins to keep their
  73      * storage from filling up with expired data.
  74      *
  75      * @return the number of associations expired.
  76      */
  77     function cleanupAssociations()
  78     {
  79         trigger_error("Auth_OpenID_OpenIDStore::cleanupAssociations ".
  80                       "not implemented", E_USER_ERROR);
  81     }
  82
  83     /*
  84      * Shortcut for cleanupNonces(), cleanupAssociations().
  85      *
  86      * This method is not called in the normal operation of the
  87      * library.  It provides a way for store admins to keep their
  88      * storage from filling up with expired data.
  89      */
  90     function cleanup()
  91     {
  92         return array($this->cleanupNonces(),
  93                      $this->cleanupAssociations());
  94     }
  95
  96     /**
  97      * Report whether this storage supports cleanup
  98      */
  99     function supportsCleanup()
 100     {
 101         return true;
 102     }
 103
 104     /**
 105      * This method returns an Association object from storage that
 106      * matches the server URL and, if specified, handle. It returns
 107      * null if no such association is found or if the matching
 108      * association is expired.
 109      *
 110      * If no handle is specified, the store may return any association
 111      * which matches the server URL. If multiple associations are
 112      * valid, the recommended return value for this method is the one
 113      * most recently issued.
 114      *
 115      * This method is allowed (and encouraged) to garbage collect
 116      * expired associations when found. This method must not return
 117      * expired associations.
 118      *
 119      * @param string $server_url The URL of the identity server to get
 120      * the association for. Because of the way the server portion of
 121      * the library uses this interface, don't assume there are any
 122      * limitations on the character set of the input string.  In
 123      * particular, expect to see unescaped non-url-safe characters in
 124      * the server_url field.
 125      *
 126      * @param mixed $handle This optional parameter is the handle of
 127      * the specific association to get. If no specific handle is
 128      * provided, any valid association matching the server URL is
 129      * returned.
 130      *
 131      * @return Association The Association for the given identity
 132      * server.
 133      */
 134     function getAssociation($server_url, $handle = null)
 135     {
 136         trigger_error("Auth_OpenID_OpenIDStore::getAssociation ".
 137                       "not implemented", E_USER_ERROR);
 138     }
 139
 140     /**
 141      * This method removes the matching association if it's found, and
 142      * returns whether the association was removed or not.
 143      *
 144      * @param string $server_url The URL of the identity server the
 145      * association to remove belongs to. Because of the way the server
 146      * portion of the library uses this interface, don't assume there
 147      * are any limitations on the character set of the input
 148      * string. In particular, expect to see unescaped non-url-safe
 149      * characters in the server_url field.
 150      *
 151      * @param string $handle This is the handle of the association to
 152      * remove. If there isn't an association found that matches both
 153      * the given URL and handle, then there was no matching handle
 154      * found.
 155      *
 156      * @return mixed Returns whether or not the given association existed.
 157      */
 158     function removeAssociation($server_url, $handle)
 159     {
 160         trigger_error("Auth_OpenID_OpenIDStore::removeAssociation ".
 161                       "not implemented", E_USER_ERROR);
 162     }
 163
 164     /**
 165      * Called when using a nonce.
 166      *
 167      * This method should return C{True} if the nonce has not been
 168      * used before, and store it for a while to make sure nobody
 169      * tries to use the same value again.  If the nonce has already
 170      * been used, return C{False}.
 171      *
 172      * Change: In earlier versions, round-trip nonces were used and a
 173      * nonce was only valid if it had been previously stored with
 174      * storeNonce.  Version 2.0 uses one-way nonces, requiring a
 175      * different implementation here that does not depend on a
 176      * storeNonce call.  (storeNonce is no longer part of the
 177      * interface.
 178      *
 179      * @param string $nonce The nonce to use.
 180      *
 181      * @return bool Whether or not the nonce was valid.
 182      */
 183     function useNonce($server_url, $timestamp, $salt)
 184     {
 185         trigger_error("Auth_OpenID_OpenIDStore::useNonce ".
 186                       "not implemented", E_USER_ERROR);
 187     }
 188
 189     /**
 190      * Removes all entries from the store; implementation is optional.
 191      */
 192     function reset()
 193     {
 194     }
 195
 196 }