Authentication
Keyed integrity with HMAC-SHA256 and the tag of authenticated encryption — proving a file was written by someone holding the key.
What authentication answers#
"Did the person who wrote this file have the key?" That is a different question from integrity, and the only one that detects a deliberate edit.
Two ways to get it, and you usually get the second for free:
| Mechanism | How it is enabled |
|---|---|
| Keyed integrity | Envelope.IntegrityAlgorithm = SaveFileFormat.IntegrityHmacSha256 |
| Authenticated encryption | Security.EncryptionAlgorithm = SaveFileFormat.EncryptionAes256CbcHmacSha256 — an encrypted save is always authenticated |
The tag is verified before decryption#
An authenticated file carries a tag over the header, the metadata, the nonce and the ciphertext. That tag is checked before anything is decrypted, which means:
- a forged file never reaches the cipher, so it cannot be probed for padding behaviour;
- a tampered schema version, payload length or metadata block is caught while it is still bytes;
- a wrong key is reported as a wrong key, not as a corrupt file.
NF.PERSIST.SECURITY.AUTHENTICATION_FAILED
The save failed authentication: it was altered, or it was not written with the supplied key.
Nothing was read or decrypted.Two keys, two purposes#
Encryption and authentication keys are separate on purpose (SaveKeyPurpose.Encryption and SaveKeyPurpose.Authentication), so one compromise does not imply the other. The framework fetches keys per operation and clears its copies afterwards.
What authentication is not#
Next#
- Encryption — confidentiality, and why encrypt-then-MAC.
- Key providers — where keys come from.
- Security best practices — the decisions that actually matter.
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