Paquets de preuves : un enregistrement signé d'un événement de confiance GNSS

Un paquet est un enregistrement technique, pas un avis juridique. Il indique ce que le moteur Kshana a calculé à partir d'un journal de récepteur donné sous une configuration donnée, et permet à quiconque de vérifier que rien n'y a été modifié par la suite. Il ne dit ni ce qui a causé un événement, ni qui en était responsable, ni si une obligation a été remplie, ni que le journal montre ce que le récepteur a réellement reçu. Le manifeste et le résumé le disent tous deux.

Un paquet de preuves sert pour un rapport d'incident, un assureur ou la question d'un régulateur : « que disait votre système du signal GNSS entre ces deux instants, et peut-on se fier à cet enregistrement ? »

Créer un paquet#

# once: a signing key. The private key stays with you; never commit it.
kshana evidence keygen --out signer.key        # writes signer.key (0600) and signer.key.pub

kshana receiver-trust evidence session.toml \
    --from 100 --to 260 \                       # seconds since the first epoch, or ISO-8601 UTC
    --key signer.key --out pack/ \
    --title "Berth 4, 14 June"                  # optional

Pour un paquet créé à partir d'une session de laboratoire, --lab-attestation lab.toml consigne dans le manifeste signé la déclaration de l'opérateur sur le montage (conduit ou blindé, atténuation ou boîtier, ce qui a émis un éventuel signal RF) ; voir HARDWARE-SAFETY.md. Elle est consignée telle que fournie et n'est jamais vérifiée.

--from et --to sont des secondes depuis la première époque du journal, ou une heure UTC ISO-8601 lorsque le journal indique sa propre heure de début. --out ne doit pas contenir déjà de fichiers. --created-utc prend une heure UTC réelle telle que 2026-01-02T03:04:05Z (toute autre valeur est refusée) ou none, qui omet l'heure de création et rend le paquet reproductible octet pour octet. L'heure de création est ce que déclare le signataire ; rien ne la compare à une horloge, ce à quoi sert le jeton d'horodatage facultatif.

Le fichier de clé contient une graine Ed25519 de 32 octets sous forme de 64 chiffres hexadécimaux ; fournissez la vôtre (par exemple une graine conservée dans votre système de gestion de clés) ou laissez keygen en créer une. kshana avertit si le fichier est lisible par d'autres utilisateurs. .gitignore exclut *.evidence-key ; nommez votre clé ainsi si elle se trouve dans une copie de travail.

Ce que contient un paquet#

Extrait du journal. Le lecteur indique l'étendue en octets source de chaque époque ; l'extrait est donc la plus petite plage d'octets contenant chaque époque de la fenêtre (byte-range) : NMEA, u-blox UBX, observations RINEX 3 et journaux Android. Il est haché sous forme d'octets bruts, jamais comme du texte décodé. Pour un flux en direct ou du RINEX 2, il n'y a pas d'étendue ; le journal entier est alors inclus et le manifeste indique whole-log (la fenêtre limite les époques rapportées, pas les octets inclus). Le résumé indique laquelle des deux situations s'applique. Un extrait est un enregistrement des octets de la fenêtre, pas un journal autonome : par exemple, un extrait RINEX n'a pas d'en-tête de fichier.

Chaîne de hachages. Le manifeste liste les fichiers dans un ordre fixe. link₀ = SHA-256("kshana- evidence-chain/1") ; pour chaque fichier, linkᵢ = SHA-256(linkᵢ₋₁ ‖ SHA-256(file) ‖ len(name) ‖ name) (longueur sur 4 octets, gros-boutiste). Le dernier maillon est chain_head. Réordonner, retirer ou substituer un fichier modifie la chaîne ; la signature couvre la chaîne.

Vérifier un paquet#

kshana evidence verify pack/ --pubkey signer.key.pub [--log session.nmea] \
    [--require-timestamp] [--allow-unpinned] [--json]

