Skip to content

Security

Passwords and tokens

The MQTT passwords and the Home Assistant token are needed by the service whenever it connects, without anyone there to type them. So they have to be stored in a form the computer can turn back into the password; what can be done is to keep that to as few as possible:

  • They are in %ProgramData%\HADA\settings.json, encrypted with Windows DPAPI for this computer. A copy of the file, from a backup for example, is useless on any other computer.
  • The folder is open only to SYSTEM and the Administrators group (and the service's account). Ordinary users of the computer cannot read the file, and cannot change what it says.
  • The folder must also belong to them, because the owner of a folder can always change who may open it. Any user may create folders in ProgramData, so someone could have made HADA there before HADA was installed. The service therefore checks the owner before it reads anything from the folder: one that belongs to anyone other than the system, the Administrators group or one of its members is moved aside, renamed HADA.untrusted-<date>, and HADA starts without settings and says so in the log. A folder it trusts is given to the Administrators group, so that no single account keeps an owner's rights to it.
  • The window never receives a saved password or token, only whether one is saved. An empty password field keeps the saved one. Passwords are never written to the log.
  • A test with a saved password, or saving settings, needs an elevated administrator, since either may send the password to an address of one's choosing.

What this does not protect against, and cannot:

  • An administrator of the computer, or a program running as one, can read the passwords: such a program can do whatever the service can, including decrypting them. That is true of every program that logs in somewhere on its own.
  • Someone with the computer's disk in their hands can find the key DPAPI uses on the disk too, unless the disk is encrypted. Turn on BitLocker (Device encryption) on a computer that leaves the house.
  • The network: without TLS, an MQTT password travels in plain text to the broker, as does a token to http:// Home Assistant. Use TLS (port 8883) or https:// where the network is not yours, or a VPN such as ZeroTier, which encrypts everything it carries. HADA refuses the worst case by itself, for Home Assistant and (new in 1.15.1) for the MQTT broker.

What helps on the Home Assistant side: give HADA a broker user of its own, so its password opens nothing else and can be changed without touching anything else.

On Linux the service runs as your user and seals the secrets with a key file only you can read; see Security on Linux.

A portable copy encrypts its secrets for the user who runs it rather than for the computer, and keeps them in its own folder, which is as protected as the place it was unpacked to.

The connection to Home Assistant

This is about a Home Assistant connected to directly, with or without the HADA integration. The refusal, the local address and signing in are new in 1.5.0.

  • Encrypted or not. With an https:// address everything between HADA and Home Assistant is encrypted, and Windows checks the server's certificate. A certificate that does not check out ends the connection; there is no setting to accept it anyway. With an http:// address nothing is encrypted: the token, the commands and the notifications can be read, and changed, by whoever is on the way.
  • What HADA refuses. An http:// address is connected to only if it is the computer's own or one of a private network: 10.x, 172.16 to 172.31, 192.168.x, 169.254.x, 100.64 to 100.127 (which VPNs such as Tailscale use), and their IPv6 counterparts. A name is looked up first, and one public address among those it stands for is enough to refuse. The Overview page and the log then say why there is no connection. HADA keeps trying, as a laptop may be back on the network where the name is a local one.
  • Lifting the refusal. Connect to this address without encryption, on the Connections page under the address, lifts it for that one server. That is for a way that is encrypted by something else, a VPN with public addresses for instance. Over the open internet, use https://: Home Assistant Cloud, a reverse proxy with a certificate, or a tunnel all give one.
  • A local address. A Home Assistant can be given another address for the networks you name as home, and that one is usually http://. It is tried only while the computer is connected to one of those networks, told by the name Windows knows it by; anywhere else it is not touched, so the token is not offered to whatever has that address on a foreign network.
  • Signing in. Instead of a pasted token, HADA can keep the refresh token of a sign-in made in the browser. It opens what a token of that user opens, is stored the same way, and can be withdrawn in Home Assistant by itself. During the sign-in HADA listens on 127.0.0.1 at a port Windows picks, and takes only the request that carries the random value it handed out with the page. A sign-in is refused, as a connection is, to an unencrypted public address.
  • Whose token. The token says which Home Assistant user the computer is. For notifications as on a phone, and for the HADA integration, the token of an ordinary user is enough, so HADA need not hold an administrator's. Give it a user of its own: the token can then be withdrawn, in that user's profile, without touching anything else.
  • The HADA integration. A Device ID belongs to the Home Assistant user whose token connected it first. Another user's token is turned away; an administrator's is not. What is pressed or set in Home Assistant reaches the computer only over the connection the computer made itself, and only for the entities switched on in HADA.
  • Notifications as on a phone. Registering with mobile_app yields the ID of a webhook, which opens as much as it says: reporting sensors and pressed buttons as this computer. It is kept encrypted, next to the token, and travels the same way the token does.

The connection to the MQTT broker

New in 1.15.1. The same rule as for a Home Assistant connected to directly:

  • Encrypted or not. With TLS encryption on, everything between HADA and the broker is encrypted, and the broker's certificate is checked against the name typed in. Without it, nothing is: the password, the readings, the commands and the notifications can be read, and changed, by whoever is on the way.
  • What HADA refuses. Without TLS, HADA connects only to a broker at an address of the computer itself or of a private network, the same ones as above. The address checked is the very one connected to, after the name was looked up. The Overview page and the log then say why there is no connection, and HADA keeps trying, as a laptop may be back on the network where the name is a local one. A connection test is refused the same way.
  • Lifting the refusal. Connect to this broker without encryption, on the Connections page under the address (in the new window, under TLS encryption), lifts it for that one server, for a way that is encrypted by something else, such as a VPN with public addresses. Over the open internet, turn TLS on.

Everything else

  • Program folder: new in 1.15.1. The installer always puts HADA in C:\Program Files\HADA and no longer asks for a folder: the service runs as SYSTEM from there, and a folder elsewhere, on a drive's root for instance, would let every signed-in user change what it runs. An administrator who passes another folder on the command line (INSTALLFOLDER=…) gets it with rights of its own, not inherited: full control for SYSTEM and the administrators, reading and running for everyone else. The installed service also never takes itself for a portable copy, whatever lies next to its folder.
  • Pipe access: HADA.Session accepts only local interactive users and denies network access. Only SYSTEM, administrators or the service account can create it. The installed app's clients refuse to talk to a pipe with any other owner (new in 1.15.1: that includes their own user, since the installed service is SYSTEM; a portable copy's clients accept their own user's, as their service is a process of that user), and connect at identification level, so the service can check who they are but cannot act as them.
  • What the tray may send: the tray registers its own entities and reports values for those only. It can't replace entities the service registered, and can't report values for them. A local user who runs their own program against the pipe can therefore add entities of their own to the device, but not touch the service's.
  • Control API: any local interactive user can read status, non-secret settings and logs, look for a newer version and (new in 1.14.0) change how updates are looked for, which decides only what the service asks GitHub. Saving the other settings and testing connections require an elevated administrator, because a connection test may send a saved password to the address being tested.
  • Commands: anyone in Home Assistant who can press a button, publish to a command topic or fire the command event can do what the enabled entities allow: lock the PC, keep it awake, change the volume, turn the screen off, show a notification, press a custom button. Shutting down, restarting, sleeping, hibernating and signing out are possible only after an administrator switched those buttons on. A command carries nothing but a value the entity accepts: on or off, a number in range, or a message; never a program or command line.
  • Custom buttons: what a button runs is fixed in settings, which only an elevated administrator can change. PowerShell buttons run with the service's rights (SYSTEM when installed); program buttons run as the signed-in user. The tray starts programs only when the service asks it to, and talks to the service only through a pipe created by SYSTEM or an administrator, or, for a portable copy, by the user themself.
  • Updates: the update check, daily or when someone presses Check now, and a download you start yourself, are the only connections HADA makes to anything other than your broker or Home Assistant. The installer is fetched over HTTPS from this project's releases only, and the file cannot be replaced between the checksum check and the installer starting. See Updates.
  • Running the service from a console: a development copy started by an account other than SYSTEM does not change the permissions of an existing %ProgramData%\HADA; only the installed service protects that folder. When it creates the folder, or saves settings, it does add its own account, as the service account needs access.
  • Custom PowerShell sensors and buttons: their commands run with the service's rights, which is SYSTEM when installed. Only an elevated administrator can define them, in the window or in appsettings.json, and an administrator can already run anything as SYSTEM, so this grants nothing new. Still, treat %ProgramData%\HADA\settings.json and appsettings.json as files that can run code.
  • Events to Home Assistant: a quick action or a notification button sends an ID, never free text: letters, digits, _, - and ., at most 64 characters. The service passes on only what the tray app of the user at the computer sends, and a quick action only if it is one that exists.
  • Notification pictures: the tray app fetches the picture a notification names, over http or https only, as the signed-in user. Whoever can send notifications can therefore make the computer request an address of their choice; the answer is used only if it is a picture of at most 5 MB.
  • Dashboard window: it shows only the addresses of the Home Assistants connected to and the one the user entered, http or https ones, in a browser profile of its own under the user's profile.
  • Portable copies: the service of a portable copy is a process of the user who started it. It accepts settings from that same user without elevation, since whatever its settings can make it do, that user can do anyway; other users are still refused. Its secrets are encrypted for that user's account, not for the computer. Its folder is as protected as the place it was unpacked to: someone who can write there can change what HADA runs.