table = $tableName; $this->login = $login; } /** * Generate a new TOTP secret and QR code for a user * @return array{0: string, 1: string} Array containing [TOTP secret, base64-encoded QR code] */ public function generate(string $username): array { $totp = TOTP::create(); $totp->setLabel($username); $totp->setIssuer('Postfix Admin'); if (Config::has('logo_url') && is_string(Config::read('logo_url'))) { $totp->setParameter('image', (string)Config::read('logo_url')); } $QR_content = $totp->getProvisioningUri(); $pTOTP_secret = $totp->getSecret(); unset($totp); // endroid/qr-code // - v4.6 supports PHP 7.4 || 8.0 // - v5 supports PHP ^8.1 and introduces enums ... // Hopefully this code will allow PHP 8.2 to use the newer library (and suppress deprecation warnings) if (class_exists('\Endroid\QrCode\ErrorCorrectionLevel\ErrorCorrectionLevelHigh')) { /** * @psalm-suppress UndefinedClass */ $level = new \Endroid\QrCode\ErrorCorrectionLevel\ErrorCorrectionLevelHigh(); } elseif (class_exists('\Endroid\QrCode\ErrorCorrectionLevel')) { /** * @psalm-suppress UndefinedClass */ $level = \Endroid\QrCode\ErrorCorrectionLevel::High; } else { throw new \InvalidArgumentException("Endroid QR Code library issue - can't figure out ErrorCorrectionLevel."); } if (class_exists('\Endroid\QrCode\RoundBlockSizeMode\RoundBlockSizeModeMargin')) { /** * @psalm-suppress UndefinedClass */ $margin = new \Endroid\QrCode\RoundBlockSizeMode\RoundBlockSizeModeMargin(); } elseif (class_exists('\Endroid\QrCode\RoundBlockSizeMode')) { /** * @psalm-suppress UndefinedClass */ $margin = \Endroid\QrCode\RoundBlockSizeMode::Margin; } else { throw new \InvalidArgumentException("Endroid QR Code library issue - can't figure out Margin."); } /** * @psalm-suppress TooManyArguments */ $encoding = new Encoding('UTF-8'); $QRresult = Builder::create() ->writer(new PngWriter()) ->writerOptions([]) ->data($QR_content) ->encoding($encoding) ->errorCorrectionLevel($level) ->size(300) ->margin(10) ->roundBlockSizeMode($margin) ->validateResult(false) ->build(); $qr_code = base64_encode($QRresult->getString()); return [$pTOTP_secret, $qr_code]; } /** * Check if a user has TOTP enabled * * @param string $username * * @return bool True if the user has TOTP enabled, false otherwise */ public function usesTOTP(string $username): bool { // Check if TOTP is globally enabled if (!(Config::read('totp') == 'YES')) { return false; } $table_name = table_by_key($this->table); $sql = "SELECT totp_secret FROM $table_name WHERE username = :username AND active = :active"; $active = db_get_boolean(true); $values = [ 'username' => $username, 'active' => $active, ]; // Execute the query and check if the user has a TOTP secret $result = db_query_one($sql, $values); return (is_array($result) && isset($result['totp_secret']) && !empty($result['totp_secret'])); } /** * Authenticate an interface that cannot complete a TOTP challenge. */ public function passwordOnlyLogin(string $username, string $password): bool { if (!$this->login->login($username, $password)) { return false; } return !$this->usesTOTP($username); } /** * Check if a TOTP code is valid for a user */ public function checkUserTOTP(string $username, string $code): bool { $table_name = table_by_key($this->table); $sql = "SELECT totp_secret FROM $table_name WHERE username = :username AND active = :active"; $active = db_get_boolean(true); $values = [ 'username' => $username, 'active' => $active, ]; $result = db_query_one($sql, $values); if (!is_array($result) || !isset($result['totp_secret'])) { return false; } return $this->checkTOTP($result['totp_secret'], $code); } /** * Check if a TOTP code is valid for a given secret * * @param string $secret TOTP secret * @param string $code TOTP code to verify * * @return bool True if the code is valid, false otherwise */ public function checkTOTP(string $secret, string $code): bool { $totp = TOTP::create($secret); return $totp->now() == $code; } public function removeTotpFromUser(string $username): void { $table_name = table_by_key($this->table); $sql = "UPDATE $table_name SET totp_secret = NULL WHERE username = :username"; db_execute($sql, ['username' => $username]); } /** * @param string $username * @param string $password * * @return string TOTP_secret or null if no secret set? * @throws \Exception if invalid user, or db update fails. */ public function getTOTP_secret(string $username, string $password): ?string { if (!$this->login->login($username, $password)) { throw new \Exception(Config::Lang('pPassword_password_current_text_error')); } $table_name = table_by_key($this->table); $sql = "SELECT totp_secret FROM $table_name WHERE username = :username AND active = :active"; $active = db_get_boolean(true); $values = [ 'username' => $username, 'active' => $active, ]; $result = db_query_one($sql, $values); if (is_array($result) && isset($result['totp_secret'])) { return $result['totp_secret']; } return null; } /** * Change the TOTP secret for a user after verifying their password * * @param string $username Username to change the TOTP secret for * @param string|null $TOTP_secret New TOTP secret or null to disable TOTP * @param string $password User's password for verification * * @return bool True on success * @throws \Exception If the password is incorrect, database update fails, or post-change script fails */ public function changeTOTP_secret(string $username, ?string $TOTP_secret, string $password): bool { list(/*NULL*/, $domain) = explode('@', $username); /* should we need to do a login check here, if it's an admin removing the TOTP requirement */ if (!$this->login->login($username, $password)) { throw new \Exception(Config::Lang('pPassword_password_current_text_error')); } $set = [ 'totp_secret' => $TOTP_secret, ]; $result = db_update($this->table, 'username', $username, $set); if ($result != 1) { db_log($domain, 'edit_password', "FAILURE: " . $username); throw new \Exception(Config::lang('pEdit_mailbox_result_error')); } // Check if a post-change script is configured $cmd_pw = Config::read('mailbox_post_TOTP_change_secret_script'); if (empty($cmd_pw)) { return true; } $warnmsg_pw = Config::Lang('mailbox_post_TOTP_change_failed'); // Execute the post-change script // Use proc_open call to avoid safe_mode problems and to prevent showing plain password in process table $spec = array( 0 => array("pipe", "r"), // stdin 1 => array("pipe", "w"), // stdout ); $cmdarg1 = escapeshellarg($username); $cmdarg2 = escapeshellarg($domain); $command = "$cmd_pw $cmdarg1 $cmdarg2 2>&1"; $proc = proc_open($command, $spec, $pipes); if (!$proc) { throw new \Exception("can't proc_open $cmd_pw"); } // Write secret through pipe to command stdin if ($TOTP_secret !== null) { fwrite($pipes[0], $TOTP_secret . "\0", 1 + strlen($TOTP_secret)); } else { fwrite($pipes[0], "\0", 1); } $output = stream_get_contents($pipes[1]); fclose($pipes[0]); fclose($pipes[1]); $retval = proc_close($proc); if (0 != $retval) { error_log("Running $command yielded return value=$retval, output was: " . json_encode($output)); throw new \Exception($warnmsg_pw); } return true; } /** * Add a TOTP exception for a specific IP address * * This allows a user to bypass TOTP verification when connecting from the specified IP address. * Different user roles have different permissions: * - Regular users can only add exceptions for themselves * - Admins can add exceptions for users in domains they manage * - Global admins can add exceptions for any user * * @param string $username Username of the authenticated user adding the exception * @param string $password Password of the authenticated user * @param string $ip_address IP address to exempt from TOTP verification * @param string $exception_username Username or domain to apply the exception to * @param string $exception_description Description of why this exception exists * * @return bool True on success * @throws \Exception If authentication fails, validation fails, or database update fails */ public function addException(string $username, string $password, string $ip_address, string $exception_username, string $exception_description): bool { $error = 0; list($local_part, $domain) = explode('@', $username); if (!$this->login->login($username, $password)) { throw new \Exception(Config::Lang('pPassword_password_current_text_error')); } if (authentication_has_role('admin')) { $admin = 1; // Get domains the admin has access to $domains = list_domains_for_admin($username); if (strpos($exception_username, '@')) { list($local_part, $Exception_domain) = explode('@', $exception_username); } else { // assume domain $Exception_domain = $exception_username; } // Ensure admin has access to the domain of the exception if ($exception_username != $username && !in_array($Exception_domain, $domains)) { throw new \Exception(Config::Lang('pException_user_entire_domain_error')); } } elseif (authentication_has_role('global-admin')) { $admin = 2; // Global admins can do anything } else { // Regular users can only add exceptions for themselves $exception_username = $username; $admin = 0; } // Validate inputs if (empty($ip_address)) { $error++; flash_error(Config::Lang('pException_ip_empty_error')); } if (!filter_var($ip_address, FILTER_VALIDATE_IP)) { $error++; flash_error(Config::Lang('pException_ip_error')); } if (empty($exception_description)) { $error++; flash_error(Config::Lang('pException_desc_empty_error')); } // Regular users can only add exceptions within a domain if ($admin === 0 && strpos($exception_username, '@') == false) { $error++; flash_error(Config::Lang('pException_user_entire_domain_error')); } // Only global admins can add an exception for any one if (!($admin === 2) && $exception_username == null) { $error++; flash_error(Config::Lang('pException_user_global_error')); } // Prepare values for database $values = [ 'ip' => $ip_address, 'username' => $exception_username, 'description' => $exception_description ]; // Only proceed if there are no validation errors if ($error == 0) { $totp_exception_address = table_by_key('totp_exception_address'); // As PostgreSQL lacks REPLACE, first delete any existing exceptions with the same IP and username $exists = db_query_all( "SELECT id FROM $totp_exception_address WHERE ip = :ip AND username = :username", ['ip' => $ip_address, 'username' => $exception_username] ); if (isset($exists[0])) { foreach ($exists as $x) { db_delete('totp_exception_address', 'id', $x['id']); } } // Insert the new exception $result = db_insert('totp_exception_address', $values, []); } // Check if the insert was successful if (!isset($result) || $result != 1) { db_log($domain, 'add_totp_exception', "FAILURE: " . $username); throw new \Exception(Config::lang('pEdit_totp_exception_result_error')); } // Run post-exception-add script if configured $cmd_pw = Config::read('mailbox_post_totp_exception_add_script'); if (empty($cmd_pw)) { return true; } $warnmsg_pw = Config::Lang('mailbox_post_totp_exception_add_failed'); // Use proc_open call to avoid safe_mode problems and to prevent showing sensitive data in process table $spec = array( 0 => array("pipe", "r"), // stdin 1 => array("pipe", "w"), // stdout ); $cmdarg1 = escapeshellarg($username); $cmdarg2 = escapeshellarg($ip_address); $command = "$cmd_pw $cmdarg1 $cmdarg2 2>&1"; $proc = proc_open($command, $spec, $pipes); if (!$proc) { throw new \Exception("can't proc_open $cmd_pw"); } fclose($pipes[0]); fclose($pipes[1]); $retval = proc_close($proc); if (0 != $retval) { error_log("Running $command yielded return value=$retval, output was: " . json_encode($retval)); throw new \Exception($warnmsg_pw); } return true; } /** * Delete a TOTP exception * * Different user roles have different permissions: * - Regular users can only delete their own exceptions * - Admins can delete exceptions for users in domains they manage, or delete a domain wide on for their domain. * - Global admins can delete any exception * * @param string $username Username of the authenticated user deleting the exception * @param int $id ID of the exception to delete * * @return bool True on success * @throws \InvalidArgumentException If the exception doesn't exist * @throws \Exception If the user doesn't have permission or the deletion fails */ public function deleteException(string $username, int $id): bool { // Get the exception details $exception = $this->getException($id); if (!is_array($exception)) { throw new \InvalidArgumentException("Invalid exception - does id: $id exist?"); } // Extract domain from exception username if (strpos($exception['username'], '@')) { list($Exception_local_part, $Exception_domain) = explode('@', $exception['username']); } else { $Exception_domain = $exception['username']; } // Check permissions based on user role if (authentication_has_role('global-admin')) { // Global admins can delete any exception } elseif (authentication_has_role('admin')) { // Admins can delete exceptions for users in domains they manage $domains = list_domains_for_admin($username); // If the exception is not for the current user, ensure it's for a domain they manage if ($exception['username'] != $username && !in_array($Exception_domain, $domains)) { throw new \Exception(Config::Lang('pException_user_entire_domain_error')); } } else { // Regular users can only delete their own exceptions if ($exception['username'] != $username) { throw new \Exception(Config::lang('pEdit_totp_exception_result_error')); } } // Delete the exception from the database $totp_exception_address = table_by_key('totp_exception_address'); $result = db_execute("DELETE FROM $totp_exception_address WHERE id = :id", ['id' => $id]); if ($result != 1) { db_log($Exception_domain, 'pViewlog_action_delete_totp_exception', "FAILURE: " . $username); throw new \Exception(Config::lang('pEdit_totp_exception_result_error')); } // Run post-exception-delete script if configured $cmd_pw = Config::read('mailbox_post_totp_exception_delete_script'); if (empty($cmd_pw)) { return true; } $warnmsg_pw = Config::Lang('mailbox_post_totp_exception_delete_failed'); // Use proc_open call to avoid safe_mode problems and to prevent showing sensitive data in process table $spec = [ 0 => ["pipe", "r"], // stdin 1 => ["pipe", "w"], // stdout ]; $cmdarg1 = escapeshellarg($username); $cmdarg2 = escapeshellarg($exception['ip']); $command = "$cmd_pw $cmdarg1 $cmdarg2 2>&1"; $proc = proc_open($command, $spec, $pipes); if (!$proc) { throw new \Exception("can't proc_open $cmd_pw"); } $output = stream_get_contents($pipes[1]); fclose($pipes[0]); fclose($pipes[1]); $retval = proc_close($proc); if (0 != $retval) { error_log("Running $command yielded return value=$retval, output was: " . json_encode($output)); throw new \Exception($warnmsg_pw); } return true; } /** * Get all TOTP exceptions in the system * * @return array List of all TOTP exceptions */ public function getAllExceptions(): array { $totp_exception_address = table_by_key('totp_exception_address'); return db_query_all("SELECT * FROM $totp_exception_address"); } /** * Get all TOTP exceptions that apply to a specific username * * This includes exceptions for: * - The specific username * - The domain part of the username * - Global exceptions (where username is NULL) * * @param string $username Username to get exceptions for * * @return array List of exceptions that apply to the username */ public function getExceptionsFor(string $username): array { list($local_part, $domain) = explode('@', $username); $totp_exception_address = table_by_key('totp_exception_address'); return db_query_all( "SELECT * FROM $totp_exception_address WHERE username = :username OR username = :domain OR username IS NULL", ['username' => $username, 'domain' => $domain] ); } /** * Get a specific TOTP exception by ID * * @param int $id ID of the exception to retrieve * * @return array|null The exception data or null if not found */ public function getException(int $id): ?array { $totp_exception_address = table_by_key('totp_exception_address'); return db_query_one("SELECT * FROM $totp_exception_address WHERE id = :id", ['id' => $id]); } }