head	1.5;
access;
symbols;
locks; strict;
comment	@# @;


1.5
date	2008.08.03.22.17.44;	author TWikiContributor;	state Exp;
branches;
next	1.4;

1.4
date	2008.01.22.03.21.26;	author TWikiContributor;	state Exp;
branches;
next	1.3;

1.3
date	2007.01.16.04.11.58;	author TWikiContributor;	state Exp;
branches;
next	1.2;

1.2
date	2006.06.25.16.26.33;	author TWikiContributor;	state Exp;
branches;
next	1.1;

1.1
date	2006.02.01.12.01.26;	author TWikiContributor;	state Exp;
branches;
next	;


desc
@new-topic
@


1.5
log
@buildrelease
@
text
@---+ Package =TWiki::Users::Password=

Base class of all password handlers. Default behaviour is no passwords,
so anyone can be anyone they like.

The methods of this class should be overridded by subclasses that want
to implement other password handling methods.


%TOC%

---++ ClassMethod *new* <tt>($session) -> $object</tt>

Constructs a new password handler of this type, referring to $session
for any required TWiki services.



---++ ObjectMethod *finish* <tt>()</tt>
Break circular references.



---++ ObjectMethod *readOnly* <tt>() -> boolean</tt>

returns true if the password database is not currently modifyable
also needs to call
$this->{session}->enter_context('passwords_modifyable');
if you want to be able to use the existing TWikiUserMappingContrib ChangePassword topics



---++ ObjectMethod *fetchPass* <tt>($login) -> $passwordE</tt>

Implements TWiki::Password

Returns encrypted password if succeeds.
Returns 0 if login is invalid.
Returns undef otherwise.



---++ ObjectMethod *checkPassword* <tt>($login,$passwordU) -> $boolean</tt>

Finds if the password is valid for the given user.

Returns 1 on success, undef on failure.



---++ ObjectMethod *removeUser* <tt>($login) -> $boolean</tt>

Delete the users entry.



---++ ObjectMethod *setPassword* <tt>($login,$newPassU,$oldPassU) -> $boolean</tt>

If the $oldPassU matches matches the user's password, then it will
replace it with $newPassU.

If $oldPassU is not correct and not 1, will return 0.

If $oldPassU is 1, will force the change irrespective of
the existing password, adding the user if necessary.

Otherwise returns 1 on success, undef on failure.



---++ encrypt( $login, $passwordU, $fresh ) -> $passwordE

Will return an encrypted password. Repeated calls
to encrypt with the same login/passU will return the same passE.

However if the passU is changed, and subsequently changed _back_
to the old login/passU pair, then the old passE is no longer valid.

If $fresh is true, then a new password not based on any pre-existing
salt will be used. Set this if you are generating a completely
new password.


---++ ObjectMethod *error* <tt>() -> $string</tt>

Return any error raised by the last method call, or undef if the last
method call succeeded.



---++ ObjectMethod *isManagingEmails* <tt>() -> $boolean</tt>
Determines if this manager can store and retrieve emails. The password
manager is used in preference to the user mapping manager for storing
emails, on the basis that emails need to be secure, and the password
database is the most secure place. If a password manager does not
manage emails, then TWiki will fall back to using the user mapping
manager (which by default will store emails in user topics)

The default ('none') password manager does *not* manage emails.



---++ ObjectMethod *getEmails* <tt>($login) -> @@emails</tt>
Fetch the email address(es) for the given login. Default
behaviour is to return an empty list. Called by Users.pm.
Only used if =isManagingEmails= -> =true=.



---++ ObjectMethod *setEmails* <tt>($login,@@emails) -> $boolean</tt>
Set the email address(es) for the given login name. Returns true if
the emails were set successfully.
Default behaviour is a nop, which will result in the user mapping manager
taking over. Called by Users.pm.
Only used if =isManagingEmails= -> =true=.



---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@@users</tt>
Returns an array of login names that relate to a email address.
Defaut behaviour is a nop, which will result in the user mapping manager
being asked for its opinion. If subclass implementations return a value for
this, then the user mapping manager will *not* be asked.
Only used if =isManagingEmails= -> =true=.

Called by Users.pm.



---++ ObjectMethod *canFetchUsers* <tt>() -> boolean</tt>

returns true if the fetchUsers method is implemented and can return an iterator of users.
returns undef / nothing in this case, as we are unable to generate a list of users



---++ ObjectMethod *fetchUsers* <tt>() -> newTWiki::ListIterator(\@@users)</tt>

returns a TWikiIterator of loginnames from the password source. If AllowLoginNames is false
this is used to remove the need for a TWikiUsers topic.


@


1.4
log
@buildrelease
@
text
@d119 1
a119 1
---++ ObjectMethod *findLoginByEmail* <tt>($email) -> \@@users</tt>
@


1.3
log
@buildrelease
@
text
@d19 2
a20 1
---++ ObjectMethod *finish* <tt></tt>
d22 8
a29 4
Complete processing after the client's HTTP request has been responded
to.
   1 breaking circular references to allow garbage collection in persistent
     environments
d37 2
a38 1
Returns encrypted password if succeeds.  Returns 0 if login is invalid.
d43 1
a43 1
---++ ObjectMethod *checkPassword* <tt>($user,$passwordU) -> $boolean</tt>
d45 1
a45 1
Finds if the password is valid for the given login.
d51 1
a51 5
---++ ObjectMethod *deleteUser* <tt>($user) -> $boolean</tt>

Delete users entry.

Returns 1 on success, undef on failure.
d53 1
a55 1
---++ ObjectMethod *passwd* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
d57 1
a57 2
If the $oldPassU is undef, it will try to add the user, failing
if they are already there.
d59 1
a59 1
If the $oldPassU matches matches the login's password, then it will
d71 1
a71 1
---++ encrypt( $user, $passwordU, $fresh ) -> $passwordE
d74 1
a74 1
to encrypt with the same user/passU will return the same passE.
d77 1
a77 1
to the old user/passU pair, then the old passE is no longer valid.
d91 40
a130 1
---++ ObjectMethod *getEmails* <tt>($user) -> @@emails</tt>
d132 2
a133 2
Fetch the email address(es) for the given username. Default behaviour
is to look up the users' personal topic.
d137 1
a137 1
---++ ObjectMethod *setEmails* <tt>($user,@@emails)</tt>
d139 2
a140 1
Set the email address(es) for the given username in the user topic.
@


1.2
log
@buildrelease
@
text
@d20 1
d29 1
@


1.1
log
@buildrelease
@
text
@d19 8
@
