Reference / Evidence
Telegram Evidence Archive Format & Verification
Contents of the signed ZIP, record kinds, process receipts, people profiles, off-site copies and offline verification.
TgWitness preserves account-visible Telegram observations in a signed journal. Recipients can verify the saved records, attachments and reports against a trusted collector key, check external time from a third party for the last record, and compare the journal with a checkpoint they retained earlier. This page describes the formats, the checks and the material to keep for handover.
Recipients can start with VERIFY.cmd on Windows: it asks for the original ZIP and independently obtained key fingerprint, displays an explained result, and saves a separate verification transcript. See verification launchers and the portable runtime for setup and trust limits.
On this page
- What is signed
- Comparing chat exports
- Investigation handoff
- Handover extract
- Readable reports
- Event canonicalization
- Actor semantics
- Coverage: continuity, gaps and unobserved IDs
- Producer
- People profiles
- Independent witness
- Manifest and checkpoints
- Verification scope
- Attachments
- Durable collection and process receipts (0.2)
- RFC 3161 preparation and response verification (0.2)
- Optional records in evidence mode: drand and Telegram devices
What is signed#
| Material | Protection | What to retain |
|---|---|---|
| Every journal observation, including operational events | SHA-256 chain and an Ed25519 signature per event | Original events.jsonl, the trusted key fingerprint, and a retained checkpoint |
| Evidence ZIP contents | manifest.sig signs the canonical manifest, which lists hashes of the content files |
The complete ZIP, including its manifest and signature |
| Preserved attachments | SHA-256 and byte count in a signed media.saved event; file hash in the signed ZIP manifest |
The original bytes inside the verified ZIP |
| Checkpoint | Ed25519 signature over journal length, head hash, public key, and creation time | An independent copy retained before a disputed change |
| Run receipt | Signed record of the collector version, source-file hashes and start settings, also included in process.started |
The receipt, associated journal and the environment evidence for the selected verification mode |
Readable reports: report.html and its parts, report.json, report.pdf, chat.pdf |
An Ed25519 seal per file over its content; the PDF also carries a standard PDF signature (see Readable reports) | The file as received and the trusted key fingerprint; the ZIP it describes |
| Standalone CSV | No standalone cryptographic signature; event hashes alone are insufficient | Use the exact copy inside the verified ZIP for integrity checking |
| Screenshots, printouts, or PDF produced by a browser | No TgWitness signature on the derivative | Keep the original verified package and document how the derivative was made |
The collector verifies journal signatures before generating every export format. Readable HTML and PDF reports carry their own seals; standalone CSV is checked as part of a signed ZIP. Keep the ZIP to retain the attachment bytes and manifest, and a separate checkpoint to check the journal against an earlier boundary.
Formats and verification paths#
The acquisition mode and the output format answer different questions. The mode supplies collection and environment evidence; each format preserves or presents part of that record with the checks below.
| Output | Verification and use |
|---|---|
| Evidence ZIP | Canonical events, signed manifest, coverage, custody entries, attachments and available external receipts; check the archive and its selected acquisition mode. |
| ASiC-E container | The evidence ZIP as an ETSI ASiC-E container (EN 319 162-1) with a mimetype entry and META-INF/ASiCManifest.xml, CAdES-signed with the workspace's own certificate at level B-B, or B-T when timestamping is on. Validators such as EU DSS check format and integrity and, as the certificate is self-issued, report no trust anchor. EU DSS 6.3 with default settings refuses a container of more than 1000 files ("Too many files detected"). verify.py checks the Ed25519 manifest and every listed file, the SHA-256 values in META-INF/ASiCManifest.xml and in an added ASiCManifestNNN.xml or ASiCEvidenceRecordManifest.xml, and fails on a META-INF/ entry none of them covers. It does not check the CAdES signatures and says so. |
| HTML and JSON reports | Individually sealed views with source references, also listed in the ZIP manifest. Their recorded counts summarize journal event kinds. |
| PDF reports | Ed25519 seal plus a PAdES baseline PDF signature over the byte range: B-B, or B-T with a signature time stamp when timestamping is on. The TgWitness verifier uses the trusted Ed25519 key; a viewer's certificate-trust display is a separate check. |
| CSV | A spreadsheet view covered by the ZIP manifest. Formula escaping protects spreadsheet use; original signed text remains in the journal. |
| JSONL | Signed event records, including attachment references. The evidence ZIP additionally carries the preserved attachment bytes. |
| Chat export and Desktop-compatible views | History acquisition and available admin-log records, with the requested rendering and signed archive. Live monitoring's saved versions are a separate acquisition path. |
| Media and hash-only records | Saved bytes are checked against their SHA-256 and message reference. Hash-only acquisition preserves the available hash metadata for later comparison with file bytes. |
| STIX/MISP and people profiles | Source-linked extracted observations, account IDs and analytical matches. Profile signatures and record hashes can be checked against the original evidence; avatar-cache provenance is labeled separately. |
| Handover extract | Signed disclosure rules, unchanged records and marked minimized records retaining original hashes/signatures. Use the retained original for a comparison requiring withheld fields. |
| Witness and time receipts | Earlier journal boundaries, continuity and the individual verified time claims. They accompany the acquisition and archive checks. |
| Password-protected delivery | Protects the enclosed package during transfer. .tgwpw uses AES-GCM authenticated encryption, including an authenticated final record; the enclosed journal keeps its signatures and acquisition receipts. |
A printout or screen capture is a presentation of the signed material. Its report ID, key fingerprint and QR reference help locate the original file for verification. Custody declarations record the supplied examiner and transfer information; verifier results and acquisition receipts are retained as separate evidence.
External signatures#
A signature can also come from a key TgWitness never holds, such as an investigator's
qualified electronic signature or an organisation's seal. On Exports, External
signature on a prepared export without a password hands out the bytes to sign: a new
META-INF/ASiCManifestNNN.xml listing every file with its SHA-256 for an ASiC-E
container, or the export's manifest.json for a ZIP. The signer returns a CMS (CAdES)
.p7s, detached or with the content embedded.
TgWitness checks that the signature covers exactly those bytes and verifies with the signer's certificate (RSA PKCS#1 v1.5, RSASSA-PSS, ECDSA, Ed25519, Ed448). The chain is checked only against root certificates the operator supplies; revocation, trusted lists and qualified status are not checked. The panel shows one state per signature: waiting for a signature, attached and not checked, verified, algorithm not supported, signature invalid, signed bytes do not match, or certificate not chained to a supplied root. Changing the export after the bytes were handed out sets all its signatures to "signed bytes do not match".
Download with signatures adds the signatures and their manifests under META-INF
in an ASiC-E container. For a ZIP, it puts the unchanged ZIP, the .p7s files and
SIGNATURES.txt into an outer ZIP. Invalid signatures and signatures over other bytes
are left out. A signature with an algorithm TgWitness cannot check is included; the
panel shows its state, as does SIGNATURES.txt for a ZIP.
Signed chat images#
Download signed ZIP in the image preview saves PNG pages, pages.sig.json and
README.txt. Each page ends with the journal record numbers it shows, the chat, the
render time, the workspace key fingerprint and the command that checks it. The panel
sends only each page's SHA-256 and record numbers; the server confirms that the records
belong to the chat, signs the statement (tgwitness-image-attestation-v1) with the
workspace key and journals the signing as export.image_attested.
python verify.py page-01.png page-02.png pages.sig.json
python verify.py page-*.png pages.sig.json --fingerprint TRUSTED_SHA256 --evidence evidence.zip
The verifier checks the signature, matches every PNG to a signed page and reports the
key fingerprint. --fingerprint compares the signer with a fingerprint obtained from the
sender independently. --evidence reads a signed evidence ZIP of the same workspace and
requires every record of the images to be present with the same hash. A changed pixel,
a changed statement or another key fails the check. The images show saved records in
TgWitness's own layout; they do not show what Telegram displayed to anyone.
Comparing chat exports#
Verify and compare two signed chat-export ZIPs with independently retained signer fingerprints:
python -m tgwitness.verify first.zip --compare second.zip \
--fingerprint FIRST_TRUSTED_KEY_SHA256 --compare-fingerprint SECOND_TRUSTED_KEY_SHA256
--require and --require-tier are refused together with --compare; check the required
profile of each archive with its own verification.
When both archives record the same numeric account and chat IDs, records are paired
by message ID. Unchanged means equality of the complete saved JSON record:
full text, author, dates, reply target, nested metadata and unknown fields are all
included. JSON object key order does not matter; absent fields, nulls, value types
and array order do. The 300-character preview is only for display. Changed entries
name the differing top-level changed_fields, including changes invisible in that preview.
Duplicate message IDs are rejected instead of overwriting one another during matching.
A difference can be a changed display name, view count, collection annotation or other observation metadata. Telegram edits appear as their own edit events, and each archive's verification shows whether that archive is intact. Unparsed records remain in the comparison and are compared by their saved representation.
For different or missing account/chat identities, the tool finds candidate
correspondences using sender, complete text, file hash, media type and a five-second
time tolerance, and reports them as Matched rather than Unchanged. Unparsed
records remain unmatched. Differences in paired records are listed in changed,
including in content mode. With --json, matched counts candidate pairs and
unchanged counts pairs whose complete saved records are equal. The
existing changed_fields and integer unchanged output remain compatible with
earlier comparison results. Archive format and signature verification are unchanged.
Investigation handoff#
- Record the case reference, operator, numeric Telegram account ID, selected sources, collection policy, and collection period in your case notes. TgWitness preserves observations and supports source-linked notes and collections in Case Board. Keep transfer and custody records with your case materials. Check the intended collection setup with the live acceptance procedure.
- Retain the workspace's public-key fingerprint independently before relying on its exports. Keep evidence mode on (the default) so checkpoints receive RFC 3161 and OpenTimestamps receipts. Save signed checkpoints outside the collector during collection. Record interruptions and the limits of the account's visibility.
- Export a signed ZIP and retain the signed run receipt. Use a checkpoint at or before the exported journal boundary. A later checkpoint can correctly reject an earlier export as too short. Exports include the full workspace journal, regardless of panel filters; review the material before sharing it.
-
Have the recipient verify the ZIP with a trusted copy of the verifier, the independently supplied fingerprint and the timestamp authority's root certificate obtained separately. From a trusted checkout with its Python environment active:
python -m tgwitness.verify evidence.zip --fingerprint TRUSTED_PUBLIC_KEY_SHA256 --tsa-ca TSA-ROOT.pem --checkpoint retained-checkpoint.json --require evidenceThe fingerprint and a checked timestamp of the last record meet the minimum for evidence;
--require evidenceexits with code 2 otherwise. The checkpoint is a supporting check, because it is signed with the collector key. Successful output reportskey_pinned: trueandcheckpoint_checked: truewhen both inputs are supplied and accepted. Preserve the verification result.For a handover requiring the final exported record to be witnessed, use `--witness witness.zip --witness-fingerprint TRUSTED_WITNESS_SHA256 --require-witness`. This refuses an export with an unwitnessed tail. Add `--channel https://t.me/s/WITNESS_CHANNEL` to read the dates Telegram set on the witness posts as external time. See the [witness handover procedure](WITNESS.md#require-a-witnessed-export-boundary).- Record the archive's SHA-256, export boundary, transfer date, sender, and
recipient in your custody record. Keep the original package intact and work
from copies. Share evidence files rather than the application's private data
directory, which also contains account sessions and signing secrets.
For transfer, choose a password-protected AES-256 ZIP or the stronger
.tgwpwcontainer. ZIP uses WinZip's low-cost password derivation; use a long random passphrase..tgwpwuses scrypt and AES-256-GCM and opens with the standalone verifier'sunseal-passwordcommand. The password is not stored and only protects confidentiality; the recipient decrypts the archive and verifies the signed export inside, which is unchanged. - To timestamp a checkpoint outside evidence mode, follow the RFC 3161 procedure and retain the request, checkpoint, trusted CA information, and verified authority response. Preparing a request alone does not obtain a timestamp.
- Record the archive's SHA-256, export boundary, transfer date, sender, and
recipient in your custody record. Keep the original package intact and work
from copies. Share evidence files rather than the application's private data
directory, which also contains account sessions and signing secrets.
For transfer, choose a password-protected AES-256 ZIP or the stronger
For .tgwpw, use an independently obtained verifier and choose a new output file
with the original extension: python verify.py unseal-password export.tgwpw --out evidence.zip.
The command prompts for the password; --password-stdin reads one line for automation.
It never overwrites an existing file and publishes plaintext only after all records
authenticate. Run normal signature verification on the decrypted file afterwards.
The container uses scrypt (N=131072, r=8, p=1, 16-byte salt; about 128 MiB RAM)
and AES-256-GCM with 1 MiB records and an authenticated final record. An encrypted
metadata record stores the inner filename, so downloaded containers can be renamed.
Successful verification establishes integrity relative to the trusted collector key and retained boundary. See verification scope for the trust assumptions and validation results for the checks performed.
Handover extract#
A signed ZIP carries the whole workspace journal. When a court, a lawyer or an abuse desk needs
only some chats, a period or certain people, Exports → Handover extract prepares a minimised
copy (tgwitness-handover-v1) according to the selected disclosure rules.
The operator states the purpose and chooses the chats, an optional period (UTC), the people the
extract is about, what happens to everyone else (shown, replaced by pseudonyms P01, P02… or left
out), which message texts stay, which attachments and profile photos are included, and whether
phone numbers and e-mail addresses in texts are masked. The purpose and these rules are in the
signed manifest and in the report; the journal records handover.exported with the access that
prepared it and the file's SHA-256, not the contents.
verify.py checks an extract in two ways. A record shown unchanged is verified in full: its
content against its hash, its Ed25519 signature and its link to an included predecessor. A
minimised record keeps the original hash and signature, so the signature still verifies, but the
withheld fields cannot be recomputed from it; the record names what was withheld and the report
marks it. Account-wide service records (starts and stops, coverage gaps, connection, network and storage notices,
scope and settings changes) keep only the fields listed for their kind: chat lists in them are cut to the chosen
chats and their totals recounted, and a live-probe gap in a chat outside the selection loses that chat, its message
numbers and the witness account; in a chosen probe chat the witness account is replaced by its pseudonym unless
everyone is shown or it is one of the chosen people. The manifest names the journal length and head with the collector's signature over that
head, and counts the records left out; coverage.json describes the chosen chats. New extracts also
carry proofs.jsonl: for every included record and for the journal head, the Merkle path from the
record's original hash to the journal root named in the signed manifest. verify.py checks each
path, so every record is shown to belong to the same journal of that length and head, without the
full journal; an extract of 100 messages checks in about a second whatever the journal size.
--range=CHAT:FROM-TO additionally confirms that messages FROM to TO of a chat are in the extract
and reports how many records it checked for them. Names inside file
names are not detected. Review the final files before sharing: free text, file names and selected
attachments can still identify people. Keep the full signed ZIP: the extract is a disclosure, not a replacement.
Readable reports#
Signed evidence, handover and chat ZIPs carry readable HTML and JSON reports, plus
PDF when the required fonts are available, in the selected report language. Each
report is sealed with the workspace's Ed25519 key and can be verified separately:
python -m tgwitness.verify FILE --fingerprint KEY [--evidence ZIP].
report.html/chat.html: the seal statement (tgwitness-report-seal-v1) closes the file and signs the SHA-256 of every byte before it. Long journals and chats are split into parts of a configurable size (Report settings, 500 to 100,000 records; 5,000 by default):records/records-0001.htmlormessages/messages-0001.html, each sealed with its number, range and the total, and listed with its SHA-256 in the signed manifest. Runs of collector heartbeats are shown as one line unless Report settings list them one by one.report.json(tgwitness-report-json-v1, keysformat,report,seal): the seal signs the SHA-256 of the canonical JSON ofreport, so the facts can be read by case systems and scripts and a selection for data protection can be made from them while the signed file stays whole.report.pdf/chat.pdf: a formal document for printing and filing, signed twice over the same bytes, the whole file except the signature value (/ByteRange). The standard PDF signature is PAdES baseline (ETSI EN 319 142-1,/SubFilter /ETSI.CAdES.detached: CMS with SHA-256 and ECDSA P-256, signing-certificate-v2, no CMS signing time; the claimed time is/M) at level B-B, or B-T with an RFC 3161 signature time stamp in the CMS when timestamping is on and a timestamp authority answers over the route for requests outside Telegram. It uses a self-issued document-signing certificate kept in the workspace vault; its subject serial number is the Ed25519 key fingerprint. The Ed25519 seal travels inside the CMS as the unsigned attribute2.25.240684792623320047764573196045913242332and names the certificate's SHA-256 with"content": "pdf-byte-range", so the Ed25519 key vouches for the certificate. The certificate is not qualified: a PDF reader shows the signature as valid and the signer as unknown or untrusted until the certificate is trusted; compare the Ed25519 fingerprint instead. Chinese, Japanese and Korean PDFs need a font on the server (or inTGWITNESS_FONT_DIR); without one the ZIP carries the HTML and JSON reports only.report.en.html,report.en.pdf/chat.en.html,chat.en.pdf: the English original of the same report when the report language is not English, sealed and signed in the same way and named underreport.originalin the signed manifest. The report in the selected language opens with a recommendation to file the English original with a certified or sworn translation; see Translating reports for court.
In a channel or supergroup Telegram numbers messages 1, 2, 3… in order. A chat export lists the
first and last number, how many are present and every run of absent numbers in
message-ids.json, the manifest and the chat.json header, and marks each gap where it falls in
the transcript. verify.py recounts them from chat.json. An absent number is a message Telegram
did not return (deleted before the export, or not visible to the account); in private chats and
basic groups numbers are shared by all of the account's chats and gaps are not counted.
After reading the history, the export asks Telegram for every absent number again, by number
(channels.getMessages, up to 10,000 numbers including the 1,000 below the first message, spread evenly over all gaps when there are more). The result is in message-ids.json and the report.
An empty answer records that the number is unavailable to this account at recheck time;
it leaves the cause unspecified. A message returned on recheck is added to the export
and marked found_on_recheck.
When the observing workspace saw messages of the chat deleted, missing on recheck or edited, the
chat export adds journal-changes.jsonl: those journal records, every saved version and the notice,
each with the hash and Ed25519 signature it received in the journal. verify.py recomputes each
record's hash, checks its signature against the export key and compares the count with the signed
manifest; the evidence export holds the complete hash chain. The report lists these messages under
Deletions and earlier versions.
Every report opens with In brief: one paragraph, then what the material shows and what the record includes. The page's own seal stamp turns amber when the browser has checked the seal's signature, not the page: a browser does not give a page its own bytes. It turns green only when the reader drops the file into the check at the end of the page and every byte matches, and only if the page shown is that file; otherwise it turns red.
Each report names the program exactly: the git commit when the collector runs from a checkout or
the installer sets TGWITNESS_COMMIT, and the SHA-256 of its source files (source_tree_sha256,
the canonical JSON of path → SHA-256 of every .py, .js, .css, .html and .svg file in the
package), which a checkout of that commit reproduces unless files were changed. The Telegram
client is named with its library, API layer and data centre. When observation starts and when a chat
export begins and ends, the collector asks Telegram for its time (updates.getState, whole
seconds) and records Telegram's time minus the collector's clock, with the uncertainty from the
round trip; the reports show these measurements under Chain of custody. A chat export also records
when it read the history, apart from the dates of the messages.
Offline report viewer and archive guide#
Extract the complete ZIP before opening chat.html or report.html. The viewer provides search,
filters, participants, indicators, record details and JSON/CSV selections without a server. Keep
viewer/ and media/ next to the report. Selections are derivatives: use verify.py SELECTION.json
--evidence ARCHIVE.zip to compare them with the signed archive.
The verifier checks the report ID, signing key, archive boundary and every selected item; edited,
missing and duplicate items fail. Selection notes and creation time remain unsigned metadata.
Message-number gaps are shown only for a complete, unfiltered ascending chat feed. Hiding a category or failing to load a data chunk must not turn an omitted row into evidence of a missing message. Search highlights operate on plain text before HTML escaping, preserving literal markup.
The browser checks manifest signatures, the report ID and key, and all listed file hashes. It rejects ambiguous or malformed ZIP structures, duplicate names and unsafe paths, and caps files at 256 MiB and declared total contents at 4 GiB. Use the standalone verifier for larger archives. This browser check complements the verifier's checks of journal chains and data semantics.
README.txt contains a start guide, an aligned file inventory, verification instructions and data
format notes in the report language, followed by a complete English guide. SHA256SUMS covers the
files listed within it, excluding itself, manifest.json and manifest.sig; the signed manifest
also covers SHA256SUMS. Keep the original ZIP unchanged and save working files outside the
extracted folder. PDF reports include section bookmarks and case/report identification on later pages.
The chat at export time#
A chat export records what Telegram said about the chat when the export began: Telegram's own
labels (scam, fake, restricted with its reasons, verified), usernames, description, member
and admin counts, the linked discussion, content protection, whether new members see earlier
messages and from which message on this account sees the history (available_min_id), the date
of message 1 when it is the chat's creation, and the SHA-256 of the chat photo (saved in media/).
It records the exporting account's place in the chat: role, join date, who invited it and, for an
admin, its rights. A request Telegram refuses is named instead.
When the exporting account is an admin, the export reads the chat's admin log (Telegram keeps about
48 hours) into admin-log.json: deletions and edits with the supplied content,
acting account and source action date. These entries complement the live journal's
captured versions and deletion reception records.
Indicators#
The reports list, and the archive carries as indicators.csv, indicators.stix.json (STIX 2.1)
and indicators.misp.json (MISP event), what an abuse desk can act on in the recorded messages:
links and domains (also hidden behind text, in buttons and in link previews), cryptocurrency
addresses, Telegram usernames and invite links, phone numbers, e-mail addresses and saved pictures.
Bitcoin, Litecoin, Dogecoin and TRON addresses are listed only when their base58 checksum holds,
segwit addresses when their bech32 or bech32m checksum holds and TON addresses when their CRC
holds; EVM and Solana addresses are marked as not checked. Pictures carry SHA-256 and a perceptual
hash (dHash, 64 bits) that recompressed or resized copies keep nearly unchanged. Reports write
indicators so that they do not open by accident (hxxps[://]example[.]com); the files keep the
values as they were. Every indicator is marked unknown and not for automatic detection (STIX
indicator_types: unknown, MISP to_ids: false, distribution to the own organisation): being
listed says that a message contained it, not that it is malicious. A link whose text shows a
different address than it opens is marked in the report.
The PDF reports end with an examiner's declaration to sign by hand, a checklist for a notary or court expert, and a QR code (also on the first page) with the report ID, the key fingerprint and the SHA-256 of the authoritative data, so that a printout leads back to its archive.
Event canonicalization#
The hash input consists of exactly these fields:
seq, observed_at, source_at, kind, chat_id, message_id, actor_id, payload, previous_hash
Serialize using Python-compatible JSON with UTF-8, sorted object keys, no ASCII escaping, no insignificant whitespace, and no NaN/infinity:
json.dumps(value, ensure_ascii=False, sort_keys=True,
separators=(",", ":"), allow_nan=False).encode("utf-8")
SHA-256 of those bytes becomes the event hash. The signature is Ed25519 over the 32 raw hash bytes, then base64 encoded. The first previous_hash is 64 zeroes. Sequence numbers start at 1 and increase by 1. All events, including operational events, share one chain. There is no duplicate-delivery suppression: repeated observations are distinct receipts, not a claim of distinct Telegram actions.
Raw Telegram dates are ISO strings; binary fields become objects containing
bytes_base64. Message text, entities, media descriptors, reply metadata, reactions,
and service actions are retained in raw message metadata when supplied. A live
message also keeps the Telegram update that delivered it in transport_update; when
that update carries the same message as raw, its message field is
{"same_as": "raw"} instead of a second copy.
observed_at is the collector's UTC time of writing the record; source_at is the date
supplied by that Telegram event. Records written while handling a live update add
payload.received_at, the UTC time the update reached the collector, and
payload.processing_delay_ms. Live edits retain the supplied edit date, history
snapshots retain the message date with a current observation time, and an ordinary
deletion notification records reception time with a null source date. Admin-log
entries retain their supplied action date separately. Reception order and source
event order are distinct timelines, with clock observations and external receipts
available for comparison.
Actor semantics#
Attribution follows the event source. message.new.actor_id and
message.edited.payload.sender_id retain the message sender. Ordinary
message.deleted notifications carry message IDs and have a null actor field;
available admin-log entries carry their supplied action, actor and date.
Membership service messages retain sender and action type, raw participant updates
retain the supplied actor_id, and reaction snapshots preserve their supplied
counts and visible identities. Read these records together with the captured
versions and panel interaction receipts.
Deletion notifications for private chats and ordinary groups contain only message IDs.
Those chats share one account-wide ID sequence, so an ID identifies a single message of
this account. When a message with that ID was saved earlier in this journal, the
deletion is recorded in that chat as message.deleted with payload.chat_resolution
naming the method. IDs that were never saved are kept as deletion.unscoped: an
actual deletion notification whose chat has not been correlated. This is distinct
from message.missing_on_recheck, which records an unavailable query result, and
from a gap in saved message IDs. Channels and supergroups number messages per chat and are
never matched this way. When the deleted message was sent by the observed account,
payload.deleted_message_was_outgoing is true; the deleter is still not supplied.
An unscoped notice keeps its own label because the matching chat may be outside the current observation scope or have no unique match. Recheck absence remains a separate observation from a deletion notification in report counts, filters and labels. A later recovery clears the current missing state while preserving the earlier unsuccessful check in the signed history; deletion notices stay a separate event type.
Multiple IDs resolved to the same chat from one notification are grouped as
deletion.batch, regardless of their count, with the message IDs exactly as Telegram
sent them and how many of them this account had sent. Telegram's notification lists
the messages; the chat's admin log names the acting administrator where the account
can read it. The link (message.deletion_attributed) is made whichever arrives first:
a poll that saw the admin log entry before the deletion notice is matched when the notice
is recorded.
Coverage: continuity, gaps and unobserved IDs#
Every signed ZIP carries coverage.json, the HTML report opens with the same summary, and
verify.py recomputes it from events.jsonl instead of trusting the file:
- Continuously observed from X to Y. A period starts with
observation.startedand ends at a pause, a stop, a lost Telegram connection, a sign-out, a process start without an orderly stop, or more than three minutes without any record while observing (heartbeats are written every minute, so silence means the process stopped, froze or the computer slept). When the heartbeat interval is changed in More tools → Parameters, each heartbeat records it and the allowed silence becomes three intervals, never less than three minutes. - Gaps list the time between periods with the reason. A gap still open at the last
record is marked
not_resumed_by_last_record. - Message IDs not observed. For channels and supergroups, which number messages per chat, the IDs missing between observed ones are listed as ranges. They are reported as not observed — deleted, never delivered, or outside the saved history — never as deleted. Private chats and ordinary groups share an account-wide sequence, so gaps inside one such chat mean nothing and are not listed there.
- Chat-level gap notices (for example Telegram asking for difference recovery in one channel) are counted as notes; they do not interrupt global coverage.
- Session records. Windows in which Telegram's update counter grew while no update
reached this session (
updates_diverted), this session left Telegram's session list while its connection kept working (session_revoked_externally), or a witness probe's answer arrived only from history (probe_ack_missed_live) are listed separately. The verifier also reports where the Telegram session key came from, other sessions signed in when observation started, sessions added during observation, Telegram security notices (777000), other sessions ended from the workspace, only-session periods, witness probe counts and phone call updates. See accounts. While strict chosen chats is on (scope.strictinobservation.started), the session list (except while this is the only session, or when Telegram devices is on), security notices and phone call updates are not collected, so their absence says nothing, and a deletion is matched to a session check only if one ran in the 10 minutes before it.
Update sequence (pts)#
Telegram numbers message-related updates with pts: one sequence for the account
(private chats and basic groups together) and one for each channel or supergroup. The
collector records each stretch it received without a hole as a coverage.sequence
record: the first and last pts, the number of updates of each type, and whether they
were pushed live or returned by getDifference or getChannelDifference. A break is a
coverage.gap record, and coverage.gap_closed names the pts from which the sequence
is whole again.
An unbroken stretch shows that every update Telegram numbered in that sequence between
its first and last pts reached this collector's Telegram client. It says nothing about
content Telegram never sent to this account, about the time before the first recorded
pts, or about stretches the collector did not write down. A pts advance that no
recorded stretch or difference covers is shown as a break.
GET /api/continuity answers for an interval (since, until, chat_id) whether each
sequence is unbroken and lists the breaks with their reasons. verify.py prints the same
from the records of an archive under Sequence continuity.
Missing message numbers (gap_summary)#
For a reader's guide to this section and to observation periods and gaps, see Coverage and missing material.
Preview. coverage.json → gap_summary measures the numbers Telegram assigned and this
collector never saw. Telegram numbers messages once per channel or supergroup, and once per
account across private chats, bots and ordinary groups. A number between two observed
messages is either observed or missing; a contiguous range is a positive statement that
every message numbered in it was observed. A gap names no actor and no reason.
| Field | Meaning |
|---|---|
status |
on, or off when turned off in More tools → Parameters → Gap analysis |
parameters |
The parameters that produced the result, so it can be repeated |
chats[] |
One entry per channel or supergroup, each numbered on its own |
account |
The account-wide sequence of private chats, bots and ordinary groups |
status (per sequence) |
applicable, or not_applicable with reason |
observed_from, observed_to, span |
First and last observed number and the size of the range |
observed, observed_without_content |
Observed numbers; those known only from a deletion or recheck record |
missing, density, gap_ranges, largest_gap |
Numbers never observed, their share of the range, how many runs, the longest run |
clusters[] |
Listed gaps: low, high, missing, and the neighbouring observed numbers after / before with their observation times |
service_estimate |
Only when enabled: how many missing numbers would be service messages at their observed share. Never subtracted from missing |
Validity is derived from the journal, never assumed:
- Channels and supergroups are measured per chat, also in an export of chosen chats.
Records chosen by sender make the measurement
not_applicable. - The account-wide sequence is measured only from the first to the last message that
arrived while whole-account collection was on and kept private chats, bots, ordinary
groups and the account's own messages, with no such chat excluded (
scope.changed). Numbers named bydeletion.unscopedcount as observed without content. An export or handover of chosen chats cannot measure it. If whole-account collection was switched off and on, a note says that numbers used meanwhile appear as gaps. - Service messages are journal records with their own numbers, so they close their gaps themselves; the optional estimate is only context.
verify.py recomputes gap_summary from events.jsonl with the parameters in the signed
coverage.json member (defaults for older archives) and
prints the account-wide line in its coverage summary. The archive's get_capture_status
(MCP and the command line) returns the same measurement for the chats an access may read;
the account-wide sequence only to access covering the whole workspace.
Repeated observations of one service message count once, and the account service estimate uses only numbers inside the measured range. An applied scope must explicitly preserve the account's own messages before account-wide measurement is enabled; the measurement starts from records that carry that information. The measured range covers running observation, and resuming it is noted. The live archive query has a time budget, including its database scan, and marks an unfinished measurement as partial.
Telegram documents the separate message ID sequences. These numbers describe observations; deletion notices, rechecks and the admin log record why a number is absent where Telegram reports it.
When Telegram stops accepting the account, the coverage.gap record that ends observation
carries cause (account_banned, account_frozen, account_deleted, session_duplicated,
session_revoked, session_expired, session_ended or not_authorized) and the Telegram
error; verify.py names the cause where the period ends.
Coverage combines recorded observation periods, interruptions and message outcomes. Assess it together with the selected chats, period and attachment policy; recheck results and recorded gaps show how completely the account's updates were observed.
Producer#
The signed manifest of evidence ZIPs, chat exports, witness journals and the statement of
people-profile files contain producer: software, version, project (PhishDestroy),
homepage and source repository. The HTML report and verifier display this signed
producer record. Source-file hashes identify the recorded source tree for comparison
with a trusted checkout. Execution provenance is checked separately by
GitHub acquisition attestation or
Intel TDX measurements, where enabled. Archives made before
the producer field existed remain supported and are identified as legacy records.
Each observation.started record also names the Telegram client that observed: its api_id
(never the hash), whether that is a built-in public pair or the operator's own application,
the client description sent in Telegram's connection request, and the kind of connection
route with the IP mode (no proxy address or secret). The report and custody.json list every
distinct client and route with when they were recorded, and the times no listed proxy answered
and Telegram saw the server's address. Journals recorded before this say so.
People profiles#
A profile file (tgwitness-dossier-v1, JSON) is built on request from records already in
the journal for one chat; nothing is fetched from Telegram and profile contents are never
written to the journal (switching profiles on and off is recorded as dossier.changed).
For every person with a saved message it lists name and username history, Telegram flags
(bot, scam, fake, premium, verified, restricted, deleted) as seen at saving time, profile
photo IDs, SHA-256 and perceptual hash (pHash, compatible with imagehash.phash) of the
avatar from the local avatar cache with similar avatars, activity (first and last message,
counts, edited and deleted shares, messages by UTC hour), who replies to whom, other chats
in this journal where the person wrote, and mentioned wallets (BTC, EVM, TRON, TON, LTC,
DOGE, XMR, SOL; Base58Check addresses are checksum-validated), phone numbers, usernames and
links, including links hidden behind text.
Every fact lists the journal records (seq) it comes from, and record_hashes holds the
hash of each referenced record. The statement is signed with the workspace key:
python verify.py tgwitness-dossier-CHAT.json --fingerprint TRUSTED_SHA256 --evidence tgwitness-evidence.zip
checks the signature, verifies the evidence export itself (signature, hash chain and files) and that every referenced record exists unchanged in that export of the same workspace. Avatar hashes are labeled as coming from the local cache (not journal records). Mentions are pattern matches and leads to check. Profiles are switched on per chat, can be exported as an AES-256 ZIP with a password, and are deleted when switched off or when the chat is removed from sources.
Independent witness#
A witness journal (tgwitness-witness-v1) and its channel posts are checked against an
evidence export with verify.py --witness … --channel …; see independent witness.
With a public https://t.me/s/… or https://telegram.me/s/… address the verifier reads
each post's date from Telegram, and the earliest such date of a post at the export head
is external time for the last record. Dates from any other source are supplied metadata.
Manifest and checkpoints#
manifest.json includes the format, export time, public key, fingerprint, journal
length, head hash, scope, producer, limitations, and SHA-256 of every content member other
than manifest.json and manifest.sig themselves.
manifest.sig is the base64 Ed25519 signature over canonical manifest JSON.
The verifier rejects unexpected/missing members, duplicate names, corrupt files,
broken sequence/chain, invalid signatures, and mismatch with a provided checkpoint.
It never extracts archive paths. It limits total declared uncompressed size to 4 GiB;
--max-gib N allows larger archives made with a raised More tools → Parameters limit.
A large archive is checked by several processes at once: members are hashed in parallel,
and after the first 5,000 records the content hash and signature of each record are checked
by worker processes while the main process follows the chain, the coverage and the bindings
in order. --jobs N sets the number of processes; the default auto uses one per CPU, at
most 16, and --jobs 1 keeps everything in one process. The answer is the same either way,
and a change is refused with the same message. Hashes at the positions named by retained
checkpoints and timestamp anchors are kept during that single pass, so each anchor is
compared without reading the journal again. On a 32-thread computer a 10.8 GB archive with
400,000 records took 58.9 s in one process, 15.2 s with 4 and 8.4 s with 16; one pass over the
records in order then sets the limit.
Run verification from your installed TgWitness version or a reviewed checkout. The copy included in an archive supports portable use; check that copy against your trusted installation before executing it.
A checkpoint signs a statement containing the public key, journal length, head
hash, and creation time. It also carries the newest drand round the workspace has
fetched (drand_anchor): the collector asks a drand relay through the workspace's
outside route before each periodic checkpoint, so Hide IP, proxies and a turned-off
outside route apply, and making the checkpoint itself never connects out. The verifier can check
that a later archive contains the same prefix. With --checkpoint and --check-drand
it confirms that round with the drand relays and reports that the checkpoint was signed
no earlier than the round's time; the round does not change the assurance tier. Retain
the checkpoint outside the collector, so later verification compares the archive with a
reference held separately from it. The collector key signs it, so it
binds the records up to it only if the recipient obtained it before the archive, through
another channel; on its own it does not meet the minimum for evidence.
Reading a verification result#
The verifier reports archive integrity, signer pinning and assurance checks
separately. A valid signature shows that the bytes have not changed since they were
signed. The operator gives the key fingerprint to the recipient through a separate
channel. Without --fingerprint, an intact archive passes its signature and format
checks with signer_pinned: false, and the final line starts with
EVIDENCE: minimum not met · missing: confirmed signer key.
For an automated local-archive policy that requires a pinned signer and the minimum for evidence:
python -m tgwitness.verify evidence.zip --strict --json --fingerprint TRUSTED_KEY_SHA256 --tsa-ca TSA-ROOT.pem --require evidence
Use a fingerprint retained through the recipient's trusted channel. A trusted
witness can also pin the collector through a consistent witnessed journal; supply
--witness, --witness-fingerprint and --require-witness. --strict exits with
status 2 for an unpinned signer; an unmet --require-tier or --require evidence also
exits with status 2. --require evidence needs --fingerprint and external time from a
third party covering the last record.
Read signer_pinned, requirements_met and the assurance results, not the exit
code alone. Sealed acquisition instead uses its
attestation verifier and approved policy to authenticate the acquisition digest.
Verification scope#
Verification checks the archive and the collection mode used to produce it. Choose the mode whose trust boundary matches the case, then retain its verification inputs.
| Collection mode | What the verifier checks | Verification inputs and trust boundary |
|---|---|---|
| Local workspace | Record signatures, hash chain, manifest and attachment bytes | Collector fingerprint retained by the recipient and external time from a third party: verified RFC 3161 or OpenTimestamps receipts, or witness posts read from t.me. Retained checkpoints and witness records are supporting checks |
| Local workspace with an independent witness | The archive checks plus agreement with an earlier journal prefix retained by the witness | Witness fingerprint and records; the custodian's key-control record shows who holds the witness key. With --channel https://t.me/s/…, the dates Telegram set on the posts give external time |
| GitHub Actions capture | GitHub attestation of the archive digest, approved workflow and collector commits, hosted runner, fresh session/key origin and internal archive integrity | Trusted verifier policy, caller repository and GitHub attestation bundle; collection runs under the pinned workflow |
| Cloud deployment | Provider lifecycle and access records, firewall and Cloudflare state, plus the collector's signed run record | Read-only queries to the provider and Cloudflare; availability of individual checks depends on the provider |
| Intel TDX confidential VM | Quote signature and platform status, binding to the collector statement, compose and OS measurements | Intel trust chain and expected deployment measurements; retain the results of every required TDX check |
In sealed acquisition, the approved collector receives data through an authenticated Telegram connection inside the verified environment. Attestation binds the archive to that execution, so verification covers acquisition as well as later file integrity. This relies on the approved code and the platform trust chain listed above. GitHub capture verification requires a session created inside the run and rejects imported-session captures.
The run receipt records the collector version, file hashes and startup settings. GitHub provenance and TDX measurements provide the environment checks; the validation record identifies tested configurations.
Where the messages come from#
Telegram delivers messages to every client, official apps included, inside an MTProto session. The session's authorization key is negotiated against Telegram's pinned server key, and every update arrives encrypted and integrity-checked under that key. The collector receives messages through the account's authenticated session and signs each observation into the journal as it arrives, with the chat, message and sender identifiers and the date Telegram set on each message. In GitHub Actions capture and Intel TDX deployments, attestation also binds that session and signing key to the approved collector execution.
The journal records where the authorization key came from. Signing in by phone or QR,
or an independent login from a session file, writes account.authorized with
key_origin: "created"; collecting on an imported .session, TData or JSON key writes
imported. An imported key also exists wherever it came from. Attested deployments
refuse imported keys.
The Telegram origin of a record rests on the account's authenticated connection, the
connection and capture records in the journal, captured MTProto frames matched to journal
entries (tgwitness/forensics/), the Telegram date of each
message and, for attested capture, the verified execution environment. Archive signatures
preserve that record for later checking. Retained checkpoints fix earlier journal
boundaries, coverage records show collection outcomes, and verified external timestamps
place the committed bytes in time.
For a local workspace, the recipient supplies trusted collector or witness inputs. For sealed acquisition, the trusted policy and attestation bind the archive digest to the approved collector execution. These are different verification paths; report the checks completed for the selected path.
Attachments#
Files are addressed by SHA-256 under media/. A media.saved event links a hash and byte length to a specific message event. Raw filenames are metadata, never local paths. Media bytes are downloaded asynchronously, so immediate deletion may prevent capture. Disabled collection, oversize/unknown-size files, download failures, and interrupted downloads are visible as outcomes. A process crash can leave unreferenced partial files; they are not included in exports.
The ZIP exporter verifies stored media against their names. JSONL, CSV, and HTML exports verify event signatures but do not carry media bytes. Derivative reports are conveniences; events.jsonl is the authoritative event representation.
A full chat export saves attachments within the workspace's attachment settings into
media/, named by SHA-256. Each message record in chat.json names its file (file,
file_sha256) or the reason it is absent (file_status), together with what the reader saw
around the text: links behind the text, forward origin, bot buttons, signature, views and
the auto-delete timer. verify.py checks that every named file is in the signed manifest
under that hash.
Durable collection and process receipts (0.2)#
A media job and its message event commit in one transaction. The job stores the original TL message descriptor; the signed observation binds its SHA-256, account, and size policy. Recovery verifies that binding before downloading. It never fetches the current message and silently substitutes a newer attachment. Interrupted jobs are retried, while permanent failure remains an explicit outcome.
Each workspace has its own journal and signing identity. A process.started event includes a run ID, local clocks, dependency versions, source-file hashes, initial account/scope, and capture settings. Heartbeats include the run ID, monotonic time, and queue state. The run receipt can also be downloaded as a separately signed statement. For verification of the execution environment, pair it with the GitHub attestation or TDX checks described in Verification scope.
Automatic checkpoints are retained locally on startup, every five minutes while observing (More tools → Parameters → Signed checkpoint every), and on orderly stop. Startup verification and export compare the journal against the latest retained local checkpoint. This can detect a database rollback when the checkpoint survives. Independent retention keeps that reference available outside the workspace; a verified external timestamp additionally anchors it in time.
After a restart the saved Telegram update position is resumed (catch_up_from in
observation.started) and missed updates are requested. The saved position covers only
updates whose handling has finished, so updates still waiting when the connection closed or
the process stopped are requested again. A periodic recheck records
message.recovered for missed messages and message.missing_on_recheck when Telegram no
longer returns a saved message; the latter is not a deletion notice and names no deleter or time.
Off-site copy and restore (S3)#
The off-site copy (Settings → Notifications and off-site copy → Off-site copy, or
More tools → Extras → Evidence & backups; off by default) uploads journal segments, preserved files, checkpoints
with their timestamps and finished chat exports to S3-compatible storage, encrypted with
AES-256-GCM before upload under a key kept in the workspace vault; Object Lock retention applies
when the bucket supports it. Without the downloaded key the copy cannot be read. Restore and verify
with python -m tgwitness.replica restore --key-file KEY.json --out DIR.
Restore requires an empty ordinary directory. Downloads and decrypted objects stay in private temporary storage until the entire journal and every retained checkpoint verify. Unsafe object paths, inconsistent segment ranges and journals shorter than a checkpoint are rejected; failed verification publishes no restored files. Retention checks compare the returned Object Lock mode and date with the deadline sent at upload (one second of rounding tolerance). An expired, invalid or shortened deadline does not count as verified. The status reports the sampled object whose retention was read back for that upload pass.
Missing or corrupt local media is reported as the pass's error and keeps the media cursor before it, so the file is tried again next pass; the files, checkpoints and exports after it are still copied. Restore checks all preserved-media references against decrypted hashes and recorded sizes. Identical overlapping journal segments from interrupted uploads are deduplicated; conflicting overlaps are rejected. Checkpoints created during an upload are deferred until their covered journal records have been copied, so a completed pass does not publish a checkpoint ahead of its journal.
Streaming export snapshots#
Streaming exports use a stable SQLite read snapshot. Its head may be older than the current live journal when download completes. A checkpoint created after that snapshot can correctly report that the archive is shorter; compare with a checkpoint at or before the exported prefix, not an arbitrary later checkpoint.
RFC 3161 preparation and response verification (0.2)#
Evidence mode sends only the SHA-256 of each signed checkpoint to the listed RFC 3161
authorities and OpenTimestamps calendars, over the workspace route and never over MTProxy.
Timestamps are on by default in every setup goal; Evidence for a case also records drand.
Answers are kept in checkpoints/anchors/, exported as .tsr and .ots files under anchors/,
and checked by verify.py (--tsa-ca checks the TSA signature; confirm OpenTimestamps proofs
with ots upgrade and ots verify).
An RFC 3161 authority that fails twice in a row waits before the next attempt: one interval, then
two, four and so on up to six hours, or as long as its Retry-After asks, up to a day. A pass that
finds only waiting authorities writes no record; otherwise anchor.completed lists them under
deferred with retry_at. Until they answer again, the panel shows timestamps as Degraded.
The panel prepares a request archive containing canonical checkpoint.json bytes, a SHA-256 message imprint and random nonce in timestamp.tsq, checksums, and instructions. No network request is made; the token the authority returns for this request is the timestamp.
python -m tgwitness.anchor verify checks the reply against the checkpoint
bytes and the original request without OpenSSL. A trusted CA file is required explicitly;
included certificates are not automatically trusted. Request checking is optional at
the CLI, so retain and supply --request to check the nonce. The result states whether
it was checked. The collector checkpoint signature and journal must still be verified
separately with the trusted collector fingerprint.
Verification checks the response signature, checkpoint bytes and, when supplied,
the original request under the specified CA trust. For time stamps obtained in evidence mode,
verify.py also checks the stored OCSP or CRL evidence
(signing certificate revocation).
See the procedure and validation results.
Optional records in evidence mode: drand and Telegram devices#
Two more records can run on the same passes as the timestamps. Both take effect only while
evidence mode is on. Evidence for a case turns drand on; otherwise both start off. Switch them
under More tools → Extras → Evidence & backups → More witnesses · optional,
or "drand": true and "devices": true in POST /api/evidence. One failing does not stop the
other or the timestamps; the panel shows the latest result of each under the form.
drand (beacon.drand). Each pass writes the newest round of drand quicknet, the public
randomness of the League of Entropy (a round every 3 seconds), into the journal: chain,
round, randomness, signature, round_time and the relay that answered. A verified
unpredictable round supplies a lower time reference for the subsequent hash-linked material.
A verified timestamp on a later checkpoint supplies an upper time reference. These checks
bound the linked material. The collector asks drand.cloudflare.com
first, then the relays of Protocol Labs, through the workspace route, one request per pass.
verify.py checks that each randomness is the SHA-256 of its signature and that the round
time is right, and reports the rounds, the longest stretch without one and how far behind
drand the collector's clock was. --check-drand
compares the rounds with a Cloudflare relay and a Protocol Labs relay, all of them or a random
sample of 100 in a long journal; a round that differs fails the verification.
Telegram devices (account.devices). Each pass reads the account's sessions with
account.getAuthorizations, the list Telegram shows in Settings → Devices, and records it:
in full when it changed since the previous pass, with the added and removed session
hashes, otherwise only its count and SHA-256. Device model, platform, app and version,
creation and last activity, country and region are kept; IP addresses are not, because
evidence exports leave your hands. The collector's own session is active all the time, so
only other sessions' activity counts as a change. verify.py reports how often the list
was recorded and each new and ended session. It reads the list only while observation runs.
What they show: drand places the records in order against public time, and the device list is Telegram's statement through the collector, signed by the collector like every other record.
Cloudflare Gateway log (cloudflare.gateway_dns). For a server that resolves through
Cloudflare Gateway (Gateway DNS), each
pass copies what Gateway logged since the previous copy: one record per window of at most three
hours with from, until, the location_id, the server's address when one is set, and the
queries as [at, name, type, rcode, decision, colo], also when there were none. Set it under
Cloudflare Gateway log: account, location, optional address and a read-only token (Account
Analytics Read; Zero Trust PII Read to keep one address of a shared location). The panel checks
them with one request before saving; the token stays encrypted and never enters the journal.
verify.py lists the windows, the names looked up most and any time no copy covers; a record
whose count does not match its queries fails. A window that holds more than one page of
queries in a single second keeps that page and says the rest is missing. The copy is
Cloudflare's answer through the collector, signed by the collector; within 24 hours anyone with
a read-only token can compare it with Cloudflare.