loader/_docs/02_document/modules/binary_split.md

Module: binary_split

Purpose

Handles the encrypted Docker image archive workflow: downloading a key fragment from the API, decrypting an AES-256-CBC encrypted archive, loading it into Docker, and verifying expected images are present.

Public Interface

Functions

Function	Signature	Description
download_key_fragment	(resource_api_url: str, token: str) -> bytes	GET request to /binary-split/key-fragment with Bearer auth
decrypt_archive	(encrypted_path: str, key_fragment: bytes, output_path: str) -> None	AES-256-CBC decryption with SHA-256 derived key; strips PKCS7 padding
docker_load	(tar_path: str) -> None	Runs docker load -i <tar_path> subprocess
check_images_loaded	(version: str) -> bool	Checks all API_SERVICES images exist for given version tag

Module-level Constants

Name	Value
API_SERVICES	List of 7 Docker image names: azaion/annotations, azaion/flights, azaion/detections, azaion/gps-denied-onboard, azaion/gps-denied-desktop, azaion/autopilot, azaion/ai-training

Internal Logic

decrypt_archive

1. Derives AES key: SHA-256(key_fragment) → 32-byte key
2. Reads first 16 bytes as IV from encrypted file
3. Decrypts remaining data in 64KB chunks using AES-256-CBC
4. After decryption, reads last byte of output to determine PKCS7 padding length
5. Truncates output file to remove padding

check_images_loaded

Iterates all 7 service image names, runs docker image inspect <name>:<version> for each. Returns False on first missing image.

Dependencies

• Internal: none (leaf module)
• External: hashlib, os, subprocess (stdlib), requests (2.32.4), cryptography (44.0.2)

Consumers

• main — _run_unlock() calls all four functions; unlock() endpoint calls check_images_loaded()

Data Models

None.

Configuration

No env vars consumed directly. API_SERVICES list is hardcoded.

External Integrations

• REST API: GET {resource_api_url}/binary-split/key-fragment — downloads encryption key fragment
• Docker CLI: docker load and docker image inspect via subprocess
• File system: reads encrypted .enc archive, writes decrypted .tar archive

Security

• Key derivation: SHA-256 hash of server-provided key fragment
• Encryption: AES-256-CBC with PKCS7 padding
• The key fragment is ephemeral — downloaded per unlock operation

Tests

No tests found.