生物认证与 WebAuthn#

public class WebAuthnRegistrationService {
    
    @Autowired
    private RelyingParty relyingParty;
    
    /**
     * 生成注册选项
     * 这些选项由服务器生成并发送给浏览器
     */
    public PublicKeyCredentialCreationOptions generateRegistrationOptions(
            String username, 
            String displayName) {
        
        // 生成随机 challenge（至少 16 字节）
        byte[] challenge = generateSecureRandom(32);
        
        // 生成用户 ID（由服务器生成，不可预测）
        byte[] userId = UUID.randomUUID().toString().getBytes();
        
        // 保存 challenge 到会话或缓存
        sessionStore.saveChallenge(challenge);
        
        return PublicKeyCredentialCreationOptions.builder()
            .rp(PublicKeyCredentialRpEntity.builder()
                .id("example.com")
                .name("Example Application")
                .build())
            .user(PublicKeyCredentialUserEntity.builder()
                .id(userId)
                .name(username)
                .displayName(displayName)
                .build())
            .challenge(challenge)
            .pubKeyCredParams(List.of(
                // ECDSA with SHA-256（推荐）
                PublicKeyCredentialParameters.builder()
                    .type(PublicKeyCredentialType.PUBLIC_KEY)
                    .alg(COSEAlgorithmIdentifier.ES256)
                    .build(),
                // RSA with SHA-256（兼容性）
                PublicKeyCredentialParameters.builder()
                    .type(PublicKeyCredentialType.PUBLIC_KEY)
                    .alg(COSEAlgorithmIdentifier.RS256)
                    .build()
            ))
            .timeout(60000) // 60 秒超时
            .authenticatorSelection(AuthenticatorSelectionCriteria.builder()
                .authenticatorAttachment(AuthenticatorAttachment.PLATFORM)
                .requireResidentKey(false)
                .userVerification(UserVerificationRequirement.PREFERRED)
                .build())
            .attestation(AttestationConveyancePreference.DIRECT)
            .build();
    }
    
    /**
     * 验证注册响应
     */
    public RegistrationResult verifyRegistrationResponse(
            PublicKeyCredential<AuthenticatorAttestationResponse> credential) {
        
        // 从缓存中获取原始 challenge
        byte[] originalChallenge = sessionStore.getChallenge(credential.getId());
        
        RegistrationVerificationRequest request = RegistrationVerificationRequest.builder()
            .credential(credential)
            .expectedChallenge(originalChallenge)
            .expectedOrigin("https://example.com")
            .expectedRpId("example.com")
            .build();
        
        RegistrationResult result = relyingParty.verify(request);
        
        // 存储公钥到数据库
        storePublicKey(result);
        
        return result;
    }
}

public class WebAuthnAuthenticationService {
    
    @Autowired
    private RelyingParty relyingParty;
    
    /**
     * 生成认证请求选项
     */
    public PublicKeyCredentialRequestOptions generateAuthenticationOptions(
            String username) {
        
        // 获取用户的凭证 ID 列表
        List<CredentialRecord> credentials = userService.getCredentials(username);
        List<PublicKeyCredentialDescriptor> allowCredentials = credentials.stream()
            .map(c -> PublicKeyCredentialDescriptor.builder()
                .id(c.getCredentialId())
                .transports(transportsFromDb(c.getTransports()))
                .build())
            .collect(Collectors.toList());
        
        byte[] challenge = generateSecureRandom(32);
        sessionStore.saveChallengeForAuthentication(username, challenge);
        
        return PublicKeyCredentialRequestOptions.builder()
            .challenge(challenge)
            .timeout(60000)
            .rpId("example.com")
            .allowCredentials(allowCredentials)
            .userVerification(UserVerificationRequirement.PREFERRED)
            .build();
    }
    
    /**
     * 验证认证响应
     */
    public AuthenticationResult verifyAuthenticationResponse(
            String username,
            PublicKeyCredential<AuthenticatorAssertionResponse> credential) {
        
        byte[] originalChallenge = sessionStore.getChallengeForUser(username);
        
        AuthenticationVerificationRequest request = AuthenticationVerificationRequest.builder()
            .credential(credential)
            .expectedChallenge(originalChallenge)
            .expectedOrigin("https://example.com")
            .expectedRpId("example.com")
            .build();
        
        AuthenticationResult result = relyingParty.verify(request);
        
        // 更新签名计数器（防止克隆攻击）
        updateSignatureCounter(result);
        
        return result;
    }
}

public class CredentialManager {
    
    /**
     * 凭证数据结构
     */
    @Entity
    public class CredentialRecord {
        @Id
        private String credentialId;  // 凭证 ID（由认证器生成）
        
