XiHan Framework 处于预览阶段

查看获取方式
跳转到内容

XiHan.Framework.Security.WebAuthn ​

通行密钥(WebAuthn)的依赖方实现:生成注册与认证仪式的选项,按 RFC-0008「WebAuthn」的顺序核对浏览器交回的响应,提供 security.webauthn@1。适用于要做免密码、免用户名登录的应用。

项内容
包 IDXiHan.Framework.Security.WebAuthn
环层Ring 3(实现)
能力提供 security.webauthn@1;依赖 kernel.hosting@1
特性入口WebAuthnSecurityFeature(清单 xihan.security.webauthn,role: provider)
配置节XiHan:Security:WebAuthn
依赖XiHan.Framework.Security.Abstractions、System.Formats.Cbor;公开面不暴露第三方类型
AOT兼容
稳定性Preview

概述 ​

WebAuthnSecurityFeature 登记单例 WebAuthnCeremonies(ADR-0170)。它是无状态的:

  • 挑战由应用保存到仪式结束(一次性、有时限),凭据由应用存储;框架不定义凭据存储,凭据的归属、命名、启停与租户是应用的业务。
  • 选项与响应和 WebAuthn Level 3 的 JSON 同形,二进制一律 base64url(无填充);浏览器侧用 PublicKeyCredential.parseCreationOptionsFromJSON / parseRequestOptionsFromJSON 还原选项,用 credential.toJSON() 交回响应。
  • 证明一律请求 none,证明声明不校验:公钥是否真由认证器持有,由之后每次认证的签名证明。
  • 算法依次是 ES256(P-256)、PS256、RS256;EdDSA 不支持(BCL 没有 Ed25519)。

何时使用 ​

  • 登录页「用通行密钥登录」,免用户名、免密码:用本包,用户验证与可发现凭据都按缺省的 Required。
  • 只想把通行密钥当第二因素:同样用本包,ResidentKey 设为 Discouraged,认证时把用户已有的凭据放进 allowCredentials。
  • 需要证明信任链或元数据服务(只允许特定型号的安全密钥):本包不做。WebAuthnRegisteredCredential.Aaguid 在 none 证明下是认证器自报的型号,没有经过证明,任何认证器都能报成别的型号,不能拿来做型号白名单;要限制型号须请求 direct 或 enterprise 证明,自己核对证明声明的信任链与元数据服务(ADR-0216)。

安装与启用 ​

bash
dotnet add package XiHan.Framework.Security.WebAuthn --prerelease

当前是预览版,安装要带 --prerelease;从源码或本地包源引用见快速上手。

csharp
using XiHan.Framework.Hosting.AspNetCore;
using XiHan.Framework.Profiles.Standard;
using XiHan.Framework.Security.WebAuthn;

var builder = WebApplication.CreateBuilder(args);
builder.AddXiHan(xihan => xihan.UseStandardProfile().UseFeature<WebAuthnSecurityFeature>());

var app = builder.Build();
app.UseXiHan();
app.Run();

配置 ​

键(XiHan:Security:WebAuthn)类型缺省说明
RelyingPartyIdstring必填可注册的域名(如 example.com、本地开发的 localhost),不带协议、端口与路径
RelyingPartyNamestring同 RelyingPartyId认证器上显示的名称
Originsstring[]必填允许的来源,形如 scheme://host[:port];主机必须等于 RP ID 或是它的子域,https 之外只允许 localhost 的 http
UserVerificationRequired / Preferred / DiscouragedRequired为 Required 时核对响应带 UV 标志
ResidentKeyRequired / Preferred / DiscouragedRequired是否要求可发现凭据
TimeoutSecondsint300仪式的超时,写进选项交给浏览器
ChallengeSizeint32挑战的字节数,16 到 64
json
{
  "XiHan": {
    "Security": {
      "WebAuthn": {
        "RelyingPartyId": "example.com",
        "RelyingPartyName": "Example",
        "Origins": [ "https://example.com", "https://admin.example.com" ]
      }
    }
  }
}