Le code de sortie 0 signifie vérifié ; 1 signifie que quelque chose a échoué ; 2 signifie une erreur d'utilisation ; 3 signifie que le paquet est intact mais que son signataire n'était pas épinglé (voir ci-dessous). Chaque contrôle indique réussite, échec ou ignoré, et chaque échec est nommé :

Modifier un seul octet de n'importe quel fichier fait échouer la vérification pour la raison correspondante : un artefact modifié est signalé comme une discordance de hachage de ce fichier et rien d'autre ; un manifeste modifié fait échouer la signature. Recalculer les hachages et la chaîne après avoir modifié un fichier n'aide pas sans la clé de signature ; seule la signature échoue alors.

Épinglez la clé. Sans --pubkey, un paquet prouve seulement qu'il est intact par rapport à la clé qu'il désigne lui-même, que n'importe qui peut générer. La vérification retourne donc 3 et affiche « INTACT, BUT THE SIGNER IS NOT PINNED » plutôt que « VERIFIED » ; --allow-unpinned accepte en connaissance de cause la clé propre du paquet et affiche « VERIFIED against the key the pack names itself (signer NOT pinned; pass --pubkey) ». Obtenez la clé publique du signataire auprès de lui par une voie de confiance (pas depuis le paquet) et passez-la avec --pubkey : 64 chiffres hexadécimaux ou le fichier .pub. Passer la clé privée par erreur est reconnu et refusé. L'empreinte (les 128 premiers bits du SHA-256 de la clé, soit 32 chiffres hexadécimaux) est affichée pour une comparaison à l'œil ; épingler la clé complète est la voie fiable.

Format du paquet et procédure de vérification (normatifs)#

Cette section est la spécification à partir de laquelle un vérificateur indépendant est écrit. Les mots en majuscules sont des exigences. Un paquet est un répertoire (ou toute table associant un nom de fichier à des octets) de fichiers nommés exactement comme ci-dessous ; un vérificateur travaille sur les octets de chaque fichier tels que stockés et ne resérialise jamais rien.

Fichiers. Les fichiers d'artefacts, dans cet ordre fixe, sont log-slice.bin, config.json, epochs.json, summary.html. Un paquet a aussi manifest.json et manifest.sig, et PEUT avoir timestamp.tsr. Tout autre nom est un fichier non listé.

Hexadécimal. Toute chaîne hexadécimale est en minuscules 0-9a-f uniquement, sans espace ; les majuscules ne sont pas acceptées. Les valeurs SHA-256 font 64 chiffres, la clé publique fait 64 chiffres, la signature fait 128 chiffres.

manifest.sig. L'hexadécimal minuscule de 128 chiffres de la signature Ed25519 de 64 octets (RFC 8032, le schéma Ed25519 pur) sur les octets exacts de manifest.json, suivi d'exactement un \n et de rien d'autre. La signature DOIT être vérifiée strictement : une signature dont la valeur S n'est pas inférieure à l'ordre du groupe L est invalide.

manifest.json. Un objet JSON en UTF-8. Ses membres (un vérificateur DOIT trouver chacun avec le type JSON indiqué ; les membres supplémentaires sont ignorés) :

signer.fingerprint correspond aux 32 premiers chiffres hexadécimaux du SHA-256 calculé sur les 32 octets de la clé publique.

Chaîne de hachages. link0 est le SHA-256 des 23 octets ASCII kshana-evidence-chain/1. Pour chaque artefact dans l'ordre, link = SHA-256( previous_link (32 bytes) ‖ SHA-256(file) (32 bytes) ‖ len(name) as 4 bytes big-endian ‖ name as UTF-8 ), où SHA-256(file) est pris dans le sha256 consigné au manifeste pour cet artefact (la chaîne est donc une propriété du manifeste et se vérifie par rapport à lui, non par rapport aux fichiers).

