Key providers
ISaveKeyProvider is the only supported way to supply encryption and authentication keys, and the framework never stores, derives or generates one.
The package holds no key#
public sealed class MyKeyProvider : ISaveKeyProvider
{
public bool TryGetKey(SaveKeyPurpose purpose, out byte[] key)
{
class="tok-com"> // 32 bytes for AES-256, 32 for HMAC-SHA256.
class="tok-com"> // Never log one, never embed one, never derive one from the other by hand.
return m_Keystore.TryGet(purpose, out key);
}
}Register it at initialization and the framework asks for a key per operation, then clears its own copy: NexusForgePersistence.Initialize(options, logger, migrations, keyProvider).
Where a key should come from#
| Source | Verdict |
|---|---|
| Platform keystore or secure storage | Good: the platform is designed for this |
| A sign-in exchange (token-derived key) | Good: the key never exists in the build |
| A server endpoint | Good, with the caveat that it needs connectivity — acceptable for a one-time fetch |
| A constant in your source | Not protection: the build is the vulnerability |
| An asset field, a settings value, a custom metadata entry | Never — the framework gives you no way to do it, on purpose |
Rotation without guessing#
Security.KeyId records which key wrote a save. It is not a secret; it is a label. Write with one, ship a provider that can supply the previous id, and rotation becomes a decision you can make per release rather than an incident.
For tests and tools#
InMemorySaveKeyProvider copies what you give it and wipes it on dispose; NullSaveKeyProvider refuses everything, which is what proves an unencrypted configuration path works without a key.
Next#
- Encryption — how the key is used.
- Authentication — the second key, and why it is separate.
- Security best practices — what to do when a key cannot be protected.
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