spaceshiptrooper/sarah

Sarah 是一个基于 PHP 开发的双因素认证库。

维护者

详细信息

github.com/spaceshiptrooper/Sarah

源代码

问题

安装: 86

依赖项: 0

建议者: 0

安全: 0

星星: 0

关注者: 1

分支: 0

开放问题: 0

v0.1 2018-02-08 06:24 UTC

Requires

LGPL-2.1-only f17adc1d424fb45ee6914abc9db8b0a521a34d6e

  • spaceshiptrooper <webmaster.woop@phpthelegacyway.com>

This package is not auto-updated.

Last update: 2024-09-19 05:13:29 UTC

README

Sarah 是一个基于 PHP 开发的双因素认证库。

要求

  • PHP 5.4+
  • MySQL 数据库
  • composer

先决条件

安装 Composer

注意

在我们开始使用 Sarah 之前，我们必须安装 composer 来获取 Sarah 的依赖项。 Sarah 依赖于 PHPMailer 库来发送电子邮件。如果您已经有了最新版本的 PHPMailer，您可以跳过这部分。但是，如果您还没有这样做，您必须将 PHPMailer 移动到 vendor 目录。 Sarah 在 vendor 目录中查找 PHPMailer。

Linux & Mac

  1. 我们首先需要的是 composer，所以我们将从该网站下载它。 https://composer.php.ac.cn/download/

  2. 下一步是使用该页面上的代码。如果您不熟悉 Linux 和 Mac，您必须打开终端。在终端中，按顺序输入以下行；逐行。

  3. 我们将使用以下代码从官方 composer 网站复制 composer-setup.php 文件。

php -r "copy('https://composer.php.ac.cn/installer', 'composer-setup.php');"
  1. 我们使用以下代码检查是否有错误从 composer 网站下载 composer-setup.php 文件。
php -r "if (hash_file('SHA384', 'composer-setup.php') === '544e09ee996cdf60ece3804abc52599c22b1f40f4323403c44d44fdfdd586475ca9813a858088ffbc1f233e9b180f061') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
  1. 我们设置我们的 composer-setup.php 文件。这将下载一个名为 composer.phar 的新文件，这是我们使用以下代码运行实际 composer 命令所需的文件。
php composer-setup.php
  1. 然后我们删除 composer-setup.php 文件，因为我们不再需要它了。
php -r "unlink('composer-setup.php');"
  1. 在这里，我们将 composer.phar 文件移动到全局使用。这样我们就可以执行如 composer require composer.json 这样的命令，而不是 /home/user/Downloads/composer.phar require composer.json。
sudo mv composer.phar /usr/local/bin/composer
Windows

在 Windows 上，Composer 实际上要简单一些。您只需要下载位于 https://composer.php.ac.cn/doc/00-intro.md#installation-windows 的 Composer-Setup.exe 文件。一旦打开该应用程序，您就可以开始安装过程。您必须找到您的 php.exe 文件，然后 composer 将开始安装。如果您想像 Linux 和 Mac 那样使用全局设置，您必须将 composer.phar 文件的位置添加到您的 PATH 变量中。

要这样做，请按照以下步骤操作。

  1. 打开文件资源管理器。
  2. 右键单击“此电脑”。
  3. 从上下文菜单中选择“属性”。
  4. 这将打开一个新窗口，其中包含设置，基本上列出 Windows 的版本及其规格等。
  5. 在左侧侧栏中，单击“高级系统设置”。这将打开另一个新窗口。
  6. 从该窗口，单击“高级”选项卡。
  7. 在“高级”选项卡中，查找“编辑”按钮。
  8. 单击它，它将允许您编辑路径。
  9. 将 composer.phar 文件的确切路径添加到文本框中，并以 ; 结尾。这个分号将每个单独的值作为实际路径分开，所以要小心使用分号。更多的路径意味着更多的分号。
导入数据库

Sarah 使用 PDO 作为她的数据库 API。假设您理解这意味着什么，我们使用的是 MySQL 服务器。所以，如果您有权访问您的 MySQL 数据库，创建一个数据库并将以下代码复制并粘贴到您的新数据库中。一个 GUI 如 phpMyAdmin 就足够了。

CREATE TABLE `two_factor_authentication` (
  `id` int(11) NOT NULL,
  `user_id` int(11) DEFAULT NULL,
  `email` varchar(255) DEFAULT NULL,
  `authkey` text DEFAULT NULL,
  `hash` text DEFAULT NULL,
  `ip` varchar(100) DEFAULT NULL,
  `agent` varchar(255) DEFAULT NULL,
  `timestamp` int(11) DEFAULT NULL,
  `status` int(1) DEFAULT NULL
) ENGINE=InnoDB DEFAULT CHARSET=latin1;

ALTER TABLE `two_factor_authentication`
  ADD PRIMARY KEY (`id`);

ALTER TABLE `two_factor_authentication`
  MODIFY `id` int(11) NOT NULL AUTO_INCREMENT, AUTO_INCREMENT=1;

安装 Sarah

在终端（Linux、Windows 和 Mac）中输入

composer require spaceshiptrooper/sarah

这将为您当前所在的目录创建一个 composer.json 文件，并下载 Sarah 的文件以及 PHPMailer。这个过程可能需要几分钟，因为我们需要 Sarah 的文件和 PHPMailer，所以需要很多文件。只需等待并保持耐心。如果您收到错误，请提交到这里：此处。

一旦您最终下载了 Sarah 的文件和 PHPMailer，您的目录应该看起来像这样。

vendor
  |___
      |----- composer
      |
      |----- ircmaxell
      |
      |----- phpmailer
      |
      |----- spaceshiptrooper
      |
      |----- autoload.php

