Integrity
CRC32 and SHA-256, what a checksum actually proves, and why it is verified before anything is parsed.
What integrity answers#
"Was this file damaged by accident?" Nothing more. That sounds modest, and it is the most commonly misunderstood claim in a save system.
| Algorithm | Value | When to use |
|---|---|---|
| CRC32 | 1 | Fastest; good for detecting transport and storage damage |
| SHA-256 | 2 (default) | Strong accidental-damage detection at a small cost |
| HMAC-SHA256 | 3 | Keyed — this is authentication, not a checksum; see Authentication |
options.Envelope.IntegrityAlgorithm = SaveFileFormat.IntegritySha256;The value covers the header, the metadata block and the payload, so a tampered schema version or a corrupted metadata block is detected before anything is parsed or decrypted.
Verified before parsing, always#
An unverified file is never parsed. That ordering matters: a parser is the largest attack surface in a save system, so it must not see bytes the framework cannot vouch for.
A checksum is not a seal#
When it fails#
NF.PERSIST.ENVELOPE.INTEGRITY_MISMATCH means the file is damaged. The correct response is recovery — quarantine the damaged file, restore the newest valid backup — not a retry loop.
Next#
- Authentication — proving who wrote the file.
- Corruption handling — everything else that is refused.
- Configuration reference — the envelope settings.
Something wrong on this page? Every page here describes behaviour that is checked in the repository. If a page and the package disagree, the package wins.
Report a documentation problem · Frequently asked questions · Troubleshooting