已验证事件
用服务器密钥发送的事件,或由你自己的 Apple 或 Android 应用发送并经设备证明的事件,会被标记为已验证,这样你就能把它们和任何持有公开密钥的人都能发送的事件区分开。
采集密钥随你的应用或网页一起发布,所以任何人都能复制它,发送看起来和你的应用一样的事件。Lyrelog 会把能与这类事件区分开的事件 标记为已验证(verified),共有三种情况:
- 用服务器密钥发送的事件,这是只有你的服务器才持有的机密;
- 由你自己的 Apple 应用在真实设备上发送的事件,由 Apple 通过 App Attest 证明;
- 由你自己的 Android 应用在真实设备上发送的事件,由设备的安全硬件通过 Key Attestation 证明。
已验证意味着什么
已验证事件不可能是由从应用或网页中复制出公开密钥的人发送的。使用服务器密钥时,它附带的是只有项目服务器才持有的密钥。 使用 App Attest 时,它来自项目的正版应用,由项目团队签名,运行在正品 Apple 设备上。使用 Key Attestation 时, 它来自项目的正版 Android 应用,用项目的证书签名,运行在系统为原装且已锁定的真实 Android 设备上。
它并不能证明事件的内容是真实的。服务器可能发送错误的值,在越狱设备上使用正版应用的人也仍然可以让它发送事件。 已验证事件的可信程度,取决于发送它的代码。
用公开的采集密钥发送、又没有应用证明的事件是未验证的:任何持有该密钥的人都能发送一模一样的事件。 来自网页、以及来自未使用 App Attest 或 Key Attestation 的应用的事件,大多属于这种情况,这很正常。
由谁验证
| 发送方 | 密钥 | 它的事件 | verified_by |
|---|---|---|---|
| 你的服务器 | Send events from a server,lyr_srv_ | 已验证 | server |
| 你的 Apple 应用,运行在真实的 iPhone、iPad 或 Apple Watch 上,并已配置 App Attest | Send events,lyr_ing_ | 已验证 | app_attest |
| 你的 Android 应用,运行在真实设备上,并已配置 Key Attestation | Send events,lyr_ing_ | 已验证 | key_attestation |
| 其他任何使用采集密钥的发送方 | Send events,lyr_ing_ | 未验证 | 空 |
| 任何使用完全访问密钥的发送方 | Full access,lyr_adm_ | 未验证 | 空 |
Lyrelog 在采集时为每个事件设置这个值,依据是批次所带的密钥,以及(对采集密钥而言)批次携带的 App Attest 或 Key Attestation token。
客户端无法设置它:自己发送 verified_by 的行会被拒绝,并返回 unknown fields: verified_by。
服务器密钥和采集密钥一样只能追加事件,不能读取。如何创建服务器密钥,参见密钥。
在控制台中
- 在事件列表中,事件名旁边的小盾牌图标表示已验证事件。
- 打开的事件会在标题栏显示 Verified 徽章。在 Context 下,Sender 会显示 Verified, server key、Verified, App Attest、Verified, Key Attestation 或 Not verified, public key。
- 在 Explorer 中,Filter 菜单有一个 Verified by 字段,取值为
Server key、App Attest、Key Attestation 和 Not verified(在 URL 中为
server、app_attest、key_attestation和none)。选中除 Not verified 以外的全部值,就只看已验证事件;选 Not verified 则看其余事件。
读取 API 在每个事件上返回 verified_by("server"、"app_attest"、"key_attestation",
未验证时为 ""),并可以用 verified=server、verified=app_attest、verified=key_attestation 或
verified=none 按它筛选,也可以同时指定多个(verified=server|app_attest|key_attestation)。
服务器
后端(Node、Python、Go、JVM 上的 Java 或 Kotlin,或在服务器上使用 curl)应该用服务器密钥
lyr_srv_... 发送:它的事件是已验证的,而且不受单个地址每日配额的限制。
在示例中出现 lyr_ing_... 的地方,把服务器密钥交给 SDK 即可,其他都不用改。
像对待任何机密一样保管它:放在服务器的环境变量或密钥存储中,绝不要放进应用、网页或代码仓库。如果泄露了,请吊销它并新建一个。
Apple 应用(App Attest)
Apple 的 App Attest 让应用可以向服务器证明:它是由其团队签名的正版应用,运行在正品 Apple 设备上。
Swift SDK 会替你完成这一切,iOS 上的 React Native
和 Flutter SDK 也一样(通过 Swift SDK 实现)。Lyrelog 把经过证明的应用发送的事件存为已验证
(verified_by 为 app_attest)。
配置
- 找到应用的 App ID:你的 Team ID、一个点号,再加上 bundle id,例如
ABCDE12345.com.example.app。 Team ID 在你的 Apple Developer 账户的 Membership 下。 - 在 Lyrelog 中打开 Project settings。 当项目包含 iOS 应用平台时,那里会有 Verified events from your Apple apps 部分。用 Add 添加 App ID。 所有者最多可以添加 10 个,每个应用一个(iPhone 应用和它的手表应用有不同的 bundle id)。
- 在 Xcode 中,为应用 target 添加 App Attest capability(Signing & Capabilities)。对应的 entitlement 是
com.apple.developer.devicecheck.appattest-environment。App Store 和 TestFlight 构建请设为production。 不设置时,Apple 使用其开发环境,同样可以通过验证。 - 使用 Swift SDK。它的
appAttest选项默认为true,所以不需要再写任何代码。React Native 和 Flutter 也一样 (它们的选项是attest):项目设置完全相同,因为实际工作由底层的 Swift SDK 完成。
要关闭它,可以移除 App ID(事件会像以前一样以未验证状态到达),或在应用中设置 appAttest: false。
工作原理
- 每次安装只需做一次:SDK 会在设备的 Secure Enclave 中生成一个密钥,由 Apple 针对 Lyrelog 发出的一次性 challenge 对其进行证明。 Lyrelog 检查 Apple 的证书链,并确认应用属于项目的某个 App ID,然后保存该密钥的公钥部分:每次安装一个,180 天未使用后删除。
- 之后 SDK 会获得一个有效期为一天的 token,随每个批次一起发送。它用该密钥生成的签名(assertion)来续期 token, 其计数器无法被重放。
- 发送从不等待这个过程。在应用拿到 token 之前,以及任何环节出错时,事件都会照常发送,并以未验证状态存储。 批次永远不会因为 App Attest 而被拒绝。
不适用的情况
App Attest 适用于真实的 iPhone、iPad 和 Apple Watch。以下情况即使一切都已配置好,发送的也是未验证事件:
- Mac(Apple 没有在 Mac 上提供 App Attest),
- 模拟器,
- 大多数 app extension,
- 不支持 App Attest 的设备。
相关路由和 header 见 HTTP API。
只接受来自 iOS 应用的已验证事件
默认关闭。在同一个设置部分中,Accept only verified events from the iOS app 会让 Lyrelog 暂不接收所有事件为
platform: ios 的未验证批次:它返回 425 Too Early,SDK 会保留该批次并稍后重新发送。新安装的首批事件会等几秒钟拿到 token,
然后以已验证状态到达,所以这里不会丢失任何数据。
只有当所有人用的都是已配置 App Attest 的应用版本时才开启它。在此之前,来自旧版本、模拟器以及在 Mac 上运行的 iPad 应用的事件, 永远无法证明自己:它们会在设备上等待,直到达到 SDK 的保留上限(20 MB 和 7 天),并且永远不会被存储。 来自其他平台以及来自服务器密钥的事件照常接收。
Android 应用(Key Attestation)
Android 的 Key Attestation 让应用可以在手机的安全硬件(可信执行环境 TEE,或 StrongBox 芯片)中生成密钥,并从设备获得一条
一直签名到 Google 的证书链,其中描述了该密钥、应用以及手机的状态。Lyrelog 自己检查这条证书链:不需要 Google 账号、
Play Integrity 或 Google Cloud 项目。Android SDK 会替你完成这一切,Android 上的
React Native 和 Flutter SDK 也一样
(通过 Android SDK 实现)。Lyrelog 把经过证明的应用发送的事件存为已验证(verified_by 为 key_attestation)。
配置
- 找到应用的包名(它的 application id,例如
com.example.app)以及签名证书的 SHA-256 指纹:- 对于从 Google Play 安装的构建,应用由 Google 签名:在 Play Console 中打开应用,依次进入 Test and release、 App integrity,复制 App signing key certificate 的 SHA-256。
- 对于你自己签名的构建(上传密钥,或开发时的 debug 密钥),运行
./gradlew signingReport,复制对应 variant 的 SHA-256。
- 在 Lyrelog 中打开 Project settings。当项目包含 Android 应用平台时,那里会有 Verified events from your Android apps 部分。用 Add 添加包名和指纹; 如果有多个证书为发送事件的构建签名,就为每个证书再添加一次同一个包名和对应的指纹(每个包名最多 5 个,最多 10 个包名)。
- 使用 Android SDK。它的
attest选项默认为true,所以不需要再写任何代码。React Native 和 Flutter 也一样: 项目设置完全相同,因为实际工作由底层的 Android SDK 完成。在 React Native 或 Flutter 项目中,./gradlew signingReport要在应用的android文件夹中运行。
要关闭它,可以移除包名(事件会像以前一样以未验证状态到达),或在应用中设置 attest = false。
检查哪些内容
- 证书链逐级签名,一直到 Google 的某个 attestation 根证书,并且链中没有任何证书在 Google 的吊销列表上。
- 密钥位于手机的安全硬件中,在那里生成,并能响应 Lyrelog 发出的一次性 challenge。
- 手机启动的是原装且经过验证的系统,并且 bootloader 已锁定。
- 应用属于项目的某个包名,并用其某个证书签名。
随后 Lyrelog 保存该密钥的公钥部分(每次安装一个,180 天未使用后删除),并给应用一个有效期为一天的 token,应用随每个批次发送它。 应用用该密钥对新的一次性 challenge 签名来续期 token。发送从不等待这个过程:在应用拿到 token 之前,以及任何环节出错时, 事件都会照常发送,并以未验证状态存储。批次永远不会因为 Key Attestation 而被拒绝。
不适用的情况
以下情况即使一切都已配置好,发送的也是未验证事件:
- 模拟器(它们没有安全硬件,证书链也通不到 Google),
- 已 root 的手机、bootloader 已解锁或刷了第三方系统的手机,
- 没有硬件级密钥(hardware-backed key)的手机(Android 8 以后已很少见),
- 用项目未列出的证书签名的构建。
相关路由见 HTTP API。
只接受来自 Android 应用的已验证事件
默认关闭,工作方式与 iOS 的同名选项相同:开启后,所有事件为
platform: android 的未验证批次都会收到 425 Too Early,并在设备上等待。只有当所有人用的都是已配置 Key Attestation
的版本时才开启它:来自旧版本、模拟器以及已 root 或已解锁手机的事件永远无法证明自己,也永远不会被存储。
网页:通过你自己的服务器
网页无法持有服务器密钥:浏览器里的任何东西都能被读取。要从网页获得已验证事件,请通过你自己的后端转发。 网页发送到你网站上的一个路由,由该路由用服务器密钥把批次转发给 Lyrelog。
要清楚这能证明什么。这些事件之所以“已验证”,仅仅是因为它们经过了你的服务器。任何人都能向你网站上的路由发请求,所以 转发路由应该只接受来自你自己已登录会话的事件,并限制单个会话的发送量。一个来者不拒的转发路由什么也验证不了。
在网页中,把 JavaScript SDK 的 endpoint 指向转发路由。它是一个基础 URL:SDK 会发送到
<endpoint>/v1/events:batch。apiKey 不能为空,但转发路由会替换它,所以随便填个占位值即可:
export const log = Lyrelog.init({
endpoint: "https://example.com/api/lyrelog", // posts to /api/lyrelog/v1/events:batch
apiKey: "relay", // replaced by the server key on your server
});转发路由,写成 Next.js route handler(app/api/lyrelog/[...path]/route.ts):
import { getSession } from "@/lib/auth"; // your own sign-in
export async function POST(request: Request) {
const session = await getSession(request);
if (!session) return new Response(null, { status: 401 });
const encoding = request.headers.get("Content-Encoding");
const upstream = await fetch("https://ingest.lyrelog.com/v1/events:batch", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.LYRELOG_SERVER_KEY}`, // lyr_srv_..., server only
"Content-Type": request.headers.get("Content-Type") ?? "application/x-ndjson",
...(encoding ? { "Content-Encoding": encoding } : {}),
},
body: await request.arrayBuffer(),
});
const headers = new Headers({ "Content-Type": "application/json" });
const retryAfter = upstream.headers.get("Retry-After");
if (retryAfter) headers.set("Retry-After", retryAfter);
return new Response(await upstream.text(), { status: upstream.status, headers });
}需要注意:
- 原样传回状态码和
Retry-After:SDK 根据它们决定是重试还是丢弃一个批次。 401或403会让 SDK 停止发送,直到页面重新加载。请在访客登录之后再启动客户端,而不是之前。- 国家取自把批次发送给 Lyrelog 的地址,而现在这个地址是你的服务器。转发的事件带的是你服务器所在的国家, 而不是访客的国家。
- 如果你设置了内容安全策略(Content Security Policy),请把转发路由的地址加入
connect-src(同一站点上的路由已被'self'覆盖)。
其他应用和网页
来自未使用 App Attest 的 Apple 应用、未使用 Key Attestation 的 Android 应用,以及直接发送的网页的事件,使用的是公开的采集密钥, 且没有应用证明,所以它们是未验证的。网页可以通过你自己的服务器获得已验证事件。 有两项限制,让被复制的密钥难以造成太大危害:
- 套餐的每月事件数,按整个组织计算;
- 单个地址的每日配额,见下文。
单个地址的每日配额
使用公开密钥(采集密钥或完全访问密钥)时,单个发送地址在一个 UTC 日内,跨组织的所有项目,最多只能发送套餐每月事件数的五十分之一。 IPv6 地址按 /64 计算。只有非已验证的事件才计入。
| 套餐 | 单个地址每天的事件数 |
|---|---|
| Free | 20,000 |
| Pro | 200,000 |
| Business | 4,000,000 |
| Unlimited | 无限制 |
这远远超过一台设备的发送量。设置它,是为了让从应用中复制出来的密钥无法在一台机器上耗尽组织整个月的用量。 已验证事件(来自服务器密钥、App Attest 或 Key Attestation)不计入。
超过后,该地址会收到 429,Retry-After 最长一小时,直到下一个 UTC 日。其他地址照常发送。SDK 会像处理任何 429
一样重试,并在其队列限制内保留事件。响应体见 HTTP API。
如果你的某台服务器达到了这个限制,那它应该改用服务器密钥。