summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorlpsolit%gmail.com <>2006-11-21 03:59:12 +0100
committerlpsolit%gmail.com <>2006-11-21 03:59:12 +0100
commitca5d15eba7b9f6ad3e0dd6be01ade0f5138fe889 (patch)
treeee8e01859a3166945636027f75d2f2e4c8b7c16c
parentd4bcf5272dffa704cfe97774088e9ecbafa03b47 (diff)
downloadbugzilla-ca5d15eba7b9f6ad3e0dd6be01ade0f5138fe889.tar.gz
bugzilla-ca5d15eba7b9f6ad3e0dd6be01ade0f5138fe889.tar.xz
Bug 316797: Token.pm needs POD - Patch by Frédéric Buclin <LpSolit@gmail.com> r/a=myk
-rw-r--r--Bugzilla/Token.pm181
1 files changed, 181 insertions, 0 deletions
diff --git a/Bugzilla/Token.pm b/Bugzilla/Token.pm
index 051514b01..8d3088df0 100644
--- a/Bugzilla/Token.pm
+++ b/Bugzilla/Token.pm
@@ -383,3 +383,184 @@ sub _create_token {
}
1;
+
+__END__
+
+=head1 NAME
+
+Bugzilla::Token - Provides different routines to manage tokens.
+
+=head1 SYNOPSIS
+
+ use Bugzilla::Token;
+
+ Bugzilla::Token::issue_new_user_account_token($login_name);
+ Bugzilla::Token::IssueEmailChangeToken($user_id, $old_email, $new_email);
+ Bugzilla::Token::IssuePasswordToken($login_name);
+ Bugzilla::Token::DeletePasswordTokens($user_id, $reason);
+ Bugzilla::Token::Cancel($token, $cancelaction, $vars);
+
+ Bugzilla::Token::CleanTokenTable();
+
+ my $token = issue_session_token($event);
+ check_token_data($token, $event)
+ delete_token($token);
+
+ my $token = Bugzilla::Token::GenerateUniqueToken($table, $column);
+ my $token = Bugzilla::Token::HasEmailChangeToken($user_id);
+ my ($token, $date, $data) = Bugzilla::Token::GetTokenData($token);
+
+=head1 SUBROUTINES
+
+=over
+
+=item C<issue_new_user_account_token($login_name)>
+
+ Description: Creates and sends a token per email to the email address
+ requesting a new user account. It doesn't check whether
+ the user account already exists. The user will have to
+ use this token to confirm the creation of his user account.
+
+ Params: $login_name - The new login name requested by the user.
+
+ Returns: Nothing. It throws an error if the same user made the same
+ request in the last few minutes.
+
+=item C<sub IssueEmailChangeToken($user_id, $old_email, $new_email)>
+
+ Description: Sends two distinct tokens per email to the old and new email
+ addresses to confirm the email address change for the given
+ user ID. These tokens remain valid for the next MAX_TOKEN_AGE days.
+
+ Params: $user_id - The user ID of the user account requesting a new
+ email address.
+ $old_email - The current (old) email address of the user.
+ $new_email - The new email address of the user.
+
+ Returns: Nothing.
+
+=item C<IssuePasswordToken($login_name)>
+
+ Description: Sends a token per email to the given login name. This token
+ can be used to change the password (e.g. in case the user
+ cannot remember his password and wishes to enter a new one).
+
+ Params: $login_name - The login name of the user requesting a new password.
+
+ Returns: Nothing. It throws an error if the same user made the same
+ request in the last few minutes.
+
+=item C<CleanTokenTable()>
+
+ Description: Removes all tokens older than MAX_TOKEN_AGE days from the DB.
+ This means that these tokens will now be considered as invalid.
+
+ Params: None.
+
+ Returns: Nothing.
+
+=item C<GenerateUniqueToken($table, $column)>
+
+ Description: Generates and returns a unique token. This token is unique
+ in the $column of the $table. This token is NOT stored in the DB.
+
+ Params: $table (optional): The table to look at (default: tokens).
+ $column (optional): The column to look at for uniqueness (default: token).
+
+ Returns: A token which is unique in $column.
+
+=item C<Cancel($token, $cancelaction, $vars)>
+
+ Description: Invalidates an existing token, generally when the token is used
+ for an action which is not the one expected. An email is sent
+ to the user who originally requested this token to inform him
+ that this token has been invalidated (e.g. because an hacker
+ tries to use this token for some malicious action).
+
+ Params: $token: The token to invalidate.
+ $cancelaction: The reason why this token is invalidated.
+ $vars: Some additional information about this action.
+
+ Returns: Nothing.
+
+=item C<DeletePasswordTokens($user_id, $reason)>
+
+ Description: Cancels all password tokens for the given user. Emails are sent
+ to this user to inform him about this action.
+
+ Params: $user_id: The user ID of the user account whose password tokens
+ are cancelled.
+ $reason: The reason why these tokens are cancelled.
+
+ Returns: Nothing.
+
+=item C<HasEmailChangeToken($user_id)>
+
+ Description: Returns any existing token currently used for an email change
+ for the given user.
+
+ Params: $user_id - A user ID.
+
+ Returns: A token if it exists, else undef.
+
+=item C<GetTokenData($token)>
+
+ Description: Returns all stored data for the given token.
+
+ Params: $token - A valid token.
+
+ Returns: The user ID, the date and time when the token was created and
+ the (event)data stored with that token.
+
+=back
+
+=head2 Security related routines
+
+The following routines have been written to be used together as described below,
+despite they can be used separately.
+
+=over
+
+=item C<issue_session_token($event)>
+
+ Description: Creates and returns a token used internally.
+
+ Params: $event - The event which needs to be stored in the DB for future
+ reference/checks.
+
+ Returns: A unique token.
+
+=item C<check_token_data($token, $event)>
+
+ Description: Makes sure the $token has been created by the currently logged in
+ user and to be used for the given $event. If this token is used for
+ an unexpected action (i.e. $event doesn't match the information stored
+ with the token), a warning is displayed asking whether the user really
+ wants to continue. On success, it returns 1.
+ This is the routine to use for security checks, combined with
+ issue_session_token() and delete_token() as follows:
+
+ 1. First, create a token for some coming action.
+ my $token = issue_session_token($action);
+ 2. Some time later, it's time to make sure that the expected action
+ is going to be executed, and by the expected user.
+ check_token_data($token, $action);
+ 3. The check has been done and we no longer need this token.
+ delete_token($token);
+
+ Params: $token - The token used for security checks.
+ $event - The expected event to be run.
+
+ Returns: 1 on success, else a warning is thrown.
+
+=item C<delete_token($token)>
+
+ Description: Deletes the specified token. No notification is sent.
+
+ Params: $token - The token to delete.
+
+ Returns: Nothing.
+
+=back
+
+=cut