Procédure. Un vérificateur exécute ces étapes dans l'ordre et recueille chaque échec ; le résultat est l'ensemble des échecs, chacun étant un code et, lorsque c'est indiqué, le fichier name. Il NE DOIT PAS s'arrêter au premier échec, sauf là où c'est indiqué. pin est la clé publique à laquelle le vérificateur a reçu l'instruction de se fier, le cas échéant.

1. Pas de manifest.json : échec manifest-missing ; arrêt.
2. Si manifest.json n'est pas un objet JSON dont chaque membre ci-dessus a le type indiqué (y compris des entrées artifacts avec chaque membre, et log.slice) : échec manifest-malformed. Sinon, si format n'est pas la valeur ci-dessus : unsupported-format.
3. Phase de signature. Cette phase est exécutée que le manifeste ait été lisible ou non. Si le manifeste était lisible, la clé nommée est signer.public_key ; si ce n'est pas 64 chiffres hexadécimaux minuscules, échec public-key-malformed (pas de clé nommée) ; sinon, si signer.fingerprint n'en est pas l'empreinte, échec public-key-malformed (la clé reste utilisable). Si un pin et une clé nommée existent et diffèrent : échec public-key-mismatch. La clé de contrôle est pin s'il en a été fourni un, sinon la clé nommée s'il y en a une ; avec aucun des deux, il n'y a pas de clé de contrôle (cela inclut tous les cas où le manifeste n'était pas lisible et où aucun pin n'a été fourni). S'il n'y a pas de manifest.sig : signature-missing. Sinon, si le fichier n'est pas exactement 128 chiffres hexadécimaux minuscules plus un \n : signature-malformed. Sinon, s'il y a une clé de contrôle qui n'est pas un encodage valide de clé publique Ed25519 : public-key-malformed. Sinon, s'il y a une clé de contrôle et que la signature ne se vérifie pas strictement sur les octets de manifest.json (quels qu'ils soient) : signature-invalid. (Sans clé de contrôle, la signature n'est pas vérifiée et aucun échec n'est levé à ce titre.)
4. Si le manifeste n'était pas lisible (l'étape 2 a donné manifest-malformed) : arrêt ici.
5. Artefacts. Si les noms de artifacts ne sont pas exactement les quatre ci-dessus dans l'ordre : artifact-list-malformed. Puis, pour chaque entrée du manifeste, dans l'ordre : si le paquet n'a aucun fichier de ce nom, file-missing (nom) ; sinon, si sa longueur diffère de bytes, file-size-mismatch (nom) ; et, indépendamment, si le SHA-256 du fichier diffère de sha256, file-hash-mismatch (nom).
6. Fichiers non listés : pour chaque fichier du paquet autre que manifest.json, manifest.sig, timestamp.tsr et les noms de artifacts du manifeste : unlisted-file (nom).
7. Chaîne. Parcourir les artifacts du manifeste dans l'ordre à partir de link0. Si le sha256 d'une entrée n'est pas 64 chiffres hexadécimaux minuscules : manifest-malformed et la chaîne est abandonnée (pas de contrôle de tête). Sinon, calculer le maillon ; s'il diffère du link de l'entrée : chain-mismatch (nom). Après le parcours, si la chaîne n'a pas été abandonnée et que le dernier maillon diffère de chain_head : chain-head-mismatch.
8. Extrait et époques. Lever slice-record-inconsistent (au plus une fois par raison, et un vérificateur signale le code une seule fois quel que soit le nombre de raisons applicables) si l'un quelconque des cas suivants se produit : start > end ; end > full_bytes ; le sha256 de l'entrée log-slice.bin diffère de slice.sha256 ; le bytes de cette entrée diffère de end - start ; ou kind est whole-log et l'un quelconque de start != 0, end != full_bytes, slice.sha256 != full_sha256. Si epochs.json existe et s'analyse comme un tableau JSON dont la longueur diffère de epochs_in_window : epoch-count-mismatch.
9. Journal complet. Seulement si le vérificateur a reçu les octets du journal d'origine : si leur SHA-256 diffère de log.full_sha256, full-log-hash-mismatch ; sinon, si la plage start..end n'est pas à l'intérieur du journal ou si les octets du journal à cet endroit diffèrent de log-slice.bin, slice-not-from-full-log.
10. Horodatage. Sans timestamp.tsr : si le vérificateur a reçu l'instruction d'en exiger un, timestamp-missing ; sinon, rien. Avec un fichier : s'il ne peut pas être lu comme un jeton ou une réponse RFC 3161 (voir ci-dessous), timestamp-malformed ; sinon, si son empreinte de message n'est pas le hachage, dans l'algorithme propre à l'empreinte (SHA-256, SHA-384 ou SHA-512), des octets de manifest.json : timestamp-imprint-mismatch.

