SimpleWebAuthn项目中iOS Passkey注册的Base64Url编码问题解析

问题背景

在iOS平台上实现Passkey注册功能时，开发者经常会遇到一个令人困惑的错误："UnexpectedRPIDHash: Unexpected RP ID hash"。这个错误通常发生在使用ASAuthorizationPlatformPublicKeyCredentialProvider进行Passkey注册，并在服务器端使用SimpleWebAuthn库进行验证时。

问题本质

经过深入分析，这个问题实际上源于Base64和Base64Url编码格式之间的不匹配。iOS系统生成的凭证数据使用的是标准Base64编码，而WebAuthn规范要求使用Base64Url编码格式进行传输和验证。这种微妙的编码差异导致了服务器端验证失败。

技术细节

Base64与Base64Url的区别

1. 字符替换：

   • Base64Url将标准Base64中的"+"替换为"-"
   • 将"/"替换为"_"

2. 填充处理：

   • Base64Url通常会去除末尾的"="填充字符

3. URL安全性：

   • Base64Url编码后的字符串可以直接用于URL，无需额外编码

iOS实现中的关键点

在iOS端发送凭证数据到服务器前，必须进行编码转换：

func base64ToBase64Url(_ base64: String) -> String {
    return base64
        .replacingOccurrences(of: "+", with: "-")
        .replacingOccurrences(of: "/", with: "_")
        .trimmingCharacters(in: CharacterSet(charactersIn: "="))
}

服务器端验证流程

服务器端的SimpleWebAuthn库期望接收Base64Url编码的数据。验证流程主要包括：

1. 接收客户端发送的凭证数据
2. 验证RP ID哈希是否匹配
3. 检查挑战值(challenge)是否正确
4. 验证原始来源(origin)是否可信

解决方案

要解决这个问题，开发者需要在iOS端对以下关键字段进行Base64到Base64Url的转换：

1. 凭证ID(credentialId)
2. 原始ID(rawId)
3. 证明对象(attestationObject)
4. 客户端数据JSON(clientDataJSON)

示例实现：

let body: [String: Any] = [
    "email": email,
    "challenge": challengeB64,
    "credential": [
        "id": base64ToBase64Url(credentialId),
        "rawId": base64ToBase64Url(credentialId),
        "type": "public-key",
        "response": [
            "attestationObject": base64ToBase64Url(attestationObject),
            "clientDataJSON": base64ToBase64Url(clientDataJSON)
        ]
    ]
]

最佳实践

1. 统一编码标准：在整个系统中明确使用Base64Url编码
2. 错误处理增强：在服务器端增加更明确的错误提示
3. 文档记录：在项目文档中明确编码要求
4. 测试验证：编写专门的测试用例验证编码转换逻辑

总结

iOS Passkey注册过程中的"UnexpectedRPIDHash"错误通常是由编码格式不匹配引起的。通过正确实现Base64到Base64Url的转换，可以确保iOS生成的凭证数据能够被SimpleWebAuthn库正确验证。这个问题提醒我们在实现WebAuthn相关功能时，需要特别注意各种规范的细节要求，特别是编码格式这样的基础但关键的差异。