more docs and tests

zopefoundation · Jan 29, 2010 · e66f4a3 · e66f4a3
1 parent 1a8773a
commit e66f4a3
Showing 1 changed file with 174 additions and 20 deletions.
diff --git a/src/z3c/password/principal.txt b/src/z3c/password/principal.txt
@@ -185,94 +185,129 @@ Let's now reset the failure count.
   >>> user.failedAttempts = 0
 
 
-failedAttempts, non-resource
-----------------------------
+failedAttemptCheck, non-resource
+---------------------------------
 
   >>> import zope.security.management
   >>> from z3c.password import testing
 
+Set the option on the user:
+
   >>> user.failedAttemptCheck = interfaces.TML_CHECK_NONRESOURCE
 
-  >>> request = testing.TestBrowserRequest('http://localhost/@@/logo.gif')
+Create our dummy request:
+Watch out! this is a request for a resource (/@@/)
 
+  >>> request = testing.TestBrowserRequest('http://localhost/@@/logo.gif')
   >>> zope.security.management.getInteraction().add(request)
 
-  >>> user.failedAttempts
-  0
+Reset the counter:
+
+  >>> user.failedAttempts = 0
+
+Here's the password checking.
+The password is wrong.
 
   >>> user.checkPassword('456456')
   False
 
+But the counter is not incremented.
+
   >>> user.failedAttempts
   0
 
-  >>> zope.security.management.getInteraction().remove(request)
+Try a non-resource request.
 
+  >>> zope.security.management.getInteraction().remove(request)
   >>> request = testing.TestBrowserRequest('http://localhost/loginform.html',
   ...     'POST')
-
   >>> zope.security.management.getInteraction().add(request)
 
+Password is still wrong.
+
   >>> user.checkPassword('456456')
   False
 
+But now the counter is incremented.
+
   >>> user.failedAttempts
   1
 
-  >>> user.failedAttempts = 0
+Try now without a request in effect (as an edge case):
 
   >>> zope.security.management.getInteraction().remove(request)
 
+  >>> user.failedAttempts = 0
+
+A bad password gets counted.
+
   >>> user.checkPassword('456456')
   False
-
   >>> user.failedAttempts
   1
 
-failedAttempts, POST
---------------------
+failedAttemptCheck, POST
+-------------------------
 
-  >>> user.failedAttempts = 0
+Set the option on the user:
 
   >>> user.failedAttemptCheck = interfaces.TML_CHECK_POSTONLY
 
-  >>> request = testing.TestBrowserRequest('http://localhost/index.html', 'GET')
+Create our dummy request:
+Watch out! this is a normal GET request.
 
+  >>> request = testing.TestBrowserRequest('http://localhost/index.html', 'GET')
   >>> zope.security.management.getInteraction().add(request)
 
-  >>> user.failedAttempts
-  0
+  >>> user.failedAttempts = 0
+
+Here's the password checking.
+The password is wrong.
 
   >>> user.checkPassword('456456')
   False
 
+But the counter is not incremented.
+
   >>> user.failedAttempts
   0
 
-  >>> zope.security.management.getInteraction().remove(request)
+Try a POST request. What a loginform usually is.
+(Note, that the request gets examined only if the password does not match.)
 
+  >>> zope.security.management.getInteraction().remove(request)
   >>> request = testing.TestBrowserRequest('http://localhost/loginform.html',
   ...     'POST')
-
   >>> zope.security.management.getInteraction().add(request)
 
+Password is still wrong.
+
   >>> user.checkPassword('456456')
   False
 
+But now the counter is incremented.
+
   >>> user.failedAttempts
   1
 
-  >>> user.failedAttempts = 0
+Try now without a request in effect (as an edge case):
 
   >>> zope.security.management.getInteraction().remove(request)
 
+  >>> user.failedAttempts = 0
+
+A bad password gets counted.
+
   >>> user.checkPassword('456456')
   False
-
   >>> user.failedAttempts
   1
 
-expired password
+Reset the option on the user:
+
+  >>> user.failedAttemptCheck = None
+
+Expired password
 ----------------
 
 Next we expire the password:
@@ -494,6 +529,125 @@ The admin(?) has to reset the password of the user.
   >>> user.checkPassword('234234')
   True
 
+failedAttemptCheck, non-resource
+---------------------------------
+
+Set the option on the utility:
+
+  >>> poptions.failedAttemptCheck = interfaces.TML_CHECK_NONRESOURCE
+
+Create our dummy request:
+Watch out! this is a request for a resource (/@@/)
+
+  >>> request = testing.TestBrowserRequest('http://localhost/@@/logo.gif')
+  >>> zope.security.management.getInteraction().add(request)
+
+Reset the counter:
+
+  >>> user.failedAttempts = 0
+
+Here's the password checking.
+The password is wrong.
+
+  >>> user.checkPassword('456456')
+  False
+
+But the counter is not incremented.
+
+  >>> user.failedAttempts
+  0
+
+Try a non-resource request.
+
+  >>> zope.security.management.getInteraction().remove(request)
+  >>> request = testing.TestBrowserRequest('http://localhost/loginform.html',
+  ...     'POST')
+  >>> zope.security.management.getInteraction().add(request)
+
+Password is still wrong.
+
+  >>> user.checkPassword('456456')
+  False
+
+But now the counter is incremented.
+
+  >>> user.failedAttempts
+  1
+
+Try now without a request in effect (as an edge case):
+
+  >>> zope.security.management.getInteraction().remove(request)
+
+  >>> user.failedAttempts = 0
+
+A bad password gets counted.
+
+  >>> user.checkPassword('456456')
+  False
+  >>> user.failedAttempts
+  1
+
+failedAttemptCheck, POST
+-------------------------
+
+Set the option on the utility:
+
+  >>> poptions.failedAttemptCheck = interfaces.TML_CHECK_POSTONLY
+
+Create our dummy request:
+Watch out! this is a normal GET request.
+
+  >>> request = testing.TestBrowserRequest('http://localhost/index.html', 'GET')
+  >>> zope.security.management.getInteraction().add(request)
+
+  >>> user.failedAttempts = 0
+
+Here's the password checking.
+The password is wrong.
+
+  >>> user.checkPassword('456456')
+  False
+
+But the counter is not incremented.
+
+  >>> user.failedAttempts
+  0
+
+Try a POST request. What a loginform usually is.
+(Note, that the request gets examined only if the password does not match.)
+
+  >>> zope.security.management.getInteraction().remove(request)
+  >>> request = testing.TestBrowserRequest('http://localhost/loginform.html',
+  ...     'POST')
+  >>> zope.security.management.getInteraction().add(request)
+
+Password is still wrong.
+
+  >>> user.checkPassword('456456')
+  False
+
+But now the counter is incremented.
+
+  >>> user.failedAttempts
+  1
+
+Try now without a request in effect (as an edge case):
+
+  >>> zope.security.management.getInteraction().remove(request)
+
+  >>> user.failedAttempts = 0
+
+A bad password gets counted.
+
+  >>> user.checkPassword('456456')
+  False
+  >>> user.failedAttempts
+  1
+
+Reset the option on the utility:
+
+  >>> poptions.failedAttemptCheck = None
+
 
 Timed lockout
 -------------