Le paquet est vérifié exactement lorsque l'ensemble des échecs est vide. Le fait que le signataire ait été épinglé est signalé séparément et ne modifie pas l'ensemble des échecs.

Jeton d'horodatage. Un jeton est un ContentInfo DER dont le type de contenu est CMS SignedData (1.2.840.113549.1.7.2) et dont le type de contenu encapsulé est id-ct-TSTInfo (1.2.840.113549.1.9.16.1.4) ; une réponse est un TimeStampResp DER (un PKIStatusInfo suivi du jeton) dont le statut est 0 ou 1. L'algorithme d'empreinte de message du TSTInfo doit être SHA-256, SHA-384 ou SHA-512 avec un condensat de la longueur de cet algorithme, et son genTime une heure calendaire UTC réelle. Le BER à longueur indéfinie n'est pas accepté. La signature de l'autorité et la chaîne de certificats ne sont vérifiées que lorsque des ancres de confiance sont fournies (--tsa-ca, ci-dessous).

L'étiquette de preuve (0,40)#

Un paquet créé par la version 0,40 ou ultérieure porte, dans config.json, une entrée evidence (le niveau, VALIDATED, MODELLED ou PARTNER, qui est le statut le plus faible parmi ses lignes, ainsi que les identifiants et les exigences des lignes de la matrice de vérification sur lesquelles repose le contenu du paquet : la ligne d'intégrité du paquet, les lignes receiver-trust, et les lignes de notation jammertest ou d'aller-retour pour ces paquets) et config_version "1.1". Elle se trouve dans config.json, de sorte que le hachage de fichier du manifeste, la chaîne de hachage et la signature la couvrent : la modifier fait échouer la vérification. kshana evidence verify indique le niveau et les identifiants de lignes.

Le changement est additif et à sens unique. Le format du manifeste reste kshana-evidence/1 : le texte normatif ci-dessus dit qu'un vérificateur DOIT trouver cette valeur, et le vérificateur indépendant de scripts/ le fait. La version mineure est donc portée par config_version (absente pour un paquet créé avant 0,40, ce qui signifie 1,0), et non par une nouvelle chaîne format. Un paquet créé avant 0,40 n'a pas d'étiquette et se vérifie sans changement ; kshana evidence verify indique « no evidence label (pre-0.40 pack) ». Les tests sont tests/evidence_pack_label.rs (y compris les paquets de référence antérieurs à la version 0.40 versionnés) et tests/evidence_labels_doc_sync.rs.

Horodatage RFC 3161 (facultatif)#

Un jeton d'horodatage délivré par une autorité d'horodatage montre que le manifeste existait à un instant que l'autorité atteste. Le jeton porte sur manifest.json ; il est donc demandé après la création du paquet (il n'y a aucun moyen d'en fournir un lors de la création du paquet, et create_bundle refuse un jeton qui ne porte pas sur ce manifeste exact) :

openssl ts -query -data pack/manifest.json -sha256 -cert -out req.tsq
# send req.tsq to your authority, get the response, then:
kshana evidence attach-timestamp pack/ response.tsr
openssl ts -verify -in response.tsr -data pack/manifest.json -CAfile authority-ca.pem

