Modernizing encryption of House Assistant backups

Backups are a kind of quiet, highly effective options: once they work, you don’t discover them, however if you want them, they’re all the things. We’ve advanced House Assistant’s built-in backup format over time to maintain it protected and safe, particularly when backing as much as distant places. As fashionable cryptography has superior, we wanted to construct a system to match. SecureTar v3 is a purpose-built library for creating and studying password-protected House Assistant backups with fashionable cryptography and safer, stronger defaults.

To assist us get this proper, we commissioned Path of Bits, a number one safety engineering agency, to independently audit our work. Their evaluation discovered that SecureTar v3 follows best-in-class practices for core safety algorithms, similar to hashing and encryption. Additionally they recognized three areas for enchancment, which they confirmed have been resolved of their follow-up evaluation. This audit was paid for by the Open House Basis so we may put money into enhancements that shield customers’ privateness, safety, and management.

Your backups will begin utilizing this new encryption robotically, starting with the discharge of model 2026.4 on April 1, 2026. Please word outdated backups will nonetheless work and be readable after this variation (see Advisable subsequent steps beneath). For extra technical particulars, please learn on…

A little bit of historical past

House Assistant backups have all the time been encrypted by default, and use a excessive entropy key, to assist guarantee your knowledge is protected. After we launched backups, early codecs (v1 and v2) used the identical AES-128 encryption variant, together with a easy key derivation (the code that turns your passphrase into the precise key used for encryption). Sam Gleske delivered to our consideration that the key-derivation step was now not as much as fashionable requirements.

It’s price stressing an vital level: House Assistant’s passphrase generator already produces lengthy, high-entropy passphrases. Which means that backups created beforehand have been troublesome to interrupt if utilizing this function. To reveal this, we calculated {that a} brute pressure passphrase assault (the place attackers strive many passwords quickly) on the backups would take extra time than the typical lifespan of an individual to achieve success.

Nonetheless, as a result of it was potential to manually generate an insecure passphrase for superior customers, and the library’s inner cryptographic primitives might be improved, we determined to overtake SecureTar to make use of best-in-class algorithms, and to have that work validated by an exterior audit.

What we modified and why

The objectives have been easy: select fashionable, well-studied algorithms, keep away from design errors that might weaken confidentiality or integrity, and make v3 the safe default.

Highlights of the SecureTar v3 design:

Fashionable key derivation: SecureTar v3 makes use of Argon2id for password-based key derivation. Argon2id is a memory-hard algorithm that makes brute-force assaults way more expensive.
Fashionable encryption and authentication: Encryption is supplied by the libsodium secretstream API (uncovered in Python through PyNaCl), which implements a strong streaming authenticated-encryption building utilizing XChaCha20-Poly1305. That mixture offers each confidentiality (no one can learn your knowledge) and integrity/authentication (no one can tamper with it with out detection).
Safer defaults and parsing: We set safer defaults so new backups use v3, and we mounted parsing logic to keep away from silently treating corrupt knowledge as legitimate legacy backups.

We made these decisions to make sure that SecureTar is resilient to fashionable assaults and simpler to cause about from a safety perspective.

Unbiased audit by Path of Bits

After implementing SecureTar v3, we commissioned Path of Bits to carry out the targeted safety evaluation and repair evaluation. Here’s what the evaluation discovered:

Timing side-channel in a validation comparability (informational): The audit identified a minor coding concern in how we checked a validation key. It wasn’t a safety threat (the worth is saved overtly within the file header), however we up to date the test to a safer kind so safety instruments cease flagging it.
Insecure fallback to legacy protocol model (informational): Header parsing logic might be confused by corrupted knowledge; we up to date the logic so corrupted headers increase an error as a substitute of silently falling again.
Provide-chain threat in GitHub Actions workflow (medium): Workflow steps weren’t pinned to particular commit hashes and used broad permissions, opening the construct course of to potential supply-chain assaults. We pinned actions to particular commit hashes and tightened permissions.

Crucially, Path of Bits’ post-fix evaluation confirmed all three findings have been resolved. This reveals we have now not solely adopted fashionable cryptography, but in addition closed the gaps the audit uncovered.

You possibly can learn extra in regards to the audit and the fixes within the Path of Bits report.

The way you assist assist this work

Safety work (particularly exterior audits and specialist engineering) prices cash. The Open House Basis supplies the construction and funds that allow us do that work. That cash comes, partially, from individuals who purchase official House Assistant or ESPHome merchandise from the muse’s industrial companions, and merchandise from the Open House Basis Retailer: we actually respect your assist!

Due to this, we have been in a position to fee specialists, make investments engineering time, and validate the fixes. That funding protects customers’ backups (which frequently include configurations, passwords and API keys, integrations, and automations) and retains House Assistant a reliable, safe platform for everybody.

Advisable subsequent steps

Guarantee House Assistant is up to date to the newest model. The 2026.4 launch contains SecureTar v3.
Any encrypted backup created after updating to 2026.4 will use v3’s improved format.
Current backups are nonetheless safe, as House Assistant’s generated passphrase is powerful. That stated, for further safety, you’ll be able to regenerate the encryption key in your backup settings (use the Change encryption key choice on the backside of the backup settings web page).
In the event you use the ha backup CLI command, or the hassio.backup_full or hassio.backup_partial actions to create backups, and also you’ve used a brief/low entropy password, you need to select a brand new password.

For the curious: technical abstract

Key derivation: Argon2id (memory-hard), utilizing separate sub-keys for every backup half.
Encryption / AEAD: XChaCha20-Poly1305 through libsodium secretstream (PyNaCl) with 256-bit key measurement. AEAD means your knowledge will not be solely encrypted, but in addition authenticated (validating the information is unchanged/not tampered with).
Audit: Path of Bits: 3 findings (2 informational, 1 medium), all resolved.
Construct hardening: GitHub Actions pinned to commit SHAs and narrower permissions to cut back supply-chain threat.

In search of extra? Take a look at the SecureTar repository on GitHub.

Closing word

Safety is iterative, and this newest work has helped construct a stronger basis for House Assistant backups, and a clearer path ahead for sustaining that safety over time.

If you wish to examine comparable previous efforts, see a few of our different posts:

By maintaining House Assistant safe, we make the platform safer, extra trusted, and extra pleasing for the entire neighborhood. Thanks.