I wrote a small utility which can decrypt a home assistant backup in a way similar to using tar directly.
Pick one of two options
The project README explains both.
- A simple shell script (hassio-tar.sh). Available at the root of the repository.
- A self-contained statically compiled binary available for multiple platforms via GitHub releases.
This project started as a shell script but I decided I wanted more verification which required more binary processing than using dd utility.
Example extraction
Shell script example
mkdir some-addon
tar -xOf your-backup.tar file.tar.gz | \
hassio-tar.sh | \
tar -xC some-addon
Go binary example (the go binary does not decompress)
mkdir some-addon
tar -xOf your-backup.tar file.tar.gz | \
hassio-tar | \
tar -xzC some-addon
Why another utility?
I realize a lot of people have created python utilities which interact with the encrypted backups copying Home Assistant python code.
I wanted a simple and near-pure bash utility which behaves just like tar. The purpose is to just decrypt the tar for you and then you can use standard tar command to do whatever you want.
I wanted a simpler utility and one which behaves like other standard Linux utilities without requiring Python. The next best thing would be a statically compiled utility like Go or Rust but I feel this shell script is enough for me right now.
How it works?
Home Assistant uses SecureTar. It is a binary format where the first 48 bytes is a SecureTar header followed by the encrypted tar.gz (or encrypted tar).
SecureTar Header format (48 bytes):
- First 16 bytes is a “magic bytes” identifier of the file format.
- Second 16 bytes is ignored by the shell script. The Go utility extracts first 8 bytes for an integrity check (big-endian uint64 plain size of encrypted data).
- Third 16 bytes is a 16-byte salt.
Algorithms:
- Encrypted with AES 128 CBC
- SHA-256 hashing for key and IV (AES requires a key and IV to encrypt or decrypt)
How Home Assistant derives key and IV:
- Your Home Assistant password creates an AES key (16 bytes); it is derived by rehashing the password 100 times with SHA-256. The first 16 bytes of the resulting SHA is used for the AES key.
- AES IV (16 bytes) is derived by combining the key (16-bytes) with the salt (16-bytes from SecureTar header). Those 32 bytes are then rehashed 100 times with SHA-256. The IV is the first 16 bytes of the resulting hash.
- With both the key and the IV data can be encrypted or decrypted with openssl using aes-128-cbc algorithm.
Decrypting SecureTar:
- Ignore the first 48 bytes and use openssl decrypt the rest of the data.