5.7.73. Bugzilla::Token

5.7.73.1. NAME

Bugzilla::Token - Provides different routines to manage tokens.

5.7.73.2. SYNOPSIS

use Bugzilla::Token;

Bugzilla::Token::issue_new_user_account_token($login_name);
Bugzilla::Token::IssueEmailChangeToken($user, $new_email);
Bugzilla::Token::IssuePasswordToken($user);
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, $type) = Bugzilla::Token::GetTokenData($token);

5.7.73.3. SUBROUTINES

issue_api_token($login_name)

Description: Creates a token that can be used for API calls on the web page.

Params:      None.

Returns:     The token.

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 their 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.

sub IssueEmailChangeToken($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. These tokens remain valid for the next MAX_TOKEN_AGE days.

Params:      $new_email - The new email address of the user.

Returns:     The token to cancel the request.

IssuePasswordToken($user)

Description: Sends a token per email to the given user. This token
             can be used to change the password (e.g. in case the user
             cannot remember their password and wishes to enter a new one).

Params:      $user - User object 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.

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.

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.

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 them
             that this token has been invalidated (e.g. because an hacker
             tried 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.

DeletePasswordTokens($user_id, $reason)

Description: Cancels all password tokens for the given user. Emails are sent
             to the user to inform them about this action.

Params:      $user_id: The user ID of the user account whose password tokens
                       are canceled.
             $reason:  The reason why these tokens are canceled.

Returns:     Nothing.

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.

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,
             the (event)data stored with that token, and its type.

5.7.73.4. Methods in need of POD

check_hash_token

issue_hash_token


This documentation undoubtedly has bugs; if you find some, please file them here.