data/TWiki/TWikiUsersPasswordDotPm.txt
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
equal deleted inserted replaced
-1:000000000000 0:414e01d06fd5
       
     1 ---+ Package =TWiki::Users::Password=
       
     2 
       
     3 Base class of all password handlers. Default behaviour is no passwords,
       
     4 so anyone can be anyone they like.
       
     5 
       
     6 The methods of this class should be overridded by subclasses that want
       
     7 to implement other password handling methods.
       
     8 
       
     9 
       
    10 %TOC%
       
    11 
       
    12 ---++ ClassMethod *new* <tt>($session) -> $object</tt>
       
    13 
       
    14 Constructs a new password handler of this type, referring to $session
       
    15 for any required TWiki services.
       
    16 
       
    17 
       
    18 
       
    19 ---++ ObjectMethod *finish* <tt>()</tt>
       
    20 Break circular references.
       
    21 
       
    22 
       
    23 
       
    24 ---++ ObjectMethod *readOnly* <tt>() -> boolean</tt>
       
    25 
       
    26 returns true if the password database is not currently modifyable
       
    27 also needs to call
       
    28 $this->{session}->enter_context('passwords_modifyable');
       
    29 if you want to be able to use the existing TWikiUserMappingContrib ChangePassword topics
       
    30 
       
    31 
       
    32 
       
    33 ---++ ObjectMethod *fetchPass* <tt>($login) -> $passwordE</tt>
       
    34 
       
    35 Implements TWiki::Password
       
    36 
       
    37 Returns encrypted password if succeeds.
       
    38 Returns 0 if login is invalid.
       
    39 Returns undef otherwise.
       
    40 
       
    41 
       
    42 
       
    43 ---++ ObjectMethod *checkPassword* <tt>($login,$passwordU) -> $boolean</tt>
       
    44 
       
    45 Finds if the password is valid for the given user.
       
    46 
       
    47 Returns 1 on success, undef on failure.
       
    48 
       
    49 
       
    50 
       
    51 ---++ ObjectMethod *removeUser* <tt>($login) -> $boolean</tt>
       
    52 
       
    53 Delete the users entry.
       
    54 
       
    55 
       
    56 
       
    57 ---++ ObjectMethod *setPassword* <tt>($login,$newPassU,$oldPassU) -> $boolean</tt>
       
    58 
       
    59 If the $oldPassU matches matches the user's password, then it will
       
    60 replace it with $newPassU.
       
    61 
       
    62 If $oldPassU is not correct and not 1, will return 0.
       
    63 
       
    64 If $oldPassU is 1, will force the change irrespective of
       
    65 the existing password, adding the user if necessary.
       
    66 
       
    67 Otherwise returns 1 on success, undef on failure.
       
    68 
       
    69 
       
    70 
       
    71 ---++ encrypt( $login, $passwordU, $fresh ) -> $passwordE
       
    72 
       
    73 Will return an encrypted password. Repeated calls
       
    74 to encrypt with the same login/passU will return the same passE.
       
    75 
       
    76 However if the passU is changed, and subsequently changed _back_
       
    77 to the old login/passU pair, then the old passE is no longer valid.
       
    78 
       
    79 If $fresh is true, then a new password not based on any pre-existing
       
    80 salt will be used. Set this if you are generating a completely
       
    81 new password.
       
    82 
       
    83 
       
    84 ---++ ObjectMethod *error* <tt>() -> $string</tt>
       
    85 
       
    86 Return any error raised by the last method call, or undef if the last
       
    87 method call succeeded.
       
    88 
       
    89 
       
    90 
       
    91 ---++ ObjectMethod *isManagingEmails* <tt>() -> $boolean</tt>
       
    92 Determines if this manager can store and retrieve emails. The password
       
    93 manager is used in preference to the user mapping manager for storing
       
    94 emails, on the basis that emails need to be secure, and the password
       
    95 database is the most secure place. If a password manager does not
       
    96 manage emails, then TWiki will fall back to using the user mapping
       
    97 manager (which by default will store emails in user topics)
       
    98 
       
    99 The default ('none') password manager does *not* manage emails.
       
   100 
       
   101 
       
   102 
       
   103 ---++ ObjectMethod *getEmails* <tt>($login) -> @emails</tt>
       
   104 Fetch the email address(es) for the given login. Default
       
   105 behaviour is to return an empty list. Called by Users.pm.
       
   106 Only used if =isManagingEmails= -> =true=.
       
   107 
       
   108 
       
   109 
       
   110 ---++ ObjectMethod *setEmails* <tt>($login,@emails) -> $boolean</tt>
       
   111 Set the email address(es) for the given login name. Returns true if
       
   112 the emails were set successfully.
       
   113 Default behaviour is a nop, which will result in the user mapping manager
       
   114 taking over. Called by Users.pm.
       
   115 Only used if =isManagingEmails= -> =true=.
       
   116 
       
   117 
       
   118 
       
   119 ---++ ObjectMethod *findLoginByEmail* <tt>($email) -> \@users</tt>
       
   120 Returns an array of login names that relate to a email address.
       
   121 Defaut behaviour is a nop, which will result in the user mapping manager
       
   122 being asked for its opinion. If subclass implementations return a value for
       
   123 this, then the user mapping manager will *not* be asked.
       
   124 Only used if =isManagingEmails= -> =true=.
       
   125 
       
   126 Called by Users.pm.
       
   127 
       
   128 
       
   129 
       
   130 ---++ ObjectMethod *canFetchUsers* <tt>() -> boolean</tt>
       
   131 
       
   132 returns true if the fetchUsers method is implemented and can return an iterator of users.
       
   133 returns undef / nothing in this case, as we are unable to generate a list of users
       
   134 
       
   135 
       
   136 
       
   137 ---++ ObjectMethod *fetchUsers* <tt>() -> newTWiki::ListIterator(\@users)</tt>
       
   138 
       
   139 returns a TWikiIterator of loginnames from the password source. If AllowLoginNames is false
       
   140 this is used to remove the need for a TWikiUsers topic.
       
   141 
       
   142