Corona-Warn-App 验证服务器API接口详解

概述

Corona-Warn-App验证服务器（cwa-verification-server）是德国健康预警应用生态系统的关键组件，负责处理与健康检测结果验证相关的业务流程。本文将从技术角度深入解析其API设计、功能模块和使用方式。

API基础信息

• 当前版本：1.5.0-SNAPSHOT
• 协议：OpenAPI 3.0.1
• 授权许可：Apache 2.0
• 默认服务器地址：http://localhost:8080

核心功能接口

1. 检测结果查询接口

路径：/version/v1/testresult

方法：POST

功能：根据注册令牌(RegistrationToken)获取健康检测结果。如果注册令牌属于TeleTan(电话TAN)，则结果始终为阳性。

请求参数：

• 头部可选参数：cwa-fake (字符串类型)
• 请求体：必须包含RegistrationToken对象

响应状态：

• 200：成功获取检测结果，返回TestResult对象
• 403：DOB哈希的检测结果与哈希的检测结果不匹配
• 400/405/415/500：标准错误响应

技术要点：

• 该接口实现了检测结果与用户身份的解耦，通过令牌机制保护用户隐私
• 支持结果填充(responsePadding)增强安全性

2. TAN生成接口

路径：/version/v1/tan

方法：POST

功能：根据注册令牌生成TAN(事务授权号)，用于提交诊断密钥。

请求参数：

• 头部可选参数：cwa-fake (字符串类型)
• 请求体：必须包含RegistrationToken对象

响应状态：

• 201：成功生成TAN，返回Tan对象
• 400：注册令牌不存在
• 其他标准错误响应

技术要点：

• 采用UUID格式的TAN(8-4-4-4-12格式)
• 一次一密设计，确保安全性

3. TAN验证接口

路径：/version/v1/tan/verify

方法：POST

功能：验证TAN是否由验证服务器签发。

请求参数：

• 请求体：必须包含Tan对象

响应状态：

• 200：验证成功，返回X-CWA-TELETAN-TYPE头部(值为TEST或EVENT)
• 404：TAN验证失败
• 其他标准错误响应

技术要点：

• 内部接口，用于系统间通信
• 区分普通TAN和TeleTAN类型

4. TeleTAN生成接口

路径：/version/v1/tan/teletan

方法：POST

功能：生成7位字符的TeleTAN(电话TAN)，通过电话服务发放。

请求参数：

• 头部必须参数：Authorization (JWT令牌)
• 头部可选参数：X-CWA-TELETAN-TYPE (TEST或EVENT)

响应状态：

• 201：成功生成TeleTAN，返回TeleTan对象
• 其他标准错误响应

技术要点：

• 需要授权令牌访问
• 支持两种TeleTAN类型：测试(TEST)和事件(EVENT)
• 7位字符设计便于电话沟通

5. 注册令牌生成接口

路径：/version/v1/registrationToken

方法：POST

功能：通过提供SHA-256哈希的GUID或TeleTAN获取注册令牌。

请求参数：

• 头部可选参数：cwa-fake (字符串类型)
• 请求体：必须包含RegistrationTokenRequest对象

响应状态：

• 201：成功生成注册令牌，返回RegistrationToken对象
• 400：GUID/TeleTAN已存在
• 其他标准错误响应

技术要点：

• 支持两种密钥类型：GUID和TELETAN
• 可选DOB哈希参数增强安全性
• 生成的注册令牌为标准UUID格式

数据模型详解

1. RegistrationToken (注册令牌)

• 必需字段：registrationToken (符合UUID v4格式)
• 可选字段：responsePadding (响应填充)

2. TestResult (检测结果)

• testResult: 整数类型检测结果
• sc: 长整型时间戳
• labId: 实验室ID字符串
• responsePadding: 响应填充

3. Tan (事务授权号)

• 必需字段：tan (符合UUID v4格式)
• 可选字段：responsePadding

4. AuthorizationToken (授权令牌)

• 必需字段：token (JWT字符串)

5. TeleTan (电话TAN)

• value: 7位字符串值

6. RegistrationTokenRequest (注册令牌请求)

• 必需字段：key (密钥字符串), keyType (GUID或TELETAN)
• 可选字段：keyDob (符合特定模式的DOB哈希)

安全设计考量

1. 令牌机制：所有敏感操作都通过令牌进行，避免直接传递用户信息
2. 请求验证：关键接口需要授权头部或特定验证
3. 响应填充：多个模型支持responsePadding防止时序攻击
4. 格式限制：严格限制输入格式(UUID、特定哈希模式等)
5. 错误处理：统一且信息量适中的错误响应

典型使用流程

1. 用户获取检测后，系统通过/version/v1/registrationToken接口获取注册令牌
2. 用户或系统定期调用/version/v1/testresult查询检测结果
3. 当需要提交诊断密钥时，通过/version/v1/tan生成TAN
4. 诊断服务器通过/version/v1/tan/verify验证TAN有效性
5. 电话服务中心通过/version/v1/tan/teletan生成TeleTAN

开发注意事项

1. 所有接口都要求JSON格式内容
2. 注意处理各种错误状态码
3. 生产环境应配置正确的服务器URL
4. TeleTAN相关接口需要额外授权
5. 关注响应中的可选填充字段

通过这套API设计，Corona-Warn-App实现了检测结果验证流程的安全、可靠运行，同时保护了用户隐私和数据安全。开发者可以根据这些接口规范构建合规的客户端应用或集成系统。