1 """
2 This module contains the definition of the C{L{OpenIDStore}}
3 interface.
4 """
5
7 """
8 This is the interface for the store objects the OpenID library
9 uses. It is a single class that provides all of the persistence
10 mechanisms that the OpenID library needs, for both servers and
11 consumers.
12
13 @change: Version 2.0 removed the C{storeNonce}, C{getAuthKey}, and C{isDumb}
14 methods, and changed the behavior of the C{L{useNonce}} method
15 to support one-way nonces. It added C{L{cleanupNonces}},
16 C{L{cleanupAssociations}}, and C{L{cleanup}}.
17
18 @sort: storeAssociation, getAssociation, removeAssociation,
19 useNonce
20 """
21
23 """
24 This method puts a C{L{Association
25 <openid.association.Association>}} object into storage,
26 retrievable by server URL and handle.
27
28
29 @param server_url: The URL of the identity server that this
30 association is with. Because of the way the server
31 portion of the library uses this interface, don't assume
32 there are any limitations on the character set of the
33 input string. In particular, expect to see unescaped
34 non-url-safe characters in the server_url field.
35
36 @type server_url: C{str}
37
38
39 @param association: The C{L{Association
40 <openid.association.Association>}} to store.
41
42 @type association: C{L{Association
43 <openid.association.Association>}}
44
45
46 @return: C{None}
47
48 @rtype: C{NoneType}
49 """
50 raise NotImplementedError
51
53 """
54 This method returns an C{L{Association
55 <openid.association.Association>}} object from storage that
56 matches the server URL and, if specified, handle. It returns
57 C{None} if no such association is found or if the matching
58 association is expired.
59
60 If no handle is specified, the store may return any
61 association which matches the server URL. If multiple
62 associations are valid, the recommended return value for this
63 method is the one most recently issued.
64
65 This method is allowed (and encouraged) to garbage collect
66 expired associations when found. This method must not return
67 expired associations.
68
69
70 @param server_url: The URL of the identity server to get the
71 association for. Because of the way the server portion of
72 the library uses this interface, don't assume there are
73 any limitations on the character set of the input string.
74 In particular, expect to see unescaped non-url-safe
75 characters in the server_url field.
76
77 @type server_url: C{str}
78
79
80 @param handle: This optional parameter is the handle of the
81 specific association to get. If no specific handle is
82 provided, any valid association matching the server URL is
83 returned.
84
85 @type handle: C{str} or C{NoneType}
86
87
88 @return: The C{L{Association
89 <openid.association.Association>}} for the given identity
90 server.
91
92 @rtype: C{L{Association <openid.association.Association>}} or
93 C{NoneType}
94 """
95 raise NotImplementedError
96
98 """
99 This method removes the matching association if it's found,
100 and returns whether the association was removed or not.
101
102
103 @param server_url: The URL of the identity server the
104 association to remove belongs to. Because of the way the
105 server portion of the library uses this interface, don't
106 assume there are any limitations on the character set of
107 the input string. In particular, expect to see unescaped
108 non-url-safe characters in the server_url field.
109
110 @type server_url: C{str}
111
112
113 @param handle: This is the handle of the association to
114 remove. If there isn't an association found that matches
115 both the given URL and handle, then there was no matching
116 handle found.
117
118 @type handle: C{str}
119
120
121 @return: Returns whether or not the given association existed.
122
123 @rtype: C{bool} or C{int}
124 """
125 raise NotImplementedError
126
127 - def useNonce(self, server_url, timestamp, salt):
128 """Called when using a nonce.
129
130 This method should return C{True} if the nonce has not been
131 used before, and store it for a while to make sure nobody
132 tries to use the same value again. If the nonce has already
133 been used or the timestamp is not current, return C{False}.
134
135 You may use L{openid.store.nonce.SKEW} for your timestamp window.
136
137 @change: In earlier versions, round-trip nonces were used and
138 a nonce was only valid if it had been previously stored
139 with C{storeNonce}. Version 2.0 uses one-way nonces,
140 requiring a different implementation here that does not
141 depend on a C{storeNonce} call. (C{storeNonce} is no
142 longer part of the interface.)
143
144 @param server_url: The URL of the server from which the nonce
145 originated.
146
147 @type server_url: C{str}
148
149 @param timestamp: The time that the nonce was created (to the
150 nearest second), in seconds since January 1 1970 UTC.
151 @type timestamp: C{int}
152
153 @param salt: A random string that makes two nonces from the
154 same server issued during the same second unique.
155 @type salt: str
156
157 @return: Whether or not the nonce was valid.
158
159 @rtype: C{bool}
160 """
161 raise NotImplementedError
162
164 """Remove expired nonces from the store.
165
166 Discards any nonce from storage that is old enough that its
167 timestamp would not pass L{useNonce}.
168
169 This method is not called in the normal operation of the
170 library. It provides a way for store admins to keep
171 their storage from filling up with expired data.
172
173 @return: the number of nonces expired.
174 @returntype: int
175 """
176 raise NotImplementedError
177
179 """Remove expired associations from the store.
180
181 This method is not called in the normal operation of the
182 library. It provides a way for store admins to keep
183 their storage from filling up with expired data.
184
185 @return: the number of associations expired.
186 @returntype: int
187 """
188 raise NotImplementedError
189
191 """Shortcut for C{L{cleanupNonces}()}, C{L{cleanupAssociations}()}.
192
193 This method is not called in the normal operation of the
194 library. It provides a way for store admins to keep
195 their storage from filling up with expired data.
196 """
197 return self.cleanupNonces(), self.cleanupAssociations()
198