kshana evidence verify lit le jeton (un jeton seul ou une réponse complète), vérifie qu'il a été accordé et que son empreinte de message est égale au hachage de manifest.json, et affiche l'heure qu'il indique. Sans ancres de confiance, il ajoute « timestamp authority signature not verified by Kshana » et signale authority_signature_verified: false ; exécutez la ligne openssl ts -verify ci-dessus pour cette partie. Un jeton dont l'empreinte diffère, ou qui ne s'analyse pas, est un échec. Les types de contenu, la longueur de l'empreinte et l'heure de génération du jeton sont contrôlés pour leur cohérence.

Avec --tsa-ca authority-ca.pem (un ou plusieurs certificats PEM, tous de confiance), verify contrôle aussi l'autorité, hors ligne, à la manière de openssl ts -verify : le condensat de message des attributs signés, la signature (RSA PKCS#1 v1.5, RSA-PSS, ECDSA P-256 ou P-384), la liaison du certificat de signature ESS, l'usage étendu de clé critique timeStamping du signataire, et la chaîne jusqu'à une ancre auto-émise, chaque certificat étant valide au genTime du jeton. Un échec est signalé comme timestamp-authority-invalid avec le premier contrôle qui a échoué, et authority_signature_verified n'est vrai que lorsque tout a réussi. La révocation (CRL ou OCSP) n'est pas vérifiée. Ce vérificateur concorde avec OpenSSL 3.0.13 sur 27 cas autogénérés (tests/fixtures/evidence_tsa/PREREGISTRATION.md).

Le jeton se trouve à côté du manifeste signé, pas à l'intérieur. Rien dans la signature ni dans la chaîne ne le couvre ; un jeton peut donc être retiré, ou un autre jeton valide substitué, sans que la signature échoue. verify note donc lorsqu'un paquet n'en a pas, et --require-timestamp fait d'un jeton manquant un échec (timestamp-missing) ; un jeton substitué n'est détecté que s'il ne correspond pas au manifeste. attach-timestamp refuse d'écraser un jeton existant sauf si vous passez --replace. Si un horodatage compte pour vous, conservez le jeton et le résultat de la vérification dans vos propres archives, et exigez-le.

Depuis le code#

kshana::evidence::build_receiver_trust_pack est l'unique point d'entrée que la ligne de commande et toutes les autres surfaces appellent pour créer un paquet : un scénario, les octets du journal (et ceux du fichier de navigation, pour RINEX), la fenêtre sous forme de texte, un titre et une heure de création facultative, plus la graine de signature, en entrée ; les fichiers, le nombre d'époques, l'extrait, le hachage du manifeste et l'empreinte du signataire en sortie. Il ne lit ni fichier ni horloge, de sorte que les mêmes entrées donnent les mêmes octets. En dessous, create_bundle et verify_bundle sont des fonctions pures : des octets en entrée (EvidenceInput, une graine de 32 octets, un BTreeMap<String, Vec<u8>> de fichiers), des résultats sérialisables en sortie (Files, VerifyReport). Elles n'utilisent ni fichier, ni horloge, ni état de processus, et se compilent pour wasm32, de sorte que les surfaces Python, WebAssembly et serveur les appellent telles quelles. La ligne de commande n'en est qu'une fine enveloppe.

Ce qu'un paquet ne fait pas#

• Il ne ré-exécute pas l'évaluation. Quiconque dispose du journal complet et de config.json peut ré-exécuter kshana receiver-trust et comparer avec epochs.json ; le paquet prouve ce qui a été enregistré, pas que le moteur avait raison.
• Il ne prouve pas que le journal est authentique ou complet. Le hachage du journal complet lie l'enregistrement à un seul fichier ; il appartient à l'opérateur d'établir d'où provient ce fichier.
• Il ne porte aucune affirmation de performance sur la détection ou le rejet de l'interférence.
• C'est un enregistrement technique, et non un avis juridique ni une certification.