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