Événements vérifiés
Les événements envoyés avec une clé serveur, ou par votre propre app Apple ou Android prouvée par l'appareil, sont marqués vérifiés, pour les distinguer de ceux que n'importe quel détenteur de la clé publique aurait pu envoyer.
Une clé d'ingestion est livrée dans votre app ou votre page web : n'importe qui peut donc la copier et envoyer des événements qui ressemblent à ceux de votre app. Lyrelog marque comme vérifiés (verified) les événements qu'il sait distinguer de ceux-là, de trois façons :
- les événements envoyés avec une clé serveur, un secret que seuls vos serveurs détiennent ;
- les événements envoyés par votre propre app Apple sur un vrai appareil, ce qu'Apple prouve avec App Attest ;
- les événements envoyés par votre propre app Android sur un vrai appareil, ce que le matériel sécurisé de l'appareil prouve avec Key Attestation.
Ce que « vérifié » signifie
Un événement vérifié ne peut pas avoir été envoyé par quelqu'un qui a copié la clé publique d'une app ou d'une page web. Avec une clé serveur, il est arrivé avec une clé que seuls les serveurs du projet détiennent. Avec App Attest, il vient de l'app authentique du projet, signée par son équipe, sur un appareil Apple authentique. Avec Key Attestation, il vient de l'app Android authentique du projet, signée avec le certificat du projet, sur un vrai appareil Android dont le système d'origine est verrouillé.
Cela ne prouve pas que ce que dit l'événement est vrai. Un serveur peut envoyer une valeur fausse, et quelqu'un qui utilise la vraie app sur un appareil jailbreaké pourrait toujours lui faire envoyer des événements. Un événement vérifié n'est fiable que dans la mesure où le code qui l'a envoyé l'est.
Les événements envoyés avec la clé d'ingestion publique et sans preuve de l'app ne sont pas vérifiés : n'importe quel détenteur de cette clé aurait pu envoyer les mêmes. C'est le cas de la plupart des événements des pages web et des apps qui n'utilisent ni App Attest ni Key Attestation, et c'est normal.
Qui vérifie
| Expéditeur | Clé | Ses événements | verified_by |
|---|---|---|---|
| Votre serveur | Send events from a server, lyr_srv_ | Vérifiés | server |
| Votre app Apple sur un vrai iPhone, iPad ou Apple Watch, configurée pour App Attest | Send events, lyr_ing_ | Vérifiés | app_attest |
| Votre app Android sur un vrai appareil, configurée pour Key Attestation | Send events, lyr_ing_ | Vérifiés | key_attestation |
| Tout le reste avec la clé d'ingestion | Send events, lyr_ing_ | Non vérifiés | vide |
| Tout ce qui utilise une clé d'accès complet | Full access, lyr_adm_ | Non vérifiés | vide |
Lyrelog renseigne cette valeur sur chaque événement à l'ingestion, d'après la clé avec laquelle le
lot est arrivé et, pour une clé d'ingestion, le jeton App Attest ou Key Attestation qu'il porte.
Un client ne peut pas la définir : une ligne qui envoie elle-même verified_by est refusée avec
unknown fields: verified_by.
Comme une clé d'ingestion, une clé serveur ne peut qu'ajouter des événements ; elle ne peut pas les lire. Voir Clés pour en créer une.
Dans le tableau de bord
- Dans la liste des événements, un petit bouclier à côté du nom de l'événement signale un événement vérifié.
- Un événement ouvert affiche un badge Verified dans son en-tête. Sous Context, Sender indique Verified, server key, Verified, App Attest, Verified, Key Attestation ou Not verified, public key.
- Dans l'explorateur, le menu Filter propose un champ Verified by
avec les valeurs Server key, App Attest, Key Attestation et Not verified (dans
l'URL :
server,app_attest,key_attestationetnone). Choisissez tout sauf Not verified pour ne voir que les événements vérifiés, ou Not verified pour les autres.
L'API de lecture renvoie verified_by sur chaque événement ("server",
"app_attest", "key_attestation", ou "" quand il n'est pas vérifié) et filtre dessus avec
verified=server, verified=app_attest, verified=key_attestation ou verified=none, ou
plusieurs à la fois (verified=server|app_attest|key_attestation).
Serveurs
Un backend (Node, Python, Go, Java ou Kotlin sur la JVM, ou curl depuis un
serveur) devrait envoyer avec une clé serveur, lyr_srv_... : ses événements sont vérifiés, et il
n'a pas de quota journalier par adresse. Donnez au SDK la
clé serveur là où les exemples montrent lyr_ing_... ; rien d'autre ne change.
Gardez-la comme n'importe quel secret : dans l'environnement de votre serveur ou votre gestionnaire de secrets, jamais dans une app, une page web ou un dépôt. Si elle fuite, révoquez-la et créez-en une autre.
Apps Apple (App Attest)
App Attest, d'Apple, permet à une app de prouver à un serveur qu'elle est l'app authentique,
signée par son équipe, et qu'elle tourne sur un appareil Apple authentique. Le
SDK Swift s'en charge pour vous, tout comme les SDK
React Native et Flutter sur
iOS, via le SDK Swift. Lyrelog stocke les événements d'une app prouvée comme vérifiés
(verified_by vaut app_attest).
Le configurer
- Trouvez l'App ID de votre app : votre Team ID, un point et le bundle id, par exemple
ABCDE12345.com.example.app. Le Team ID se trouve dans votre compte Apple Developer, sous Membership. - Dans Lyrelog, ouvrez Project settings. La section Verified events from your Apple apps y figure quand le projet compte une app iOS parmi ses plateformes. Ajoutez l'App ID avec Add. Un propriétaire peut en ajouter jusqu'à 10, un par app (une app iPhone et son app pour la montre ont des bundle ids différents).
- Dans Xcode, ajoutez la capability App Attest à la cible de l'app (Signing & Capabilities).
C'est l'entitlement
com.apple.developer.devicecheck.appattest-environment. Réglez-le surproductionpour les builds App Store et TestFlight. Sans cela, Apple utilise son environnement de développement, qui vérifie aussi. - Utilisez le SDK Swift. Son option
appAttestvauttruepar défaut, il n'y a donc rien d'autre à coder. Il en va de même pour React Native et Flutter (leur option s'appelleattest) : les paramètres du projet sont les mêmes, puisque c'est le SDK Swift sous-jacent qui fait le travail.
Pour le désactiver, retirez les App IDs (les événements arrivent non vérifiés, comme avant), ou
définissez appAttest: false dans l'app.
Comment ça marche
- Une fois par installation, le SDK crée une clé dans la Secure Enclave de l'appareil, et Apple l'atteste sur un challenge à usage unique fourni par Lyrelog. Lyrelog vérifie la chaîne de certificats d'Apple et que l'app fait partie des App IDs du projet, puis garde la moitié publique de la clé : une par installation, supprimée après 180 jours sans utilisation.
- Le SDK obtient ensuite un jeton, valable un jour, qu'il envoie avec chaque lot. Il renouvelle le jeton avec une signature de cette clé (une assertion), dont le compteur ne peut pas être rejoué.
- L'envoi n'attend jamais tout cela. Tant que l'app n'a pas de jeton, et chaque fois que quelque chose échoue, les événements sont envoyés et stockés non vérifiés. Un lot n'est jamais refusé à cause d'App Attest.
Là où cela ne s'applique pas
App Attest fonctionne sur les vrais iPhone, iPad et Apple Watch. Dans les cas suivants, les événements sont envoyés non vérifiés, même avec tout configuré :
- les Mac (Apple n'y propose pas App Attest),
- le simulateur,
- la plupart des extensions d'app,
- les appareils qui ne prennent pas en charge App Attest.
Les routes et le header sont dans l'API HTTP.
N'accepter que les événements vérifiés de l'app iOS
Désactivé par défaut. Dans la même section des paramètres, Accept only verified events from the
iOS app demande à Lyrelog de retenir tout lot non vérifié dont les événements indiquent
platform: ios : il répond 425 Too Early, et le SDK garde le lot pour le renvoyer plus tard. Les
premiers événements d'une nouvelle installation attendent quelques secondes son jeton, puis
arrivent vérifiés : rien n'est perdu de ce côté.
Ne l'activez que lorsque tout le monde a une version de l'app avec App Attest configuré. D'ici là, les événements des anciennes versions, du simulateur et d'une app iPad qui tourne sur un Mac ne pourront jamais faire leurs preuves : ils attendent sur l'appareil, dans la limite de ce que garde le SDK (20 Mo et 7 jours), et ne sont jamais stockés. Les événements des autres plateformes, et ceux d'une clé serveur, sont acceptés comme avant.
Apps Android (Key Attestation)
Key Attestation, d'Android, permet à une app de créer une clé dans le matériel sécurisé du
téléphone (son environnement d'exécution de confiance, ou une puce StrongBox) et d'obtenir de
l'appareil une chaîne de certificats, signée jusqu'à Google, qui décrit la clé, l'app et l'état du
téléphone. Lyrelog vérifie lui-même cette chaîne : il n'y a besoin ni de compte Google, ni de Play
Integrity, ni de projet Google Cloud. Le SDK Android s'en charge
pour vous, tout comme les SDK React Native et
Flutter sur Android, via le SDK Android. Lyrelog stocke les
événements d'une app prouvée comme vérifiés (verified_by vaut key_attestation).
Le configurer
- Trouvez le package de votre app (son application id, par exemple
com.example.app) et l'empreinte SHA-256 du certificat avec lequel elle est signée :- Pour les builds installés depuis Google Play, c'est Google qui signe l'app : dans Play Console, ouvrez l'app, puis Test and release, App integrity, et copiez le SHA-256 de l'App signing key certificate.
- Pour les builds que vous signez vous-même (une clé d'importation, ou la clé de debug en
développement), lancez
./gradlew signingReportet copiez le SHA-256 de cette variante.
- Dans Lyrelog, ouvrez Project settings. La section Verified events from your Android apps y figure quand le projet compte une app Android parmi ses plateformes. Ajoutez le package et l'empreinte avec Add ; ajoutez à nouveau le même package avec une autre empreinte pour chaque certificat qui signe des builds envoyant des événements (jusqu'à 5 par package, 10 packages).
- Utilisez le SDK Android. Son option
attestvauttruepar défaut, il n'y a donc rien d'autre à coder. Il en va de même pour React Native et Flutter : les paramètres du projet sont les mêmes, puisque c'est le SDK Android sous-jacent qui fait le travail. Dans un projet React Native ou Flutter,./gradlew signingReportse lance dans le dossierandroidde l'app.
Pour le désactiver, retirez les packages (les événements arrivent non vérifiés, comme avant), ou
définissez attest = false dans l'app.
Ce qui est vérifié
- La chaîne est signée, certificat par certificat, jusqu'à l'une des racines d'attestation de Google, et aucun de ses certificats ne figure sur la liste de Google des certificats révoqués.
- La clé vit dans le matériel sécurisé du téléphone, y a été créée, et répond à un challenge à usage unique fourni par Lyrelog.
- Le téléphone a démarré sur son système d'origine, vérifié, et son bootloader est verrouillé.
- L'app fait partie des packages du projet et est signée avec l'un de ses certificats.
Lyrelog garde ensuite la moitié publique de la clé (une par installation, supprimée après 180 jours sans utilisation) et donne à l'app un jeton, valable un jour, qu'elle envoie avec chaque lot. Elle renouvelle le jeton en signant avec cette clé un nouveau challenge à usage unique. L'envoi n'attend jamais tout cela : tant que l'app n'a pas de jeton, et chaque fois que quelque chose échoue, les événements sont envoyés et stockés non vérifiés. Un lot n'est jamais refusé à cause de Key Attestation.
Là où cela ne s'applique pas
Dans les cas suivants, les événements sont envoyés non vérifiés, même avec tout configuré :
- les émulateurs (ils n'ont pas de matériel sécurisé, et leurs chaînes ne remontent pas jusqu'à Google),
- les téléphones rootés, ceux dont le bootloader est déverrouillé ou qui ont un système modifié,
- les téléphones sans clés adossées au matériel (rare depuis Android 8),
- les builds signés avec un certificat que le projet ne liste pas.
Les routes sont dans l'API HTTP.
N'accepter que les événements vérifiés de l'app Android
Désactivé par défaut, et cela fonctionne comme l'option iOS :
une fois activé, tout lot non vérifié dont les événements indiquent platform: android reçoit
425 Too Early et attend sur l'appareil. Ne l'activez que lorsque tout le monde a une version avec
Key Attestation : les événements des anciennes versions, des émulateurs et des téléphones rootés
ou déverrouillés ne pourront jamais faire leurs preuves et ne sont jamais stockés.
Pages web, via votre propre serveur
Une page web ne peut pas détenir de clé serveur : tout ce qui est dans le navigateur peut être lu. Pour obtenir des événements vérifiés depuis une page, relayez-les par votre propre backend. La page envoie à une route de votre site, et cette route transmet le lot à Lyrelog avec la clé serveur.
Mesurez bien ce que cela prouve. Ces événements ne sont vérifiés qu'au sens où ils sont passés par votre serveur. N'importe qui peut poster sur une route de votre site : le relais ne doit accepter que des événements venant de vos propres sessions connectées, et plafonner ce qu'envoie une session. Un relais qui accepte tout de n'importe qui ne vérifie rien.
Dans la page, faites pointer l'endpoint du SDK JavaScript vers le relais.
C'est une URL de base : le SDK poste sur <endpoint>/v1/events:batch. apiKey ne peut pas être
vide, mais le relais la remplace, donc n'importe quelle valeur factice convient :
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
});Le relais, sous forme de route handler Next.js (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 });
}Bon à savoir :
- Renvoyez le statut et
Retry-Aftertels quels : c'est d'après eux que le SDK décide de réessayer un lot ou de l'abandonner. - Un
401ou un403fait arrêter les envois du SDK jusqu'au rechargement de la page. Démarrez le client une fois le visiteur connecté, pas avant. - Le pays vient de l'adresse qui envoie le lot à Lyrelog, qui est désormais celle de votre serveur. Les événements relayés portent le pays de votre serveur, pas celui du visiteur.
- Ajoutez l'adresse du relais au
connect-srcde votre Content Security Policy si vous en définissez une ('self'couvre une route du même site).
Autres apps et pages web
Les événements des apps Apple sans App Attest, des apps Android sans Key Attestation et des pages web qui envoient directement utilisent la clé d'ingestion publique sans preuve de l'app : ils ne sont donc pas vérifiés. Une page web peut obtenir des événements vérifiés via votre propre serveur. Deux limites empêchent une clé copiée de faire beaucoup de dégâts :
- le quota mensuel d'événements de l'offre, pour toute l'organisation, et
- le quota journalier d'une adresse, ci-dessous.
Le quota journalier d'une adresse
Avec une clé publique (une clé d'ingestion, ou une clé d'accès complet), une adresse d'envoi peut envoyer au plus un cinquantième du quota mensuel d'événements de l'offre par jour UTC, tous projets de l'organisation confondus. Les adresses IPv6 comptent par /64. Seuls les événements non vérifiés comptent.
| Offre | Événements par jour depuis une adresse |
|---|---|
| Free | 20 000 |
| Pro | 200 000 |
| Business | 4 000 000 |
| Unlimited | Sans limite |
C'est bien plus que ce qu'envoie un appareil. Cette limite existe pour qu'une clé copiée depuis une app ne puisse pas épuiser le mois de l'organisation depuis une seule machine. Les événements vérifiés (par une clé serveur, App Attest ou Key Attestation) n'y comptent pas.
Au-delà, cette adresse reçoit 429 avec un Retry-After d'au plus une heure, jusqu'au jour UTC
suivant. Les autres adresses continuent d'envoyer. Les SDK réessaient comme pour n'importe quel
429, en gardant les événements dans les limites de leur file d'attente. Le corps de la réponse
est décrit dans l'API HTTP.
Si l'un de vos serveurs l'atteint, c'est qu'il devrait utiliser une clé serveur.