esphome::home_io_control::crypto Namespace Reference

Functions
void	compute_checksum (uint8_t byte, uint8_t &c1, uint8_t &c2)
	Proprietary checksum algorithm used in IV construction.
void	construct_iv (const uint8_t *data, uint8_t len, const uint8_t challenge[HMAC_SIZE], uint8_t iv[IV_SIZE])
	Construct the 16-byte initialization vector (IV) for AES encryption.
bool	aes128_encrypt (const uint8_t in[AES_BLOCK_SIZE], const uint8_t key[AES_KEY_SIZE], uint8_t out[AES_BLOCK_SIZE])
	AES-128 ECB encrypt a single 16-byte block.
bool	aes128_decrypt (const uint8_t in[AES_BLOCK_SIZE], const uint8_t key[AES_KEY_SIZE], uint8_t out[AES_BLOCK_SIZE])
	AES‑128 ECB decrypt a single 16‑byte block.
bool	create_hmac (const uint8_t *data, uint8_t len, const uint8_t challenge[HMAC_SIZE], const uint8_t key[AES_KEY_SIZE], uint8_t hmac[HMAC_SIZE])
	Create a 6-byte HMAC for authentication (proprietary IO-Homecontrol scheme).
bool	verify_hmac (const uint8_t *data, uint8_t len, const uint8_t hmac[HMAC_SIZE], const uint8_t challenge[HMAC_SIZE], const uint8_t key[AES_KEY_SIZE])
	Verify a received HMAC using constant-time comparison.
bool	crypt_key (const uint8_t *data, uint8_t len, const uint8_t challenge[HMAC_SIZE], const uint8_t in[AES_KEY_SIZE], uint8_t out[AES_KEY_SIZE])
	Encrypt or decrypt a system key during pairing.
void	generate_challenge (uint8_t out[HMAC_SIZE])
	Generate 6 random bytes for a challenge using the ESP32 hardware RNG.

Function Documentation

aes128_decrypt()

bool esphome::home_io_control::crypto::aes128_decrypt	(	const uint8_t	in[AES_BLOCK_SIZE],
		const uint8_t	key[AES_KEY_SIZE],
		uint8_t	out[AES_BLOCK_SIZE] )

AES‑128 ECB decrypt a single 16‑byte block.

Parameters

in	16‑byte ciphertext block.
key	16‑byte AES key.
out	Output: 16‑byte plaintext block.

Returns

true on success.

Definition at line 311 of file proto_crypto.cpp.

aes128_encrypt()

bool esphome::home_io_control::crypto::aes128_encrypt	(	const uint8_t	in[AES_BLOCK_SIZE],
		const uint8_t	key[AES_KEY_SIZE],
		uint8_t	out[AES_BLOCK_SIZE] )

AES-128 ECB encrypt a single 16-byte block.

AES‑128 ECB encrypt a single 16‑byte block.

Parameters

in	16‑byte plaintext block.
key	16‑byte AES key.
out	Output: 16‑byte ciphertext block.

Returns

true on success.

Definition at line 307 of file proto_crypto.cpp.

compute_checksum()

void esphome::home_io_control::crypto::compute_checksum	(	uint8_t	byte,
		uint8_t &	c1,
		uint8_t &	c2 )

Proprietary checksum algorithm used in IV construction.

Update running checksum bytes (c1, c2) with a new data byte (IO‑Homecontrol IV derivation).

This is NOT a standard CRC - it's a custom accumulator used by the IO-Homecontrol protocol to mix frame data into the initialization vector for AES encryption.

Parameters

byte	Input data byte.
c1	First checksum byte (inout).
c2	Second checksum byte (inout).

Definition at line 269 of file proto_crypto.cpp.

construct_iv()

void esphome::home_io_control::crypto::construct_iv	(	const uint8_t *	data,
		uint8_t	len,
		const uint8_t	challenge[HMAC_SIZE],
		uint8_t	iv[IV_SIZE] )

Construct the 16-byte initialization vector (IV) for AES encryption.

Construct the 16‑byte IV for AES encryption from frame data and challenge.