配置在装配时读一次,缺少必填项或值不合法即启动失败。前端开发服务器与后端端口不同时,来源写浏览器地址栏里的那个(如 http://localhost:9100)。

主要类型 ​

类型说明
WebAuthnSecurityFeature特性入口
WebAuthnOptions上表的配置;FromConfiguration 读取并核对
WebAuthnCeremoniesCreateRegistrationOptions、CreateAuthenticationOptions、VerifyRegistration、VerifyAuthentication
WebAuthnCreationOptions / WebAuthnRequestOptions交给浏览器的选项
WebAuthnRegistrationResponse / WebAuthnAuthenticationResponse浏览器交回的响应
WebAuthnRegisteredCredential注册核对通过的凭据:凭据 ID、COSE 公钥、算法、签名计数、AAGUID、BE / BS / UV、传输方式
WebAuthnStoredCredential应用存储的凭据,认证时交给核对
WebAuthnVerifiedAssertion认证核对通过的结果:新的签名计数、UV、BS

测试里用 Testing 的 WebAuthnTestAuthenticator 生成合法或篡改过的响应。

使用示例 ​

注册:选项交给浏览器,挑战存进缓存;响应回来后取出挑战(只用一次)再核对。

csharp
public sealed class PasskeyRegistration(WebAuthnCeremonies ceremonies, IPasskeyStore store, IChallengeStore challenges)
{
    public async Task<WebAuthnCreationOptions> BeginAsync(User user, CancellationToken ct)
    {
        var existing = await store.ListAsync(user.Id, ct);
        var options = ceremonies.CreateRegistrationOptions(
            new WebAuthnUserEntity(Base64Url.EncodeToString(user.Id.ToByteArray()), user.UserName, user.DisplayName),
            [.. existing.Select(c => new WebAuthnCredentialDescriptor("public-key", c.CredentialId, c.Transports))]);
        await challenges.SaveAsync(user.Id, options.Challenge, ceremonies.Options.Timeout, ct);
        return options;
    }

    public async Task<Result> CompleteAsync(User user, WebAuthnRegistrationResponse response, CancellationToken ct)
    {
        var challenge = await challenges.TakeAsync(user.Id, ct);
        if (challenge is null)
        {
            return Error.Validation("APP_VALIDATION_001", "app.passkey.expired");
        }

        var registered = ceremonies.VerifyRegistration(response, challenge);
        return registered.TryGetValue(out var credential) ? await store.AddAsync(user.Id, credential, ct) : registered.Error!;
    }
}

认证:免用户名时 allowCredentials 为空;响应回来后按凭据 ID 找到存储的凭据(连同所属用户的句柄),核对通过即更新签名计数。

  • 登录前已认出用户(先填账号、作为第二因素):把这个用户的句柄传给 expectedUserHandle,凭据不属于他即拒绝。不传的话,知道口令的攻击者能用自己账号下的通行密钥完成别人的登录。
  • 免用户名:传 null,响应必须带 userHandle;登录的用户取结果的 UserHandle(来自存储的凭据),不取响应里的句柄。
csharp
var stored = await store.FindAsync(response.Id, ct);
// 先填账号的流程传那个用户的句柄;免用户名的流程传 null
var verified = ceremonies.VerifyAuthentication(response, challenge, new WebAuthnStoredCredential(stored.CredentialId, stored.PublicKey, stored.SignCount, stored.UserHandle), expectedUserHandle);
if (verified.TryGetValue(out var assertion))
{
    await store.UpdateSignCountAsync(stored.CredentialId, assertion.SignCount, ct);
    var userHandle = assertion.UserHandle;
}

注册时把选项里的 user.id 作为凭据的所属用户存下来,并拒绝已经登记过的凭据 ID:凭据 ID 由认证器给出,同一 ID 不应属于两个用户。

行为与限制 ​

  • 核对的顺序与每条失败的 reason 见 RFC-0008「WebAuthn」:解析不了是 SECURITY_VALIDATION_006,算法不支持是 SECURITY_VALIDATION_007,核对不通过是 SECURITY_DENIED_005。
  • 签名计数:新旧值有一个不为 0 时新值必须大于旧值,否则 SECURITY_DENIED_006,参数 stored、received。它是认证器可能被复制的信号,应用应提醒本人或停用这把凭据;都为 0 的认证器(多数同步的通行密钥)不计数,放行。
  • 挑战定长比较;客户端数据的哈希在签名里,挑战与来源受签名保护。
  • 凭据属于谁(ADR-0179):存储的凭据必须记下所属用户;传了 expectedUserHandle 时凭据必须属于他,没传时响应必须带 userHandle;响应带了句柄就必须等于所属用户。任一不满足为 user_handle。它在验签之后判定:签名不对的响应只得到 signature,没有私钥的人试不出凭据属于谁(ADR-0216)。
  • RSA 公钥的模长 2048 到 4096 位,超出为 public_key:验签的开销随模长增长(ADR-0216)。
  • 客户端扩展结果不读;crossOrigin 为真(跨源的 iframe 里发起)一律拒绝。
  • 应用给的期望挑战或存储的凭据 ID 不是 base64url 抛 ArgumentException:那是调用方的错误。

相关 ​

Released under The MIT License