[Summary view] [Print] [Text view]

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