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
14 @cvar AUTH_KEY_LEN: The length of the auth key that should be
15 returned by the C{L{getAuthKey}} method.
16
17 @sort: storeAssociation, getAssociation, removeAssociation,
18 storeNonce, useNonce, getAuthKey, isDumb
19 """
20
21 AUTH_KEY_LEN = 20
22
24 """
25 This method puts a C{L{Association
26 <openid.association.Association>}} object into storage,
27 retrievable by server URL and handle.
28
29
30 @param server_url: The URL of the identity server that this
31 association is with. Because of the way the server
32 portion of the library uses this interface, don't assume
33 there are any limitations on the character set of the
34 input string. In particular, expect to see unescaped
35 non-url-safe characters in the server_url field.
36
37 @type server_url: C{str}
38
39
40 @param association: The C{L{Association
41 <openid.association.Association>}} to store.
42
43 @type association: C{L{Association
44 <openid.association.Association>}}
45
46
47 @return: C{None}
48
49 @rtype: C{NoneType}
50 """
51 raise NotImplementedError
52
54 """
55 This method returns an C{L{Association
56 <openid.association.Association>}} object from storage that
57 matches the server URL and, if specified, handle. It returns
58 C{None} if no such association is found or if the matching
59 association is expired.
60
61 If no handle is specified, the store may return any
62 association which matches the server URL. If multiple
63 associations are valid, the recommended return value for this
64 method is the one that will remain valid for the longest
65 duration.
66
67 This method is allowed (and encouraged) to garbage collect
68 expired associations when found. This method must not return
69 expired associations.
70
71
72 @param server_url: The URL of the identity server to get the
73 association for. Because of the way the server portion of
74 the library uses this interface, don't assume there are
75 any limitations on the character set of the input string.
76 In particular, expect to see unescaped non-url-safe
77 characters in the server_url field.
78
79 @type server_url: C{str}
80
81
82 @param handle: This optional parameter is the handle of the
83 specific association to get. If no specific handle is
84 provided, any valid association matching the server URL is
85 returned.
86
87 @type handle: C{str} or C{NoneType}
88
89
90 @return: The C{L{Association
91 <openid.association.Association>}} for the given identity
92 server.
93
94 @rtype: C{L{Association <openid.association.Association>}} or
95 C{NoneType}
96 """
97 raise NotImplementedError
98
100 """
101 This method removes the matching association if it's found,
102 and returns whether the association was removed or not.
103
104
105 @param server_url: The URL of the identity server the
106 association to remove belongs to. Because of the way the
107 server portion of the library uses this interface, don't
108 assume there are any limitations on the character set of
109 the input string. In particular, expect to see unescaped
110 non-url-safe characters in the server_url field.
111
112 @type server_url: C{str}
113
114
115 @param handle: This is the handle of the association to
116 remove. If there isn't an association found that matches
117 both the given URL and handle, then there was no matching
118 handle found.
119
120 @type handle: C{str}
121
122
123 @return: Returns whether or not the given association existed.
124
125 @rtype: C{bool} or C{int}
126 """
127 raise NotImplementedError
128
129
131 """
132 Stores a nonce. This is used by the consumer to prevent
133 replay attacks.
134
135
136 @param nonce: The nonce to store.
137
138 @type nonce: C{str}
139
140
141 @return: C{None}
142
143 @rtype: C{NoneType}
144 """
145 raise NotImplementedError
146
148 """
149 This method is called when the library is attempting to use a
150 nonce. If the nonce is in the store, this method removes it
151 and returns a value which evaluates as true. Otherwise it
152 returns a value which evaluates as false.
153
154 This method is allowed and encouraged to treat nonces older
155 than some period (a very conservative window would be 6 hours,
156 for example) as no longer existing, and return False and
157 remove them.
158
159
160 @param nonce: The nonce to use.
161
162 @type nonce: C{str}
163
164
165 @return: Whether or not the nonce was valid.
166
167 @rtype: C{bool} or C{int}
168 """
169 raise NotImplementedError
170
172 """
173 This method returns a key used to sign the tokens, to
174 ensure that they haven't been tampered with in transit. It
175 should return the same key every time it is called. The key
176 returned should be C{L{AUTH_KEY_LEN}} bytes long.
177
178 @return: The key. It should be C{L{AUTH_KEY_LEN}} bytes in
179 length, and use the full range of byte values. That is,
180 it should be treated as a lump of binary data stored in a
181 C{str} instance.
182
183 @rtype: C{str}
184 """
185 raise NotImplementedError
186
188 """
189 This method must return C{True} if the store is a
190 dumb-mode-style store. Unlike all other methods in this
191 class, this one provides a default implementation, which
192 returns C{False}.
193
194 In general, any custom subclass of C{L{OpenIDStore}} won't
195 override this method, as custom subclasses are only likely to
196 be created when the store is fully functional.
197
198 @return: C{True} if the store works fully, C{False} if the
199 consumer will have to use dumb mode to use this store.
200
201 @rtype: C{bool}
202 """
203 return False