composer 目录和 composer 文件中的缓存字符串是由 composer 命令生成的。ircmaxell 是必需的，并从 https://github.com/ircmaxell/password_compat 下载。这是为了向后兼容和支持使用 PHP 5.4 及以下版本的用户。由于某些比这更低的版本存在一些问题，该库的最低支持为 5.3.7。如果您使用的是 PHP 5.5 及更高版本，那么您不必担心这个库，因为 PHP 5.5 内置了这个功能。所以这个库将被忽略。spaceshiptrooper 目录是 Sarah 所在的位置。autoload.php 文件也是由 composer 生成的。然而，一些仓库需要 autoload.php 文件，而一些则不需要。ircmaxell、phpmailer 和 Sarah 都不需要 autoload.php，但是它仍然随着 composer 命令一起提供。所以这没关系。

如何使用 Sarah

下一步是将 Sarah 的 bootstrap.php 文件包含到您的应用程序中。您应该在 POST 请求期间调用 Sarah 的 sendMail() 方法。通过 GET 请求发送它可能是多余的，也是不必要的。

以下是如何实例化 Sarah 的类的示例。

<?php
session_start(); // Start the session

use \Sarah\Sarah;

// Require Sarah's bootstrap file.
require_once('vendor/spaceshiptrooper/sarah/bootstrap.php');

// Instantiate Sarah's class and pass the required parameters in the constructor.
$sarah = new Sarah([
	'SMTP_HOST' => '', // Your SMTP's host.
	'SMTP_EMAIL' => '', // Your SMTP email.
	'SMTP_PASSWORD' => '', // Your SMTP password.
	'SMTP_PORT' => 465, // Your SMTP's port (usually 465 or 587).
	'SMTP_FROM' => 'Noreply', // You can put this reply-from as anybody you want.
	'SMTP_SECURE' => 'ssl', // Use either tls or ssl. Only use ssl if your SMTP server allows it.
	'SUCCESS_DIE' => false, // true or false. Set this to true only if you want to die the entire page after succession.
	'CALLBACK_URL' => '', // Callback URL should be the URL you want to return the user to upon succession.
	'DATABASE' => [
		'TYPE' => 'mysql', // Don't change this if you aren't using other database types.
		'DB_HOST' => 'localhost', // Your database server.
		'DB_USERNAME' => '', // Your database's username.
		'DB_PASSWORD' => '', // Your database's password.
		'DB_DATABASE' => '', // Your actual database you are working in.
		'COST' => 10, // The cost password_hash needs
	]
]);

一个小提示

默认情况下，password_hash 的成本为 10。但是，您可以指定您想要的任何成本。成本越高，密码越安全，但是需要更多的资源。成本越低，密码越不安全，需要的资源也越少。这完全取决于您在两者之间找到平衡。

您可以在 POST 请求中使用以下代码。

$sarah->sarah->setCharacterAmount(10); // The amount of characters you want in the authentication key.
$sarah->sarah->sendMail([
	'email_subject' => 'Just a test', // The email subject you want to send to the user.
	'user_id' => 1, // The user's ID. This should be from your database if you are using user IDs.
	'first_name' => 'Test', // The user's first name. This should be from your database if you are using first names.
	'email' => 'test@test.com' // The user's email. This should be from your database if you are using email addresses.
]);

为了验证用户是否已经通过认证，认证时已经设置了一个 $_SESSION。因此，我们可以检查该 $_SESSION 饼干是否已设置，如果已设置，则表示用户已成功认证。

if(isset($_SESSION['CALLBACK_SUCCESS'])) {

	// The user has already authenticated successfully.

} else {

	// Doesn't look like the user has authenticated at all.

}

这是您可以基本上允许用户通过您的 $_SESSION 饼干或其他方式登录的地方。

什么是 SMTP？

简单邮件传输协议（SMTP）是发送电子邮件的下一步。PHP 中的默认 mail() 函数 不应 被依赖。这个函数 可能 或 可能不 会随机时间工作。使用 mail() 函数时没有任何 100% 的保证。这意味着什么？这意味着 PHP 的 mail() 函数 可能 或 可能不 会将其指定的任何电子邮件发送到目标。这就是为什么 Sarah 选择通过名为 PHPMailer 的 SMTP 库发送电子邮件的原因。

SMTP 库和 mail() 函数在用法上的区别是什么？

这里有很大的区别。SMTP需要多个信息。您需要提供SMTP主机、SMTP用户名（也视为SMTP电子邮件）、SMTP密码、SMTP端口以及SMTP协议类型（tls或ssl）。而mail()函数只需要接收者的电子邮件地址、主题行和消息正文。

现在，你可能想知道：“为什么我们不能直接使用mail()函数，因为它既简单又容易理解？”简单的回答是：“你根本不能依赖它。不能保证它甚至会发送任何电子邮件到你的目标地址。”

即使它有70%的时间可以发送电子邮件，这里有一个我最近在我的电子邮件订阅中看到的问题。这与mail()函数的使用有关。

https://sitepoint.com/community/t/important-update-managing-email-addresses-for-php-asp-mail-scripts-whois-coms-friendly-reminder/274333

实际上，获取SMTP信息并不太难。您可以使用您的Gmail、Hotmail或Ymail作为SMTP。以下是一些使用Gmail、Hotmail和Ymail设置SMTP的文章。您可以将这些相同的步骤应用于Sarah。

https://wpsitecare.com/gmail-smtp-settings/ <-- Gmail

https://lifewire.com/what-are-windows-live-hotmail-smtp-settings-1170861 <-- Hotmail

https://help.yahoo.com/kb/SLN4724.html <-- Ymail

一旦您完成了Sarah的设置，给它旋转一下。希望您没有弄坏它！享受吧。