README

WebAuthn

一个简单的PHP WebAuthn (FIDO2) 服务器库

本项目目标是提供一个小巧、轻量、易于理解的库，用于保护使用密码、安全密钥（如Yubico或Solo）、Android或Windows Hello指纹登录。

手册

查看 /_test 了解此库的简单用法。查看 webauthn.lubu.ch 了解一个工作示例。

支持的声明格式

android-key ✅
android-safetynet ✅
apple ✅
fido-u2f ✅
none ✅
packed ✅
tpm ✅

注意

此库支持使用X.509证书签名的验证器或自认证的验证器。不支持ECDAA。

工作流程

         JAVASCRIPT            |          SERVER
------------------------------------------------------------
                         REGISTRATION


   window.fetch  ----------------->     getCreateArgs
                                             |
navigator.credentials.create   <-------------'
        |
        '------------------------->     processCreate
                                             |
      alert ok or fail      <----------------'


------------------------------------------------------------
                      VALIDATION


   window.fetch ------------------>      getGetArgs
                                             |
navigator.credentials.get   <----------------'
        |
        '------------------------->      processGet
                                             |
      alert ok or fail      <----------------'

认证

通常，当有人登录时，您只需确认他们正在使用注册时使用的同一设备。在这种情况下，您不需要任何形式的认证。但是，如果您需要额外的安全措施，例如，您的公司要求使用Solokey进行登录，您可以通过直接认证验证其真实性。公司还可以购买使用其自签名的根证书的验证器，使他们能够验证验证器是否与其组织相关。

无认证

只需验证设备是注册时使用的同一设备。如果您只检查“none”格式，则可以使用此库进行“none”认证。

提示

如果您想为公共网站提供安全的登录，这可能是您想要使用的。

间接认证

浏览器可能用更隐私友好和/或更易于验证的同一数据的版本替换AAGUID和认证声明（例如，通过使用匿名CA）。如果浏览器使用匿名证书，则不能针对任何根CA进行验证。如果您选择多个格式但不提供任何根CA，此库将设置认证为间接。

提示

混合解决方案，客户端可能会被浏览器警告，但您知道他们使用的是哪种设备（统计数据规则！）

直接认证

浏览器提供有关标识设备的数据，设备可以被唯一识别。用户可能会在多个网站上被追踪，因此浏览器可能会显示警告消息，提醒提供此数据时进行注册。如果您选择多个格式并提供根CA，此库将设置认证为直接。

提示

如果您知道您的客户端使用的是哪种设备并确保只使用这些设备，这可能正是您想要的。

密钥/客户端端可发现凭据

客户端端可发现凭据源是一种公钥凭据源，其凭据私钥存储在验证器、客户端或客户端设备中。这种客户端端存储需要具有驻留凭据能力的验证器。这仅由FIDO2硬件支持，不支持旧的U2F硬件。

注意

密钥是一种允许在设备上共享存储的凭据的技术。从服务器端的技术角度来看，与客户端端可发现凭据没有区别。区别仅在于手机或计算机系统会自动通过云服务在用户的设备之间同步凭据。跨设备同步的密钥由操作系统透明管理。

它是如何工作的？

在典型的服务器端密钥管理过程中，用户通过输入用户名，在某些情况下还需要输入密码来发起请求。服务器验证用户的凭据，并在认证成功后检索与该用户账户关联的所有公钥标识符列表。然后，此列表返回给验证器，验证器选择它颁发的第一个凭证标识符，并使用注册过程中注册的公钥响应一个可以进行验证的签名。

在客户端密钥过程中，用户不需要提供用户名或密码。相反，验证器在其自己的内存中搜索是否有为受信任方（域）保存的密钥。如果找到密钥，则认证过程将与服务器发送标识符列表时相同，验证过程没有差异。

我该如何使用这个库呢？

注册时

当调用 WebAuthn\WebAuthn->getCreateArgs 时，将 $requireResidentKey 设置为 true，以通知验证器它应该在内存中保存注册信息。

登录时

当调用 WebAuthn\WebAuthn->getGetArgs 时，不要提供任何 $credentialIds（验证器将自己在内存中查找 ID，并以用户句柄的形式返回用户 ID）。将验证器类型设置为 hybrid（通过二维码扫描的 Passkey）和 internal（存储在设备本身上的 Passkey）。

缺点

RP ID（=域）保存在验证器上。因此，如果验证器丢失，理论上可以找到验证器使用的服务，并在那里登录。

设备支持

内置密钥自动同步到所有用户的设备的可用性：（也请参阅passkeys.dev/device-support）

Apple iOS 16+ / iPadOS 16+ / macOS Ventura+
Android 9+
Microsoft Windows 11 23H2+

要求

PHP >= 8.0，并包含 OpenSSL 和 Multibyte String
支持 WebAuthn 的浏览器（Firefox 60+、Chrome 67+、Edge 18+、Safari 13+）
PHP Sodium（或Sodium Compat）用于Ed25519支持

lbuchs / webauthn

维护者

详细信息