Accès anticipéSur invitation, et les SDK ne sont pas encore publiés.Demander une invitation
Aller au contenu
Docs

É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éditeurCléSes événementsverified_by
Votre serveurSend events from a server, lyr_srv_Vérifiésserver
Votre app Apple sur un vrai iPhone, iPad ou Apple Watch, configurée pour App AttestSend events, lyr_ing_Vérifiésapp_attest
Votre app Android sur un vrai appareil, configurée pour Key AttestationSend events, lyr_ing_Vérifiéskey_attestation
Tout le reste avec la clé d'ingestionSend events, lyr_ing_Non vérifiésvide
Tout ce qui utilise une clé d'accès completFull access, lyr_adm_Non vérifiésvide

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_attestation et none). 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

  1. 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.
  2. 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).
  3. 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 sur production pour les builds App Store et TestFlight. Sans cela, Apple utilise son environnement de développement, qui vérifie aussi.
  4. Utilisez le SDK Swift. Son option appAttest vaut true par 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'appelle attest) : 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

  1. 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 signingReport et copiez le SHA-256 de cette variante.
  2. 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).
  3. Utilisez le SDK Android. Son option attest vaut true par 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 signingReport se lance dans le dossier android de 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-After tels quels : c'est d'après eux que le SDK décide de réessayer un lot ou de l'abandonner.
  • Un 401 ou un 403 fait 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-src de 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 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
Free20 000
Pro200 000
Business4 000 000
UnlimitedSans 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.