HomeAssistant Secret Service 🕴

A small configurable service that can validate values against secrets without having to expose the secrets to other configurations. Home Assistant made the choice to not allow secrets inside of templates which makes checking a value against a secret in an automation or script difficult. While there are workarounds they are either insecure, rudimentary, inflexible, or some combination of these. With the Secret Service values can be validated against secrets stored in the secrets.yaml file or even hard coded into the service configuration.

Secrets are hashed using bcrypt with a random salt generated at setup time to ensure as much security as possible and limit where secrets are exposed. Secrets and hashes are not exposed via the service call or stored in the state, again the maintain as much security as possible.

✨Features✨

Name	Description
Single Secret Validation	Validation against a single named secret.
Grouped Secret Validation	Validation against one or more secrets with a single name. This can be useful when you want to provide different secrets but validate in a single call. Each group can only have one instance of each secret.

Planned Features

Name	Description
Rate Limiting	Configurable limits on how often secrets can be validated against to prevent brute force attacks.
Failure Limits	Configurable limits on how many times a failed validation can occur and options to handle when the limits are reached (eg. lock for a period of time)
Conditions	Allow secrets and groups to have conditions on their use allowing for even greater customization. This assumes that there's a way to use the existing condition system within the integration, more research is needed here.

📦Installation📦

HACS (Recommended)

1. Open HACS
2. Go to Integrations
3. Click the ellipse button in the top right and select Custom Repositories
4. Enter the following information
   • Repository: https://github.com/amura11/ha-secret-service
   • Category: Integration
5. Click "Add"
6. Close the modal then click Explore & Download Repositories
7. Search for `Secret Checker`` and select the repository
8. Click the Download button
9. Restart Home Assistant
10. Add an entry to your configuration for the Secret Service
11. Restart Home Assistant ...again

Manually

1. Using the tool of choice open the directory (folder) for your HA configuration (where you find configuration.yaml).
2. If you do not have a custom_components directory (folder) there, you need to create it.
3. In the custom_components directory (folder) create a new folder called secret_service.
4. Download all the files from the custom_components/secret_service/ directory (folder) in this repository.
5. Place the files you downloaded in the new directory (folder) you created.
6. Restart Home Assistant
7. Add an entry to your configuration for the Secret Service
8. Restart Home Assistant ...again

🔧Configuration🔧

Main Configuration

Name	Type	Description	Required	Default
secrets	array	An array of Secret Configurations	*
groups	array	An array of Group Configurations	*

*Groups and secrets are not required but you should at least have one otherwise why are you using the service? 🤔

Note: The same secret can appear in the secrets section multiple times and the same secret can appear in the secrets section and in the groups section. However, the same secret cannot appear more than once in the secrets section of a single group. The way secrets are checked in a group uses the secret itself (although hashed) as a key and having the secret appear multiple times wouldn't work.

Single Secret Configuration

Name	Type	Description	Required	Default
secret	string	The name of the secret that will be used when calling the service to validate a value against this secret.	✔
value	string	The actual value of the secret. This can be pulled from the secrets.yaml file or hard coded.	✔

Secret Group Configuration

Name	Type	Description	Required	Default
group	string	The name of the group that will be used when calling the service to validate a value against this group.	✔
secrets	array	An array of Secret Configurations	✔

Examples

Basic Example

secret_service:
  secrets:
    - secret: secret_a
      value: !secret my_secret
  groups:
    - group: group_1
      secrets:
        - secret: secret_1
          value: qtPHuwV2vEVanS
        - secret: secret_2
          value: !secret my_secret

📄Usage📄

Call the service using the parameters described below.

Name	Type	Description	Required	Default
name	string	The name of the group or secret that the value should be validated against	✔
value	array	An array of Secret Configurations	✔
full_response	bool	When True the response result field will contain all validation data. When False the result field a simple bool		False

Response Data

When using full_response: False:

{
    result: <true|false>
}

When using full_response: True:

{
    result: <"success"|"failed_invalid"|"failed_attempts_exceeded"|"failed_rate_exceeded">
}

Note: More data will be added to this in the future but result will always hold the result codes above.

Examples

Basic Example

service: secret_service.check_secret
data:
  name: "group_or_secret_name"
  value: "sEcReTpAsSwOrD"

Full Script Example

alias: Test
sequence:
  - service: secret_service.check_secret
    data:
      name: secret_a
      value: "{{code}}"
    response_variable: check_result
  - condition: template
    value_template: "{{ check_result.result }}"
  - service: system_log.write
    data:
      level: info
      message: Check successful
mode: single
icon: mdi:test-tube

Where the code variable is passed in as data to the script.

🎉Contributions are welcome!🎉

If you want to contribute to this please read the Contribution guidelines

---