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（通过 QR 码扫描的 Passkey）和 internal（存储在设备本身的 Passkey）。

缺点

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

设备支持

内置 Passkey 的可用性，这些 Passkey 可自动同步到用户的所有设备：（另见passkeys.dev/device-support）

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

要求

PHP >= 8.0，带有 OpenSSL 和多字节字符串
支持 WebAuthn 的浏览器（Firefox 60+、Chrome 67+、Edge 18+、Safari 13+）
用于 Ed25519 支持的 PHP Sodium（或 Sodium 兼容）

lbuchs / webauthn

维护者

详细信息