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