libs/openid/store/interface.py

   1 """
   2 This module contains the definition of the C{L{OpenIDStore}}
   3 interface.
   4 """
   5
   6 class OpenIDStore(object):
   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
  22     def storeAssociation(self, server_url, association):
  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
  52     def getAssociation(self, server_url, handle=None):
  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
  97     def removeAssociation(self, server_url, handle):
  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
 163     def cleanupNonces(self):
 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
 178     def cleanupAssociations(self):
 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
 190     def cleanup(self):
 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()