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: }
197: