synology_apm_repo.sdk.format.crypto module

Chunk and key-material cryptography (FORMAT-SPEC.md: Key hierarchy).

Four independent AES schemes, never confused with each other:

  • Chunk pool (.buk): AES-256-CTR, key = vaultKey (the DEK), IV derived from each chunk’s ChunkAddress, never stored (FORMAT-SPEC.md: Chunk pool encryption).

  • Wrapped VaultKey: AES-256-GCM, key = userKey (the KEK), nonce = the first 12 ASCII bytes of userKeyID (FORMAT-SPEC.md: VaultKey custody). A wrong key/nonce pair fails the GCM tag, which doubles as the integrity check.

  • copy_meta_file’s aHlT envelope: AES-256-CTR with the vaultKey DEK and an IV stored in its own header (FORMAT-SPEC.md: File-level encryption).

  • db/copy_target_version.version_spec: AES-256-CTR with the same DEK and an IV derived from hex(MD5(version_uid)) (FORMAT-SPEC.md: copy_target_version.version_spec encryption).

Nothing here decides whether something is encrypted; callers decide by mode bit or magic.

synology_apm_repo.sdk.format.crypto.NO_ENCRYPTION_USER_KEY_ID = 'NoEncryption'

user_key_id value marking a vault that was never encrypted.

synology_apm_repo.sdk.format.crypto.chunk_iv(addr)

16-byte AES-CTR IV for one chunk: its own 64-bit ChunkAddress, big-endian, repeated twice (FORMAT-SPEC.md: Chunk pool encryption).

synology_apm_repo.sdk.format.crypto.build_aes_algorithm(vault_key)

Build one AES-256 key-schedule object from vault_key, for a caller decrypting many chunks with one key (the algorithm= of decrypt_chunk and ChunkDecryptor).

Nothing here caches it; the caller does, for the lifetime of whatever owns vault_key (Pool).

Raises:

KeyMaterialError – vault_key is not 32 bytes.

synology_apm_repo.sdk.format.crypto.decrypt_chunk(vault_key, addr, ciphertext, *, algorithm=None)

AES-256-CTR-decrypt one chunk’s ciphertext (no decompression; see compression). Many chunks decrypt cheaper through ChunkDecryptor.

Parameters:
  • vault_key (bytes) – The DEK; unused when algorithm is given.

  • addr (ChunkAddress) – The chunk’s address, which derives the IV.

  • ciphertext (bytes | memoryview) – bytes or a memoryview (not copied).

  • algorithm (AES | None) – The DEK’s prebuilt key schedule (build_aes_algorithm), not checked against vault_key.

Returns:

The plaintext (still compressed, if the chunk was).

Raises:

KeyMaterialError – vault_key is not 32 bytes and no algorithm was given.

Return type:

bytes

class synology_apm_repo.sdk.format.crypto.ChunkDecryptor(vault_key, *, algorithm=None)

Bases: object

decrypt_chunk for many chunks: one AES-256-CTR context, re-nonced with each chunk’s own IV. vault_key and algorithm are as decrypt_chunk’s. Not thread-safe: use one instance per thread.

Raises:

KeyMaterialError – vault_key is not 32 bytes and no algorithm was given.

decrypt(address, ciphertext)

One chunk’s ciphertext decrypted, as decrypt_chunk would. address is the chunk’s raw uint64 form (ChunkAddress.to_int()).

synology_apm_repo.sdk.format.crypto.parse_key_string(key_string)

Split an administrator-provided key string "<userKeyID>@<base64(userKey)>" (FORMAT-SPEC.md: Key hierarchy) into (user_key_id, user_key). Splits on the last @ and validates user_key_id is 12 ASCII characters (the GCM nonce’s 12 bytes) without a path separator and user_key decodes to 32 bytes. "NoEncryption" is not special-cased (that is KeyMaterial’s decision).

Raises:

KeyMaterialError – The string is malformed.

synology_apm_repo.sdk.format.crypto.unwrap_vault_key(user_key_id, user_key, wrapped)

AES-256-GCM-unwrap a 48-byte wrapped VaultKey (ciphertext(32) || tag(16)) using userKey and a nonce built from userKeyID’s first 12 ASCII bytes (FORMAT-SPEC.md: VaultKey custody).

A successful unwrap proves the (userKeyID, userKey) pair is correct for the repository’s data too, since the DEK never changes after initialization.

Raises:
synology_apm_repo.sdk.format.crypto.is_ahlt(head)

Whether head opens with the aHlT envelope’s magic — only its first 4 bytes are inspected.

synology_apm_repo.sdk.format.crypto.ahlt_decrypt(data, vault_key)

Decrypt a copy_meta_file entry’s aHlT-enveloped bytes: 64-byte header (the generic IndexHeader shell, IV at [8,24)) followed by AES-256-CTR ciphertext from byte 64 onward (FORMAT-SPEC.md: File-level encryption). The IV is stored in the header, not derived as in chunk_iv.

Returns:

The plaintext body, header stripped.

Raises:
Return type:

bytes

synology_apm_repo.sdk.format.crypto.version_spec_iv(version_uid)

16-byte AES-CTR IV for one copy_target_version.version_spec: the first 16 ASCII bytes of the hex string hex(MD5(version_uid)), not the raw 16-byte digest (FORMAT-SPEC.md: copy_target_version.version_spec encryption).

synology_apm_repo.sdk.format.crypto.decrypt_version_spec(ciphertext_b64, version_uid, vault_key)

Decrypt one copy_target_version.version_spec column: AES-256-CTR, same DEK as chunk-pool/aHlT (vault_key), IV from version_spec_iv. The value is plain base64 with no magic to sniff, so the caller decides whether to call this (repo.vault_key is not None) (FORMAT-SPEC.md: copy_target_version.version_spec encryption).

Returns:

The decoded UTF-8 plaintext (a JSON string).

Raises:
Return type:

str