        private String userId;         // 用户 ID（服务器生成）
        private byte[] publicKey;      // 公钥
        private long signCount;        // 签名计数器
        private String deviceType;     // 设备类型
        private String transports;     // 支持的传输方式 (USB/NFC/BLE)
        private Instant createdAt;
        private Instant lastUsedAt;
        private boolean active;
    }
    
    /**
     * 用户可能注册多个凭证
     * 例如：手机指纹 + 工作电脑 YubiKey + 家用电脑 Windows Hello
     */
    public List<CredentialRecord> getCredentialsForUser(String userId) {
        return credentialRepository.findByUserIdAndActiveTrue(userId);
    }
    
    /**
     * 凭证撤销
     */
    public void revokeCredential(String credentialId) {
        credentialRepository.findByCredentialId(credentialId)
            .ifPresent(c -> c.setActive(false));
    }
}

public class RpConfiguration {
    
    /**
     * rpId 必须满足以下条件之一：
     * 1. 精确匹配 origin 的有效域名
     * 2. 是 origin 域名的有效父域名（仅限 WebAuthn Level 2+）
     */
    public boolean validateRpId(String origin, String rpId) {
        URL originUrl = new URL(origin);
        String originHost = originUrl.getHost();
        
        // 精确匹配
        if (originHost.equals(rpId)) {
            return true;
        }
        
        // 父域名匹配（需要 rpId 以点开头）
        if (rpId.startsWith(".") && originHost.endsWith(rpId)) {
            return true;
        }
        
        return false;
    }
}

AuthenticatorSelectionCriteria.builder()
    .authenticatorAttachment(AuthenticatorAttachment.CROSS_PLATFORM)
    .requireResidentKey(false)
    .userVerification(UserVerificationRequirement.REQUIRED)
    .build();
// CROSS_PLATFORM: 漫游认证器（YubiKey 等）
// PLATFORM: 平台认证器（Touch ID 等）
// REQUIRED: 必须验证用户生物特征/PIN
// PREFERRED: 优先验证，但不强制

@Service
@Slf4j
public class WebAuthnService {
    
    @Autowired
    private RelyingParty relyingParty;
    
    @Autowired
    private CredentialRepository credentialRepository;
    
    /**
     * 凭证注册
     */
    public void registerCredential(String userId, String username, 
            byte[] attestationResponse) throws Exception {
        
        // 解析凭证创建响应
        PublicKeyCredential<AuthenticatorAttestationResponse> credential =
            PublicKeyCredential.parseRegistrationResponseJson(
                new String(attestationResponse, StandardCharsets.UTF_8));
        
        // 验证并注册
        RegistrationResult result = relyingParty.verify(
            RegistrationVerificationRequest.builder()
                .credential(credential)
                .expectedChallenge(getChallenge(userId))
                .expectedOrigin("https://example.com")
                .expectedRpId("example.com")
                .build()
        );
        
        // 存储凭证
        CredentialRecord record = new CredentialRecord();
        record.setCredentialId(credential.getId());
        record.setUserId(userId);
        record.setPublicKey(result.getPublicKeyCose());
        record.setSignCount(result.getSignatureCounter());
        record.setTransports(credential.getResponse().getTransports().orElse(Collections.emptyList()));
        credentialRepository.save(record);
        
        log.info("WebAuthn credential registered for user: {}", username);
    }
    
    /**
     * 凭证认证
     */
    public boolean authenticate(String credentialId, byte[] assertionResponse) {
        
        CredentialRecord credential = credentialRepository.findByCredentialId(credentialId);
        if (credential == null) {
            return false;
        }
        
        PublicKeyCredential<AuthenticatorAssertionResponse> credential2 =
            PublicKeyCredential.parseAssertionResponseJson(
                new String(assertionResponse, StandardCharsets.UTF_8));
        
        AuthenticationResult result = relyingParty.verify(
            AuthenticationVerificationRequest.builder()
                .credential(credential2)
                .expectedChallenge(getChallenge(credential.getUserId()))
                .expectedOrigin("https://example.com")
                .expectedRpId("example.com")
                .expectedPublicKey(credential.getPublicKeyCose())
                .expectedSignatureCounter(credential.getSignCount())
                .build()
        );
        
        // 更新签名计数器
        credential.setSignCount(result.getSignatureCounter());
        credential.setLastUsedAt(Instant.now());
        credentialRepository.save(credential);
        
        return true;
    }
    
    /**
     * 检测克隆攻击
     * 如果签名计数器小于等于上次值，说明可能存在克隆
     */
    private void detectCloneAttack(CredentialRecord credential, long newCount) {
        if (newCount <= credential.getSignCount()) {
            log.error("Potential clone attack detected for credential: {}", 
                credential.getCredentialId());
            // 撤销凭证，发送安全告警
            credential.setActive(false);
            credentialRepository.save(credential);
            securityAlertService.sendAlert("WebAuthn clone attack", credential);
        }
    }
}