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 */
30class 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}
197