Layout: [bytes 0-7: frame data or 0x55 padding] [bytes 8-9: checksums] [bytes 10-15: challenge] The IV binds the HMAC to both the frame content and the random challenge, preventing replay attacks.

Layout: bytes 0–7 = up to 8 frame bytes padded with 0x55, bytes 8–9 = checksums, bytes 10–15 = challenge.

Parameters

data	Frame data bytes.
len	Number of data bytes.
challenge	6‑byte challenge from the device.
iv	Output: 16‑byte IV.

Definition at line 289 of file proto_crypto.cpp.

Here is the call graph for this function:

create_hmac()

bool esphome::home_io_control::crypto::create_hmac	(	const uint8_t *	data,
		uint8_t	len,
		const uint8_t	challenge[HMAC_SIZE],
		const uint8_t	key[AES_KEY_SIZE],
		uint8_t	hmac[HMAC_SIZE] )

Create a 6-byte HMAC for authentication (proprietary IO-Homecontrol scheme).

Create a 6‑byte HMAC for authentication (IO‑Homecontrol proprietary scheme).

See proto_crypto.h for full parameter documentation and construction details.

Process: build IV from [data + challenge] → AES‑128‑ECB encrypt IV with system key → take first 6 bytes. This is NOT a standard HMAC; it is specific to IO‑Homecontrol and matches the protocol specification as implemented in compatible devices.

Parameters

data	Frame data bytes (usually command + payload).
len	Length of data.
challenge	6‑byte random challenge.
key	16‑byte system key.
hmac	Output: 6‑byte HMAC.

Note

The IV construction appends two checksum bytes derived from the data stream (see compute_checksum()) followed by the 6‑byte challenge, padded to 16 bytes with 0x55. The AES result is truncated to 6 bytes for transmission.

Returns

true on success.

Definition at line 317 of file proto_crypto.cpp.

Here is the call graph for this function:

crypt_key()

bool esphome::home_io_control::crypto::crypt_key	(	const uint8_t *	data,
		uint8_t	len,
		const uint8_t	challenge[HMAC_SIZE],
		const uint8_t	in[AES_KEY_SIZE],
		uint8_t	out[AES_KEY_SIZE] )

Encrypt or decrypt a system key during pairing.

Encrypt or decrypt the system key during pairing (XOR with AES‑encrypted IV).

The system key is XORed with AES(IV, TRANSFER_KEY) - the same operation encrypts and decrypts. The TRANSFER_KEY is a hardcoded key known to all IO-Homecontrol devices.

The same operation works for both directions: encrypting for the device and decrypting the device's acknowledgement.

Parameters

data	Frame data (typically the key‑init command byte).
len	Length of data (usually 1).
challenge	Device's 6‑byte challenge.
in	Input key (plaintext for encrypt, ciphertext for decrypt).
out	Output key.

Warning

This primitive is used ONLY during the key‑transfer phase (0x32). The resulting system key is then used for all normal authenticated exchanges. Never call this with arbitrary data outside the pairing sequence.

Returns

true on success.

Definition at line 347 of file proto_crypto.cpp.

Here is the call graph for this function:

generate_challenge()

void esphome::home_io_control::crypto::generate_challenge

(

uint8_t

out[HMAC_SIZE]

)

Generate 6 random bytes for a challenge using the ESP32 hardware RNG.

Generate 6 random bytes for a challenge using the ESP hardware RNG.

Parameters

out	Output buffer (6 bytes).

Definition at line 360 of file proto_crypto.cpp.

verify_hmac()

bool esphome::home_io_control::crypto::verify_hmac	(	const uint8_t *	data,
		uint8_t	len,
		const uint8_t	hmac[HMAC_SIZE],
		const uint8_t	challenge[HMAC_SIZE],
		const uint8_t	key[AES_KEY_SIZE] )

Verify a received HMAC using constant-time comparison.

Verify a received 6‑byte HMAC using constant‑time comparison.

Full documentation in proto_crypto.h.

Parameters

data	Frame data bytes.
len	Length of data.
hmac	Received 6‑byte HMAC.
challenge	Challenge used in HMAC calculation.
key	16‑byte system key.

Returns

true if HMAC matches.

Definition at line 331 of file proto_crypto.cpp.

Here is the call graph for this function: