# Saltstack renderer for age-encrypted secrets
This project introduces a [SaltStack](https://saltproject.io/) renderer
integrated with [age](https://age-encryption.org/),
a modern and simple encryption tool.
SaltStack is an open-source configuration management system that allows you to
automate the setup, deployment, and management of your infrastructure.
Integrating age encryption enhances SaltStack by providing a secure method to
handle secrets.
By using age, this renderer allows you to securely store encrypted secrets
directly in your source control.
This is particularly useful for environments where security and privacy are
paramount.
Only Salt masters (or masterless minions) configured with the appropriate age
identity or passphrase can decrypt these secrets, ensuring that sensitive
information remains protected even if source control is compromised.
The typical use case for this extension involves encrypting secrets stored in
Salt's pillar data,
enhancing security without sacrificing convenience or functionality.
## Requirements
This package has been tested with Saltstack 3007.0 on Ubuntu 22.04.4 LTS
(Jammy Jellyfish).
## Installation
If you use the [official Saltstack package](https://repo.saltproject.io/),
you can simply install it using:
```sh
sudo salt-pip install saltstack-age
```
## Configuration
age can be used to encrypt data using either a passphrase or an identity file.
This extension supports both, and they can be defined either in the Saltstack
daemon configuration file, or in the daemon environment.
| Type | Configuration directive | Environment variable | Expected value |
| ------------ | ----------------------- | -------------------- | ---------------------------- |
| identity | `age_identity_file` | `AGE_IDENTITY_FILE` | Path of an age identity file |
| passphrase | `age_passphrase` | `AGE_PASSPHRASE` | An age passphrase |
You can check this [example configuration](./example/config/minion).
## Secret encryption
Encrypted secrets are formatted as `ENC[age-passphrase,CIPHERTEXT]` or
`ENC[age-identity,CIPHERTEXT]`, depending on the encryption type.
`CIPHERTEXT` is the age-encrypted value, encoded with base64.
This package provides a handy CLI tool to make it easier:
```sh
$ saltstack-age -P secret-passphrase enc secret-value
ENC[age-passphrase,YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdCB1QndwT3dJejhaSEtZZlIxeFEvZk5RIDIwCmhrcm9OY0tTOWdwNkhWbDdadlNIOHRFYmFLdkpZSjhLTktTWXhZVHFHKzgKLS0tIHFJWVRNc0JzTkpKNHJ1TFBuZ2tybWt0WWVQR0wrbjVnMmlZYzRaWVlBbFkKPWQu4lawaAu1owDXPDwwmj9/tN9/5NF/Avd4jPrLoy/ugUb0ciqm8H5My44=]
```
> [!CAUTION]
> While it is convenient to pass all arguments to the command-line,
> be careful to not leak credentials while doing it.
The tool exposes multiple options to provide the passphrase and identity files.
You can see them in details by reading its help: `saltstack-age --help`.
## Pillar data formatting
The renderer must be specified on the first line of the pillar data files that
contain encrypted values:
```yaml
#!yaml|age
```
Then you can define your secret values as:
```yaml
#!yaml|age
secret: ENC[age-passphrase,YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdCB1QndwT3dJejhaSEtZZlIxeFEvZk5RIDIwCmhrcm9OY0tTOWdwNkhWbDdadlNIOHRFYmFLdkpZSjhLTktTWXhZVHFHKzgKLS0tIHFJWVRNc0JzTkpKNHJ1TFBuZ2tybWt0WWVQR0wrbjVnMmlZYzRaWVlBbFkKPWQu4lawaAu1owDXPDwwmj9/tN9/5NF/Avd4jPrLoy/ugUb0ciqm8H5My44=]
```
For reference, you can read this [example](./example/).
## FAQ
### Why did you write this extension?
As a fan of GPG, I explored the
[GPG renderer](https://docs.saltproject.io/en/latest/ref/renderers/all/salt.renderers.gpg.html)
offered by SaltStack.
While GPG is robust, I found it somewhat cumbersome for smaller projects.
The simplicity and effectiveness of age encryption inspired me to develop this
extension,
providing a straightforward solution for managing secrets in Salt environments.
### Do I need to install age separately?
No, there's no need to install age separately.
This extension utilizes [pyrage](https://github.com/woodruffw/pyrage),
a Python wrapper that embeds [rage](https://github.com/str4d/rage),
a Rust implementation of age.
It simplifies the installation process by embedding all necessary functionality
within the extension itself.
### How do I ensure my secrets are secure when using this extension?
To maximize security:
- Always use secure channels for transferring sensitive information,
including age identities and passphrases.
- Store your age identities and passphrases securely, using environment
variables or secure files that are not checked into source control.
- Be cautious with logging and command-line usage as these can inadvertently
expose sensitive information if not handled properly.
To ensure calls to the `saltstack-age` command are never logged in your
bash history, add it to your
[HISTIGNORE](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-HISTIGNORE)
variable.
### What should I do if I encounter errors during encryption or decryption?
First, verify that your age identities and passphrases are correctly configured
and accessible to the Salt master or minion. Check for typos or incorrect paths
in your configuration.
If the issue persists, refer to the detailed error messages provided by Salt and
age for further troubleshooting.
You can also seek help from the Salt community
or the issue tracker for this project.
Please provide your entire configuration so we can reproduce the error
(and use throwaway credentials to do so).
### Where can I find more resources?
For more detailed guidance on using age,
visit the official [age documentation](https://age-encryption.org/).
For SaltStack, consult the
[SaltStack documentation](https://docs.saltproject.io/) and community forums.
These resources offer comprehensive information and community-driven support
that can help you effectively utilize age encryption in your SaltStack projects.
## Development
* Environment is managed with [rye](https://rye-up.com/)
* Create a virtualenv: `rye sync`
* Check typing: `rye run basedpyright`
* Check formatting with ruff: `rye fmt -- --check`
* Check linting with ruff: `rye check`
* Run tests: `rye run pytest`
See [workflow](./.github/workflows/build.yaml) for reference.
## Release
* Build package: `rye build --clean --wheel`
* Publish package: `rye publish`
See [workflow](./.github/workflows/release.yaml) for reference.
Raw data
{
"_id": null,
"home_page": null,
"name": "saltstack-age",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "age, encryption, pillar, salt, saltstack, security",
"author": "Philippe Muller",
"author_email": null,
"download_url": null,
"platform": null,
"description": "# Saltstack renderer for age-encrypted secrets\n\nThis project introduces a [SaltStack](https://saltproject.io/) renderer\nintegrated with [age](https://age-encryption.org/),\na modern and simple encryption tool.\nSaltStack is an open-source configuration management system that allows you to\nautomate the setup, deployment, and management of your infrastructure.\nIntegrating age encryption enhances SaltStack by providing a secure method to\nhandle secrets.\n\nBy using age, this renderer allows you to securely store encrypted secrets\ndirectly in your source control.\nThis is particularly useful for environments where security and privacy are\nparamount.\nOnly Salt masters (or masterless minions) configured with the appropriate age\nidentity or passphrase can decrypt these secrets, ensuring that sensitive\ninformation remains protected even if source control is compromised.\n\nThe typical use case for this extension involves encrypting secrets stored in\nSalt's pillar data,\nenhancing security without sacrificing convenience or functionality.\n\n## Requirements\n\nThis package has been tested with Saltstack 3007.0 on Ubuntu 22.04.4 LTS\n(Jammy Jellyfish).\n\n## Installation\n\nIf you use the [official Saltstack package](https://repo.saltproject.io/),\nyou can simply install it using:\n\n```sh\nsudo salt-pip install saltstack-age\n```\n\n## Configuration\n\nage can be used to encrypt data using either a passphrase or an identity file.\nThis extension supports both, and they can be defined either in the Saltstack\ndaemon configuration file, or in the daemon environment.\n\n| Type | Configuration directive | Environment variable | Expected value |\n| ------------ | ----------------------- | -------------------- | ---------------------------- |\n| identity | `age_identity_file` | `AGE_IDENTITY_FILE` | Path of an age identity file |\n| passphrase | `age_passphrase` | `AGE_PASSPHRASE` | An age passphrase |\n\nYou can check this [example configuration](./example/config/minion).\n\n## Secret encryption\n\nEncrypted secrets are formatted as `ENC[age-passphrase,CIPHERTEXT]` or\n`ENC[age-identity,CIPHERTEXT]`, depending on the encryption type.\n`CIPHERTEXT` is the age-encrypted value, encoded with base64.\n\nThis package provides a handy CLI tool to make it easier:\n\n```sh\n$ saltstack-age -P secret-passphrase enc secret-value\nENC[age-passphrase,YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdCB1QndwT3dJejhaSEtZZlIxeFEvZk5RIDIwCmhrcm9OY0tTOWdwNkhWbDdadlNIOHRFYmFLdkpZSjhLTktTWXhZVHFHKzgKLS0tIHFJWVRNc0JzTkpKNHJ1TFBuZ2tybWt0WWVQR0wrbjVnMmlZYzRaWVlBbFkKPWQu4lawaAu1owDXPDwwmj9/tN9/5NF/Avd4jPrLoy/ugUb0ciqm8H5My44=]\n```\n\n> [!CAUTION]\n> While it is convenient to pass all arguments to the command-line,\n> be careful to not leak credentials while doing it.\n\nThe tool exposes multiple options to provide the passphrase and identity files.\nYou can see them in details by reading its help: `saltstack-age --help`.\n\n## Pillar data formatting\n\nThe renderer must be specified on the first line of the pillar data files that\ncontain encrypted values:\n\n```yaml\n#!yaml|age\n```\n\nThen you can define your secret values as:\n\n```yaml\n#!yaml|age\nsecret: ENC[age-passphrase,YWdlLWVuY3J5cHRpb24ub3JnL3YxCi0+IHNjcnlwdCB1QndwT3dJejhaSEtZZlIxeFEvZk5RIDIwCmhrcm9OY0tTOWdwNkhWbDdadlNIOHRFYmFLdkpZSjhLTktTWXhZVHFHKzgKLS0tIHFJWVRNc0JzTkpKNHJ1TFBuZ2tybWt0WWVQR0wrbjVnMmlZYzRaWVlBbFkKPWQu4lawaAu1owDXPDwwmj9/tN9/5NF/Avd4jPrLoy/ugUb0ciqm8H5My44=]\n```\n\nFor reference, you can read this [example](./example/).\n\n## FAQ\n\n### Why did you write this extension?\n\nAs a fan of GPG, I explored the\n[GPG renderer](https://docs.saltproject.io/en/latest/ref/renderers/all/salt.renderers.gpg.html)\noffered by SaltStack.\nWhile GPG is robust, I found it somewhat cumbersome for smaller projects.\nThe simplicity and effectiveness of age encryption inspired me to develop this\nextension,\nproviding a straightforward solution for managing secrets in Salt environments.\n\n### Do I need to install age separately?\n\nNo, there's no need to install age separately.\nThis extension utilizes [pyrage](https://github.com/woodruffw/pyrage),\na Python wrapper that embeds [rage](https://github.com/str4d/rage),\na Rust implementation of age.\nIt simplifies the installation process by embedding all necessary functionality\nwithin the extension itself.\n\n### How do I ensure my secrets are secure when using this extension?\n\nTo maximize security:\n- Always use secure channels for transferring sensitive information,\n including age identities and passphrases.\n- Store your age identities and passphrases securely, using environment\n variables or secure files that are not checked into source control.\n- Be cautious with logging and command-line usage as these can inadvertently\n expose sensitive information if not handled properly.\n\nTo ensure calls to the `saltstack-age` command are never logged in your\nbash history, add it to your\n[HISTIGNORE](https://www.gnu.org/software/bash/manual/html_node/Bash-Variables.html#index-HISTIGNORE)\nvariable.\n\n### What should I do if I encounter errors during encryption or decryption?\n\nFirst, verify that your age identities and passphrases are correctly configured\nand accessible to the Salt master or minion. Check for typos or incorrect paths\nin your configuration.\nIf the issue persists, refer to the detailed error messages provided by Salt and\nage for further troubleshooting.\nYou can also seek help from the Salt community\nor the issue tracker for this project.\nPlease provide your entire configuration so we can reproduce the error\n(and use throwaway credentials to do so).\n\n### Where can I find more resources?\n\nFor more detailed guidance on using age,\nvisit the official [age documentation](https://age-encryption.org/).\nFor SaltStack, consult the\n[SaltStack documentation](https://docs.saltproject.io/) and community forums.\nThese resources offer comprehensive information and community-driven support\nthat can help you effectively utilize age encryption in your SaltStack projects.\n\n## Development\n\n* Environment is managed with [rye](https://rye-up.com/)\n* Create a virtualenv: `rye sync`\n* Check typing: `rye run basedpyright`\n* Check formatting with ruff: `rye fmt -- --check`\n* Check linting with ruff: `rye check`\n* Run tests: `rye run pytest`\n\nSee [workflow](./.github/workflows/build.yaml) for reference.\n\n## Release\n\n* Build package: `rye build --clean --wheel`\n* Publish package: `rye publish`\n\nSee [workflow](./.github/workflows/release.yaml) for reference.\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "age renderer for Saltstack",
"version": "0.3.0",
"project_urls": {
"Changelog": "https://github.com/pmuller/saltstack-age/blob/main/CHANGELOG.md",
"Homepage": "https://github.com/pmuller/saltstack-age",
"Issues": "https://github.com/pmuller/saltstack-age/issues",
"Repository": "https://github.com/pmuller/saltstack-age.git"
},
"split_keywords": [
"age",
" encryption",
" pillar",
" salt",
" saltstack",
" security"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "abf1b1902ae65db44da942cac9ed5fd35003cb1b394014df027b5f783e6eacf1",
"md5": "9f51562b4f958c23190f6f53499a6b4c",
"sha256": "061e4e6f1a6fedc23388d6dc1c90f69791f05b267616d6ac2254e402dbaba1bd"
},
"downloads": -1,
"filename": "saltstack_age-0.3.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9f51562b4f958c23190f6f53499a6b4c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 9204,
"upload_time": "2024-04-30T13:52:19",
"upload_time_iso_8601": "2024-04-30T13:52:19.186849Z",
"url": "https://files.pythonhosted.org/packages/ab/f1/b1902ae65db44da942cac9ed5fd35003cb1b394014df027b5f783e6eacf1/saltstack_age-0.3.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-30 13:52:19",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pmuller",
"github_project": "saltstack-age",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "saltstack-age"
}
JSON
