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’sChunkAddress, never stored (FORMAT-SPEC.md: Chunk pool encryption).Wrapped VaultKey: AES-256-GCM, key =
userKey(the KEK), nonce = the first 12 ASCII bytes ofuserKeyID(FORMAT-SPEC.md: VaultKey custody). A wrong key/nonce pair fails the GCM tag, which doubles as the integrity check.copy_meta_file’saHlTenvelope: AES-256-CTR with thevaultKeyDEK 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 fromhex(MD5(version_uid))(FORMAT-SPEC.md:copy_target_version.version_specencryption).
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_idvalue 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 (thealgorithm=ofdecrypt_chunkandChunkDecryptor).Nothing here caches it; the caller does, for the lifetime of whatever owns
vault_key(Pool).- Raises:
KeyMaterialError –
vault_keyis 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 throughChunkDecryptor.- Parameters:
vault_key (bytes) – The DEK; unused when
algorithmis given.addr (ChunkAddress) – The chunk’s address, which derives the IV.
ciphertext (bytes | memoryview) –
bytesor amemoryview(not copied).algorithm (AES | None) – The DEK’s prebuilt key schedule (
build_aes_algorithm), not checked againstvault_key.
- Returns:
The plaintext (still compressed, if the chunk was).
- Raises:
KeyMaterialError –
vault_keyis not 32 bytes and noalgorithmwas given.- Return type:
- class synology_apm_repo.sdk.format.crypto.ChunkDecryptor(vault_key, *, algorithm=None)¶
Bases:
objectdecrypt_chunkfor many chunks: one AES-256-CTR context, re-nonced with each chunk’s own IV.vault_keyandalgorithmare asdecrypt_chunk’s. Not thread-safe: use one instance per thread.- Raises:
KeyMaterialError –
vault_keyis not 32 bytes and noalgorithmwas given.
- decrypt(address, ciphertext)¶
One chunk’s ciphertext decrypted, as
decrypt_chunkwould.addressis the chunk’s rawuint64form (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 validatesuser_key_idis 12 ASCII characters (the GCM nonce’s 12 bytes) without a path separator anduser_keydecodes to 32 bytes."NoEncryption"is not special-cased (that isKeyMaterial’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)) usinguserKeyand a nonce built fromuserKeyID’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:
KeyMaterialError – An argument has the wrong length, or
user_key_idis not ASCII.KeyMismatchError – The GCM tag check fails (wrong key pair).
- synology_apm_repo.sdk.format.crypto.is_ahlt(head)¶
Whether
headopens with theaHlTenvelope’s magic — only its first 4 bytes are inspected.
- synology_apm_repo.sdk.format.crypto.ahlt_decrypt(data, vault_key)¶
Decrypt a
copy_meta_fileentry’saHlT-enveloped bytes: 64-byte header (the genericIndexHeadershell, 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 inchunk_iv.- Returns:
The plaintext body, header stripped.
- Raises:
FormatError –
datais shorter than the 64-byte header.DataCorruptError – A magic or header-CRC mismatch.
- Return type:
- 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 stringhex(MD5(version_uid)), not the raw 16-byte digest (FORMAT-SPEC.md:copy_target_version.version_specencryption).
- synology_apm_repo.sdk.format.crypto.decrypt_version_spec(ciphertext_b64, version_uid, vault_key)¶
Decrypt one
copy_target_version.version_speccolumn: AES-256-CTR, same DEK as chunk-pool/aHlT(vault_key), IV fromversion_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_specencryption).- Returns:
The decoded UTF-8 plaintext (a JSON string).
- Raises:
KeyMaterialError –
vault_keyis not 32 bytes.UnicodeDecodeError – A wrong key or corrupt input.
ValueError –
ciphertext_b64is not ASCII, or not valid base64 (binascii.Error).
- Return type: