synology_apm_repo.sdk.dedup.keys module¶
Key material: parsing an administrator-provided key string, and resolving the wrapped VaultKey from whichever of the two on-disk locations this repository’s layout uses.
“Is this key correct” is answered by ``KeyMaterial.verify`` alone, via
AES-256-GCM’s own authentication tag — never by also decrypting a real
chunk (see format.crypto.unwrap_vault_key; FORMAT-SPEC.md: VaultKey
custody). Per-chunk fingerprint verification is Pool’s
VerifyPolicy, not this module’s.
- class synology_apm_repo.sdk.dedup.keys.KeyVerification(gcm_ok, vault_key)¶
Bases:
objectResult of
KeyMaterial.verify.vault_keyholds the resolved DEK only whengcm_okand encryption is actually in use; it’sNoneboth for an unencrypted repository and for a failed unwrap.
- class synology_apm_repo.sdk.dedup.keys.KeyMaterial(user_key_id, user_key)¶
Bases:
objectA parsed
"<userKeyID>@<base64(userKey)>"key string.user_key_id == "NoEncryption"(NO_ENCRYPTION_USER_KEY_ID) marks an unencrypted repository — no VaultKey exists to resolve.- classmethod from_key_string(key_string)¶
Parse
key_string(seeformat.crypto.parse_key_string).- Raises:
KeyMaterialError – The string is malformed.
- async resolve_vault_key(store, layout)¶
Fetch this repository’s wrapped VaultKey (from whichever of the two on-disk locations
layout.kindimplies) and AES-256-GCM unwrap it.- Returns:
The VaultKey, or
Noneif no wrapped key is on record (the lookup row/file is absent).- Raises:
KeyMismatchError – A wrapped key was found but this
(userKeyID, userKey)pair does not open it.KeyMaterialError – The stored wrapped key has the wrong length.
DataCorruptError – The key database or file is unreadable.
- Return type:
bytes | None
- async verify(store, layout)¶
The whole answer to “is this key correct”; no per-chunk check follows. A wrong key is reported via the returned
KeyVerification, not raised. Reads only the wrapped-VaultKey record, never the Pool.- Raises:
KeyMaterialError – The stored wrapped key has the wrong length.
DataCorruptError – The key database or file is unreadable.
- async synology_apm_repo.sdk.dedup.keys.probe_encrypted(store, layout)¶
Whether this repository is vault-encrypted, read from its key record alone (no key, no bucket file, no Pool scan).
VAULT layout: the last-inserted row of
db/vault_encryption_key; itsuser_key_uuidis"NoEncryption"iff never encrypted, which cannot change after first initialization (FORMAT-SPEC.md: VaultKey custody). OBJECT_STORE layout: the object names under<key_root>/userKey/, with the same sentinel.- Returns:
True/False, orNoneif the record is entirely absent.- Raises:
DataCorruptError – The VAULT key database is unreadable.
- Return type:
bool | None