Token.pm

# This Source Code Form is subject to the terms of the Mozilla Public
# License, v. 2.0. If a copy of the MPL was not distributed with this
# file, You can obtain one at http://mozilla.org/MPL/2.0/.
#
# This Source Code Form is "Incompatible With Secondary Licenses", as
# defined by the Mozilla Public License, v. 2.0.

package Bugzilla::Token;

use 5.10.1;
use strict;
use warnings;

use Bugzilla::Constants;
use Bugzilla::Error;
use Bugzilla::Mailer;
use Bugzilla::Util;
use Bugzilla::User;

use Date::Format;
use Date::Parse;
use File::Basename;
use Digest::SHA qw(hmac_sha256_base64);

use parent qw(Exporter);

@Bugzilla::Token::EXPORT = qw(issue_api_token issue_session_token
  check_token_data delete_token
  issue_hash_token check_hash_token);

use constant SEND_NOW => 1;

################################################################################
# Public Functions
################################################################################

# Create a token used for internal API authentication
sub issue_api_token {

  # Generates a random token, adds it to the tokens table if one does not
  # already exist, and returns the token to the caller.
  my $dbh     = Bugzilla->dbh;
  my $user    = Bugzilla->user;
  my ($token) = $dbh->selectrow_array("
        SELECT token FROM tokens
         WHERE userid = ? AND tokentype = 'api_token'
               AND ("
      . $dbh->sql_date_math('issuedate', '+', (MAX_TOKEN_AGE * 24 - 12), 'HOUR')
      . ") > NOW()", undef, $user->id);
  return $token // _create_token($user->id, 'api_token', '');
}

# Creates and sends a token to create a new user account.
# It assumes that the login has the correct format and is not already in use.
sub issue_new_user_account_token {
  my $login_name = shift;
  my $dbh        = Bugzilla->dbh;
  my $template   = Bugzilla->template;
  my $vars       = {};

# Is there already a pending request for this login name? If yes, do not throw
# an error because the user may have lost their email with the token inside.
# But to prevent using this way to mailbomb an email address, make sure
# the last request is old enough before sending a new email (default: 10 minutes).

  my $pending_requests = $dbh->selectrow_array(
    'SELECT COUNT(*)
           FROM tokens
          WHERE tokentype = ?
                AND ' . $dbh->sql_istrcmp('eventdata', '?') . '
                AND issuedate > '
      . $dbh->sql_date_math('NOW()', '-', ACCOUNT_CHANGE_INTERVAL, 'MINUTE'),
    undef, ('account', $login_name)
  );

  ThrowUserError('too_soon_for_new_token', {'type' => 'account'})
    if $pending_requests;

  my ($token, $token_ts) = _create_token(undef, 'account', $login_name);

  $vars->{'email'}         = $login_name . Bugzilla->params->{'emailsuffix'};
  $vars->{'expiration_ts'} = ctime($token_ts + MAX_TOKEN_AGE * 86400);
  $vars->{'token'}         = $token;

  my $message;
  $template->process('account/email/request-new.txt.tmpl', $vars, \$message)
    || ThrowTemplateError($template->error());

  # In 99% of cases, the user getting the confirmation email is the same one
  # who made the request, and so it is reasonable to send the email in the same
  # language used to view the "Create a New Account" page (we cannot use their
  # user prefs as the user has no account yet!).
  MessageToMTA($message, SEND_NOW);
}

sub IssueEmailChangeToken {
  my $new_email = shift;
  my $user      = Bugzilla->user;

  my ($token, $token_ts)
    = _create_token($user->id, 'emailold', $user->login . ":$new_email");
  my $newtoken
    = _create_token($user->id, 'emailnew', $user->login . ":$new_email");

  # Mail the user the token along with instructions for using it.

  my $template = Bugzilla->template_inner($user->setting('lang'));
  my $vars     = {};

  $vars->{'newemailaddress'} = $new_email . Bugzilla->params->{'emailsuffix'};
  $vars->{'expiration_ts'}   = ctime($token_ts + MAX_TOKEN_AGE * 86400);

  # First send an email to the new address. If this one doesn't exist,
  # then the whole process must stop immediately. This means the email must
  # be sent immediately and must not be stored in the queue.
  $vars->{'token'} = $newtoken;

  my $message;
  $template->process('account/email/change-new.txt.tmpl', $vars, \$message)
    || ThrowTemplateError($template->error());

  MessageToMTA($message, SEND_NOW);

  # If we come here, then the new address exists. We now email the current
  # address, but we don't want to stop the process if it no longer exists,
  # to give a chance to the user to confirm the email address change.
  $vars->{'token'} = $token;

  $message = '';
  $template->process('account/email/change-old.txt.tmpl', $vars, \$message)
    || ThrowTemplateError($template->error());

  eval { MessageToMTA($message, SEND_NOW); };

  # Give the user a chance to cancel the process even if he never got
  # the email above. The token is required.
  return $token;
}

# Generates a random token, adds it to the tokens table, and sends it
# to the user with instructions for using it to change their password.
sub IssuePasswordToken {
  my $user = shift;
  my $dbh  = Bugzilla->dbh;

  my $too_soon = $dbh->selectrow_array(
    'SELECT 1 FROM tokens
          WHERE userid = ? AND tokentype = ?
                AND issuedate > '
      . $dbh->sql_date_math('NOW()', '-', ACCOUNT_CHANGE_INTERVAL, 'MINUTE'),
    undef, ($user->id, 'password')
  );

  ThrowUserError('too_soon_for_new_token', {'type' => 'password'}) if $too_soon;

  my $ip_addr = remote_ip();
  my ($token, $token_ts) = _create_token($user->id, 'password', $ip_addr);

  # Mail the user the token along with instructions for using it.
  my $template = Bugzilla->template_inner($user->setting('lang'));
  my $vars     = {};

  $vars->{'token'}         = $token;
  $vars->{'ip_addr'}       = $ip_addr;
  $vars->{'emailaddress'}  = $user->email;
  $vars->{'expiration_ts'} = ctime($token_ts + MAX_TOKEN_AGE * 86400);

  # The user is not logged in (else they wouldn't request a new password).
  # So we have to pass this information to the template.
  $vars->{'timezone'} = $user->timezone;

  my $message = "";
  $template->process("account/password/forgotten-password.txt.tmpl",
    $vars, \$message)
    || ThrowTemplateError($template->error());

  MessageToMTA($message);
}

sub issue_session_token {

  # Generates a random token, adds it to the tokens table, and returns
  # the token to the caller.

  my $data = shift;
  return _create_token(Bugzilla->user->id, 'session', $data);
}

sub issue_hash_token {
  my ($data, $time) = @_;
  $data ||= [];
  $time ||= time();

  # For the user ID, use the actual ID if the user is logged in.
  # Otherwise, use the remote IP, in case this is for something
  # such as creating an account or logging in.
  my $user_id = Bugzilla->user->id || remote_ip();

  # The concatenated string is of the form
  # token creation time + user ID (either ID or remote IP) + data
  my @args = ($time, $user_id, @$data);

  my $token = join('*', @args);

  # Wide characters cause Digest::SHA to die.
  if (Bugzilla->params->{'utf8'}) {
    utf8::encode($token) if utf8::is_utf8($token);
  }
  $token
    = hmac_sha256_base64($token, Bugzilla->localconfig->{'site_wide_secret'});
  $token =~ s/\+/-/g;
  $token =~ s/\//_/g;

  # Prepend the token creation time, unencrypted, so that the token
  # lifetime can be validated.
  return $time . '-' . $token;
}

sub check_hash_token {
  my ($token, $data) = @_;
  $data ||= [];
  my ($time, $expected_token);

  if ($token) {
    ($time, undef) = split(/-/, $token);

    # Regenerate the token based on the information we have.
    $expected_token = issue_hash_token($data, $time);
  }

  if (!$token
    || $expected_token ne $token
    || time() - $time > MAX_TOKEN_AGE * 86400)
  {
    my $template = Bugzilla->template;
    my $vars     = {};
    $vars->{'script_name'} = basename($0);
    $vars->{'token'}       = issue_hash_token($data);
    $vars->{'reason'}
      = (!$token) ? 'missing_token'
      : ($expected_token ne $token) ? 'invalid_token'
      :                               'expired_token';
    print Bugzilla->cgi->header();
    $template->process('global/confirm-action.html.tmpl', $vars)
      || ThrowTemplateError($template->error());
    exit;
  }

  # If we come here, then the token is valid and not too old.
  return 1;
}

sub CleanTokenTable {
  my $dbh = Bugzilla->dbh;
  $dbh->do(
    'DELETE FROM tokens
              WHERE '
      . $dbh->sql_to_days('NOW()') . ' - '
      . $dbh->sql_to_days('issuedate')
      . ' >= ?', undef, MAX_TOKEN_AGE
  );
}

sub GenerateUniqueToken {

  # Generates a unique random token.  Uses generate_random_password
  # for the tokens themselves and checks uniqueness by searching for
  # the token in the "tokens" table.  Gives up if it can't come up
  # with a token after about one hundred tries.
  my ($table, $column) = @_;

  my $token;
  my $duplicate = 1;
  my $tries     = 0;
  $table  ||= "tokens";
  $column ||= "token";

  my $dbh = Bugzilla->dbh;
  my $sth = $dbh->prepare("SELECT 1 FROM $table WHERE $column = ?");

  while ($duplicate) {
    ++$tries;
    if ($tries > 100) {
      ThrowCodeError("token_generation_error");
    }
    $token = generate_random_password();
    $sth->execute($token);
    $duplicate = $sth->fetchrow_array;
  }
  return $token;
}

# Cancels a previously issued token and notifies the user.
# This should only happen when the user accidentally makes a token request
# or when a malicious hacker makes a token request on behalf of a user.
sub Cancel {
  my ($token, $cancelaction, $vars) = @_;
  my $dbh = Bugzilla->dbh;
  $vars ||= {};

  # Get information about the token being canceled.
  trick_taint($token);
  my ($db_token, $issuedate, $tokentype, $eventdata, $userid)
    = $dbh->selectrow_array(
    'SELECT token, '
      . $dbh->sql_date_format('issuedate') . ',
                                      tokentype, eventdata, userid
                                 FROM tokens
                                WHERE token = ?', undef, $token
    );

  # Some DBs such as MySQL are case-insensitive by default so we do
  # a quick comparison to make sure the tokens are indeed the same.
  (defined $db_token && $db_token eq $token)
    || ThrowCodeError("cancel_token_does_not_exist");

  # If we are canceling the creation of a new user account, then there
  # is no entry in the 'profiles' table.
  my $user = new Bugzilla::User($userid);

  $vars->{'emailaddress'}  = $userid ? $user->email : $eventdata;
  $vars->{'remoteaddress'} = remote_ip();
  $vars->{'token'}         = $token;
  $vars->{'tokentype'}     = $tokentype;
  $vars->{'issuedate'}     = $issuedate;

  # The user is probably not logged in.
  # So we have to pass this information to the template.
  $vars->{'timezone'}     = $user->timezone;
  $vars->{'eventdata'}    = $eventdata;
  $vars->{'cancelaction'} = $cancelaction;

  # Notify the user via email about the cancellation.
  my $template = Bugzilla->template_inner($user->setting('lang'));

  my $message;
  $template->process("account/cancel-token.txt.tmpl", $vars, \$message)
    || ThrowTemplateError($template->error());

  MessageToMTA($message);

  # Delete the token from the database.
  delete_token($token);
}

sub DeletePasswordTokens {
  my ($userid, $reason) = @_;
  my $dbh = Bugzilla->dbh;

  detaint_natural($userid);
  my $tokens = $dbh->selectcol_arrayref(
    'SELECT token FROM tokens
                                           WHERE userid = ? AND tokentype = ?',
    undef, ($userid, 'password')
  );

  foreach my $token (@$tokens) {
    Bugzilla::Token::Cancel($token, $reason);
  }
}

# Returns an email change token if the user has one.
sub HasEmailChangeToken {
  my $userid = shift;
  my $dbh    = Bugzilla->dbh;

  my $token = $dbh->selectrow_array(
    'SELECT token FROM tokens
                                       WHERE userid = ?
                                       AND (tokentype = ? OR tokentype = ?) '
      . $dbh->sql_limit(1), undef, ($userid, 'emailnew', 'emailold')
  );
  return $token;
}

# Returns the userid, issuedate and eventdata for the specified token
sub GetTokenData {
  my ($token) = @_;
  my $dbh = Bugzilla->dbh;

  return unless defined $token;
  $token = clean_text($token);
  trick_taint($token);

  my @token_data = $dbh->selectrow_array(
        "SELECT token, userid, "
      . $dbh->sql_date_format('issuedate')
      . ", eventdata, tokentype
         FROM   tokens
         WHERE  token = ?", undef, $token
  );

  # Some DBs such as MySQL are case-insensitive by default so we do
  # a quick comparison to make sure the tokens are indeed the same.
  my $db_token = shift @token_data;
  return undef if (!defined $db_token || $db_token ne $token);

  return @token_data;
}

# Deletes specified token
sub delete_token {
  my ($token) = @_;
  my $dbh = Bugzilla->dbh;

  return unless defined $token;
  trick_taint($token);

  $dbh->do("DELETE FROM tokens WHERE token = ?", undef, $token);
}

# Given a token, makes sure it comes from the currently logged in user
# and match the expected event. Returns 1 on success, else displays a warning.
sub check_token_data {
  my ($token, $expected_action, $alternate_script) = @_;
  my $user     = Bugzilla->user;
  my $template = Bugzilla->template;
  my $cgi      = Bugzilla->cgi;

  my ($creator_id, $date, $token_action) = GetTokenData($token);
  unless ($creator_id
    && $creator_id == $user->id
    && $token_action eq $expected_action)
  {
    # Something is going wrong. Ask confirmation before processing.
    # It is possible that someone tried to trick an administrator.
    # In this case, we want to know their name!
    require Bugzilla::User;

    my $vars = {};
    $vars->{'abuser'}           = Bugzilla::User->new($creator_id)->identity;
    $vars->{'token_action'}     = $token_action;
    $vars->{'expected_action'}  = $expected_action;
    $vars->{'script_name'}      = basename($0);
    $vars->{'alternate_script'} = $alternate_script || basename($0);

    # Now is a good time to remove old tokens from the DB.
    CleanTokenTable();

    # If no token was found, create a valid token for the given action.
    unless ($creator_id) {
      $token = issue_session_token($expected_action);
      $cgi->param('token', $token);
    }

    print $cgi->header();

    $template->process('admin/confirm-action.html.tmpl', $vars)
      || ThrowTemplateError($template->error());
    exit;
  }
  return 1;
}

################################################################################
# Internal Functions
################################################################################

# Generates a unique token and inserts it into the database
# Returns the token and the token timestamp
sub _create_token {
  my ($userid, $tokentype, $eventdata) = @_;
  my $dbh = Bugzilla->dbh;

  detaint_natural($userid) if defined $userid;
  trick_taint($tokentype);
  trick_taint($eventdata);

  my $is_shadow = Bugzilla->is_shadow_db;
  $dbh = Bugzilla->switch_to_main_db() if $is_shadow;

  $dbh->bz_start_transaction();

  my $token = GenerateUniqueToken();

  $dbh->do(
    "INSERT INTO tokens (userid, issuedate, token, tokentype, eventdata)
        VALUES (?, NOW(), ?, ?, ?)", undef,
    ($userid, $token, $tokentype, $eventdata)
  );

  $dbh->bz_commit_transaction();

  if (wantarray) {
    my (undef, $token_ts, undef) = GetTokenData($token);
    $token_ts = str2time($token_ts);
    Bugzilla->switch_to_shadow_db() if $is_shadow;
    return ($token, $token_ts);
  }
  else {
    Bugzilla->switch_to_shadow_db() if $is_shadow;
    return $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, $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);

=head1 SUBROUTINES

=over

=item C<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.

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

=item C<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.

=item C<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.

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

=item C<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.

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

=back

=head2 Security related routines

The following routines have been written to be used together as described below,
although 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

=head1 B<Methods in need of POD>

=over

=item check_hash_token

=item issue_hash_token

=back