Auth

The Auth module provides the authentication mechanism for the OpenWebNet gateway. OpenWebNet allows for two types of authentication: open algorithm and hmac algorithm.

The open algorithm is the simplest one and is used by the majority of the gateways, but it's not officially documented.

The hmac algorithm is used by the latest gateways, and the documentation is available.

pyown.auth.open.own_calc_pass

own_calc_pass(password: str | int, nonce: str | int) -> str

Encodes the password using the OPEN algorithm. Source: https://rosettacode.org/wiki/OpenWebNet_password#Python

Parameters:

Name	Type	Description	Default
password	str | int	The password to encode must be composed of only digits.	required
nonce	str	The nonce received from the gateway.	required

Returns:

Name	Type	Description
str	str	The encoded password.

pyown.auth.hmac.client_hmac

client_hmac(
    server_key: str,
    client_key: str,
    password: str,
    client_identity: str = "736F70653E",
    server_identity: str = "636F70653E",
    hash_algorithm: AuthAlgorithm = SHA256,
) -> bytes

Generates the HMAC authentication for the client.

Parameters:

Name	Type	Description	Default
server_key	str	The key sent by the server (Ra)	required
client_key	str	The key generated by the client (Rb)	required
password	str	The open password of the server (Kab = sha(kab))	required
client_identity	str	string used to identify the client (A)	'736F70653E'
server_identity	str	string used to identify the server (B)	'636F70653E'
hash_algorithm	AuthAlgorithm	The hash function to use for the hmac calculation (can be sha1 or sha256)	SHA256

Returns:

Name	Type	Description
str	bytes	the client authentication string in bytes

pyown.auth.hmac.server_hmac

server_hmac(
    server_key: str,
    client_key: str,
    password: str,
    hash_algorithm: AuthAlgorithm = SHA256,
) -> bytes

Generates the HMAC authentication for the server.

Parameters:

Name	Type	Description	Default
server_key	str	The key sent by the server (Ra)	required
client_key	str	The key generated by the client (Rb)	required
password	str	The open password of the server (Kab = sha(kab))	required
hash_algorithm	AuthAlgorithm	The hash function to use for the hmac calculation (can be sha1 or sha256)	SHA256

Returns:

Name	Type	Description
str	bytes	the server confirmation string in bytes

pyown.auth.hmac.compare_hmac

compare_hmac(hmac1: bytes, hmac2: bytes) -> bool

Compares two hmacs in constant time.

Parameters:

Name	Type	Description	Default
hmac1	bytes	The first hmac	required
hmac2	bytes	The second hmac	required

Returns:

Name	Type	Description
bool	bool	True if the hmacs are equal, False otherwise

pyown.auth.hmac.create_key

create_key(hash_algorithm: AuthAlgorithm = SHA256) -> str

Creates a random key for the hmac.

Parameters:

Name	Type	Description	Default
hash_algorithm	AuthAlgorithm	The hash function to use for the hmac calculation (can be sha1 or sha256)	SHA256

Returns:

Name	Type	Description
str	str	the key in hex format

pyown.auth.hmac.hex_to_digits

hex_to_digits(hex_string: str) -> str

Converts a hex string to digits.

Parameters:

Name	Type	Description	Default
hex_string	str	The hex string	required

Returns:

Name	Type	Description
str	str	the digit string

pyown.auth.hmac.digits_to_hex

digits_to_hex(digits_string: str) -> str

Converts a digit string to hex.

Parameters:

Name	Type	Description	Default
digits_string	str	The digit string	required

Returns:

Name	Type	Description
str	str	the hex string

pyown.auth.enum.AuthAlgorithm

Bases: IntEnum

Represents the all allowed hashing algorithms when using the HMAC authentication algorithm.

Attributes:

Name	Type	Description
SHA1		The SHA1 hashing algorithm.
SHA256		The SHA256 hashing algorithm

to_message

to_message() -> GenericMessage

Converts the AuthAlgorithm to a message.

Returns:

Name	Type	Description
GenericMessage	GenericMessage	The message.

from_string classmethod

from_string(value: str) -> AuthAlgorithm

Converts a string to an AuthAlgorithm.

Parameters:

Name	Type	Description	Default
value	str	The string to convert.	required

Returns:

Name	Type	Description
AuthAlgorithm	AuthAlgorithm	The corresponding AuthAlgorithm.