On this page· 3
Integrity
- file format 6
- Rust SDK 1.0 preview
Plain words: the seal
Every pack carries a SHA-256 digest of its contents. SHA-256 is a public hash function, defined in FIPS 180-4, that turns any sequence of bytes into a 32-byte value. The same bytes always give the same value.
The digest is SHA-256 over the file's bytes from offset 257 up to, not including, offset L − 96. In order, that is the record lines and, when the pack has an appendix, the marker line, the padding and the appendix.
The header line and the footer are outside it. A writer can therefore fill in the header line after the rest of the file is written without changing the digest.
The digest is stored twice: raw in footer bytes 64 to 95, and as 64 lowercase hexadecimal digits in a final header line. A reader compares the digest it computes with the footer's, and the header line's with the footer's.
An appendix also carries its own CRC32C checksums, which are checked in addition to the digest. CRC32C is a 32-bit checksum, the Castagnoli CRC.
- Who wrote the pack. Revision 6.0 defines no signature.
- Whether a statement in it is true. The digest covers bytes, not meaning.
- Whether the pack is the newest one. Two different packs each carry a valid digest of their own bytes.
- Whether its records can be read. A reader still checks every line after the digest matches. Verify
| What changed | Error kind |
|---|---|
| a byte of a record line, the marker line, the padding or the appendix | checksum_mismatch |
| the record count, the appendix offset or size, or the digest, in a final header line or in the footer, so the two disagree | header_footer_mismatch |
the footer's text_section_size, so the layout no longer adds up | invalid_footer |
A change inside the record text can also break a JSON line. Opening still reports checksum_mismatch, because the digest step comes before the body step.