lib/TWiki/Users/Password.pm
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     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;