lib/TWiki/Users/Password.pm
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
     1 # Module of TWiki Enterprise Collaboration Platform, http://TWiki.org/
     2 #
     3 # Copyright (C) 1999-2007 Peter Thoeny, peter@thoeny.org
     4 # and TWiki Contributors. All Rights Reserved. TWiki Contributors
     5 # are listed in the AUTHORS file in the root of this distribution.
     6 # NOTE: Please extend that file, not this notice.
     7 #
     8 # This program is free software; you can redistribute it and/or
     9 # modify it under the terms of the GNU General Public License
    10 # as published by the Free Software Foundation; either version 2
    11 # of the License, or (at your option) any later version. For
    12 # more details read LICENSE in the root of this distribution.
    13 #
    14 # This program is distributed in the hope that it will be useful,
    15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
    16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
    17 #
    18 # As per the GPL, removal of this notice is prohibited.
    19 
    20 =begin twiki
    21 
    22 ---+ package TWiki::Users::Password
    23 
    24 Base class of all password handlers. Default behaviour is no passwords,
    25 so anyone can be anyone they like.
    26 
    27 The methods of this class should be overridded by subclasses that want
    28 to implement other password handling methods.
    29 
    30 =cut
    31 
    32 package TWiki::Users::Password;
    33 
    34 use strict;
    35 use Assert;
    36 
    37 =pod
    38 
    39 ---++ ClassMethod new( $session ) -> $object
    40 
    41 Constructs a new password handler of this type, referring to $session
    42 for any required TWiki services.
    43 
    44 =cut
    45 
    46 sub new {
    47     my( $class, $session ) = @_;
    48 
    49     my $this = bless( { session => $session }, $class );
    50     $this->{error} = undef;
    51     return $this;
    52 }
    53 
    54 =begin twiki
    55 
    56 ---++ ObjectMethod finish()
    57 Break circular references.
    58 
    59 =cut
    60 
    61 # Note to developers; please undef *all* fields in the object explicitly,
    62 # whether they are references or not. That way this method is "golden
    63 # documentation" of the live fields in the object.
    64 sub finish {
    65     my $this = shift;
    66     undef $this->{error};
    67     undef $this->{session};
    68 }
    69 
    70 =pod
    71 
    72 ---++ ObjectMethod readOnly(  ) -> boolean
    73 
    74 returns true if the password database is not currently modifyable
    75 also needs to call
    76 $this->{session}->enter_context('passwords_modifyable');
    77 if you want to be able to use the existing TWikiUserMappingContrib ChangePassword topics
    78 
    79 =cut
    80 
    81 sub readOnly {
    82     return 1;   #there _is_ no password file.
    83 }
    84 
    85 =pod
    86 
    87 ---++ ObjectMethod fetchPass( $login ) -> $passwordE
    88 
    89 Implements TWiki::Password
    90 
    91 Returns encrypted password if succeeds.
    92 Returns 0 if login is invalid.
    93 Returns undef otherwise.
    94 
    95 =cut
    96 
    97 sub fetchPass {
    98     return undef;
    99 }
   100 
   101 =pod
   102 
   103 ---++ ObjectMethod checkPassword( $login, $passwordU ) -> $boolean
   104 
   105 Finds if the password is valid for the given user.
   106 
   107 Returns 1 on success, undef on failure.
   108 
   109 =cut
   110 
   111 sub checkPassword {
   112     my $this = shift;
   113     $this->{error} = undef;
   114     return 1;
   115 }
   116 
   117 =pod
   118 
   119 ---++ ObjectMethod removeUser( $login ) -> $boolean
   120 
   121 Delete the users entry.
   122 
   123 =cut
   124 
   125 sub removeUser {
   126     my $this = shift;
   127     $this->{error} = undef;
   128     return 1;
   129 }
   130 
   131 
   132 =pod
   133 
   134 ---++ ObjectMethod setPassword( $login, $newPassU, $oldPassU ) -> $boolean
   135 
   136 If the $oldPassU matches matches the user's password, then it will
   137 replace it with $newPassU.
   138 
   139 If $oldPassU is not correct and not 1, will return 0.
   140 
   141 If $oldPassU is 1, will force the change irrespective of
   142 the existing password, adding the user if necessary.
   143 
   144 Otherwise returns 1 on success, undef on failure.
   145 
   146 =cut
   147 
   148 sub setPassword {
   149     my $this = shift;
   150     $this->{error} = 'System does not support changing passwords';
   151     return 1;
   152 }
   153 
   154 =pod
   155 
   156 ---++ encrypt( $login, $passwordU, $fresh ) -> $passwordE
   157 
   158 Will return an encrypted password. Repeated calls
   159 to encrypt with the same login/passU will return the same passE.
   160 
   161 However if the passU is changed, and subsequently changed _back_
   162 to the old login/passU pair, then the old passE is no longer valid.
   163 
   164 If $fresh is true, then a new password not based on any pre-existing
   165 salt will be used. Set this if you are generating a completely
   166 new password.
   167 
   168 =cut
   169 
   170 sub encrypt {
   171     return '';
   172 }
   173 
   174 =pod
   175 
   176 ---++ ObjectMethod error() -> $string
   177 
   178 Return any error raised by the last method call, or undef if the last
   179 method call succeeded.
   180 
   181 =cut
   182 
   183 sub error {
   184     my $this = shift;
   185 
   186     return $this->{error};
   187 }
   188 
   189 =pod
   190 
   191 ---++ ObjectMethod isManagingEmails() -> $boolean
   192 Determines if this manager can store and retrieve emails. The password
   193 manager is used in preference to the user mapping manager for storing
   194 emails, on the basis that emails need to be secure, and the password
   195 database is the most secure place. If a password manager does not
   196 manage emails, then TWiki will fall back to using the user mapping
   197 manager (which by default will store emails in user topics)
   198 
   199 The default ('none') password manager does *not* manage emails.
   200 
   201 =cut
   202 
   203 sub isManagingEmails {
   204     return 0;
   205 }
   206 
   207 =pod
   208 
   209 ---++ ObjectMethod getEmails($login) -> @emails
   210 Fetch the email address(es) for the given login. Default
   211 behaviour is to return an empty list. Called by Users.pm.
   212 Only used if =isManagingEmails= -> =true=.
   213 
   214 =cut
   215 
   216 sub getEmails {
   217     ASSERT(0, "should never be called") if DEBUG;
   218 }
   219 
   220 =pod
   221 
   222 ---++ ObjectMethod setEmails($login, @emails) -> $boolean
   223 Set the email address(es) for the given login name. Returns true if
   224 the emails were set successfully.
   225 Default behaviour is a nop, which will result in the user mapping manager
   226 taking over. Called by Users.pm.
   227 Only used if =isManagingEmails= -> =true=.
   228 
   229 =cut
   230 
   231 sub setEmails {
   232     ASSERT(0, "should never be called") if DEBUG;
   233 }
   234 
   235 =pod
   236 
   237 ---++ ObjectMethod findLoginByEmail($email) -> \@users
   238 Returns an array of login names that relate to a email address.
   239 Defaut behaviour is a nop, which will result in the user mapping manager
   240 being asked for its opinion. If subclass implementations return a value for
   241 this, then the user mapping manager will *not* be asked.
   242 Only used if =isManagingEmails= -> =true=.
   243 
   244 Called by Users.pm.
   245 
   246 =cut
   247 
   248 sub findUserByEmail {
   249     ASSERT(0, "should never be called") if DEBUG;
   250 }
   251 
   252 =pod 
   253 
   254 ---++ ObjectMethod canFetchUsers() -> boolean
   255 
   256 returns true if the fetchUsers method is implemented and can return an iterator of users.
   257 returns undef / nothing in this case, as we are unable to generate a list of users
   258 
   259 =cut
   260 
   261 sub canFetchUsers {
   262     return;
   263 }
   264 
   265 =pod 
   266 
   267 ---++ ObjectMethod fetchUsers() -> new TWiki::ListIterator(\@users)
   268 
   269 returns a TWikiIterator of loginnames from the password source. If AllowLoginNames is false
   270 this is used to remove the need for a TWikiUsers topic.
   271 
   272 =cut
   273 
   274 sub fetchUsers {
   275 
   276     die "not Implemented in Base class";
   277     #return new TWiki::ListIterator(\@users);
   278 }
   279 
   280 
   281 1;