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: object

Result of KeyMaterial.verify. vault_key holds the resolved DEK only when gcm_ok and encryption is actually in use; it’s None both for an unencrypted repository and for a failed unwrap.

gcm_ok: bool
vault_key: bytes | None
property ok: bool
class synology_apm_repo.sdk.dedup.keys.KeyMaterial(user_key_id, user_key)

Bases: object

A parsed "<userKeyID>@<base64(userKey)>" key string.

user_key_id == "NoEncryption" (NO_ENCRYPTION_USER_KEY_ID) marks an unencrypted repository — no VaultKey exists to resolve.

user_key_id: str
user_key: bytes
classmethod from_key_string(key_string)

Parse key_string (see format.crypto.parse_key_string).

Raises:

KeyMaterialError – The string is malformed.

property is_no_encryption: bool
async resolve_vault_key(store, layout)

Fetch this repository’s wrapped VaultKey (from whichever of the two on-disk locations layout.kind implies) and AES-256-GCM unwrap it.

Returns:

The VaultKey, or None if no wrapped key is on record (the lookup row/file is absent).

Raises:
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:
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; its user_key_uuid is "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, or None if the record is entirely absent.

Raises:

DataCorruptError – The VAULT key database is unreadable.

Return type:

bool | None