ansible-vars 1.0.7__tar.gz → 1.0.9__tar.gz

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ansible-vars
-Version: 1.0.7
+Version: 1.0.9
 Summary: Manage vaults and variable files for Ansible
 Project-URL: Homepage, https://github.com/xorwow/ansible-vars
 Project-URL: Issues, https://github.com/xorwow/ansible-vars/issues
@@ -105,6 +105,10 @@ By default, the first loaded key is used for all encryption tasks. Note that aut
 
 You can disable automatic key detection by flagging `--no-encrypt-keys|-D`. Use `ansible-vars keyring` to view all available keys.
 
+#### Encryption salts
+
+Each time you edit a vault or otherwise encrypt a value, a randomly generated salt is used so even identical plain values will result in unique ciphers. However, this also means that each time a single encrypted variable is edited, all other ciphers in the vault will change as well. You can avoid this by passing a fixed salt via `--fixed-salt|-S <salt>`. Note that it should be at least 32 characters long and sufficiently random for Ansible's AES-256 encryption, and that you won't benefit from unique ciphers for identical plaintexts anymore.
+
 ### Diff logging
 
 **TL;DR:** You can use `-l <log directory>` to log changes to edited vaults to a vault-encrypted log file.
@@ -174,6 +178,10 @@ Shows the amounts of encrypted and decrypted variables in a vault file. Supports
 
 En-/Decrypts or checks the encryption status of a file or string value. Note that only full file encryption is considered in file mode, a hybrid vault with individually encrypted variables will be counted as plain.
 
+### rekey
+
+Re-encrypts a vault file with a different encryption key and/or salt. The key specified in the global `--encryption-key|-K <identifier>` flag is used for encryption, along with an optional fixed salt set via the global `--fixed-salt|-S <salt>` flag.
+
 #### convert
 
 Convenience function to convert between fully encrypted vaults and hybrid vaults. Useful if you wish to convert your "legacy" fully encrypted vaults to plain files with all string values individually encrypted. Works both ways.
@@ -220,6 +228,10 @@ Set the tempfile/staging root as you would with `-T <path>`.
 
 Invert the default creation mode for files: If unset or `no`, files are created with full encryption unless specified otherwise via the `--plain|-p` flag. This behavior mirrors that of `ansible-vault`. When set to `yes`, the behavior and flag are inverted as files are created without encryption by default unless specified otherwise via the `--no-plain|-P` flag.
 
+#### AV_SALT
+
+Set a fixed salt as you would with `-S <salt>`.
+
 ### Python library
 
 When using `ansible-vars` as a library, import any of these modules from the `ansible_vars` module.
@@ -270,7 +282,6 @@ When editing a file or creating a daemon, decrypted vaults are written to disk t
     - Changes to file metadata (permissions, ...) are not mirrored.
 - `ansible-vars` does not support files which are not (Jinja2) YAML dictionaries, except for limited support in these commands:
     - `edit`, `view` (without `--json` support), `encrypt`, `decrypt`, `is-encrypted`
-- When a vault is modified, all of its ciphers will change due to new salts, even if only one encrypted variable has been changed.
 
 ## Extension plans
 

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/README.md

@@ -83,6 +83,10 @@ By default, the first loaded key is used for all encryption tasks. Note that aut
 
 You can disable automatic key detection by flagging `--no-encrypt-keys|-D`. Use `ansible-vars keyring` to view all available keys.
 
+#### Encryption salts
+
+Each time you edit a vault or otherwise encrypt a value, a randomly generated salt is used so even identical plain values will result in unique ciphers. However, this also means that each time a single encrypted variable is edited, all other ciphers in the vault will change as well. You can avoid this by passing a fixed salt via `--fixed-salt|-S <salt>`. Note that it should be at least 32 characters long and sufficiently random for Ansible's AES-256 encryption, and that you won't benefit from unique ciphers for identical plaintexts anymore.
+
 ### Diff logging
 
 **TL;DR:** You can use `-l <log directory>` to log changes to edited vaults to a vault-encrypted log file.
@@ -152,6 +156,10 @@ Shows the amounts of encrypted and decrypted variables in a vault file. Supports
 
 En-/Decrypts or checks the encryption status of a file or string value. Note that only full file encryption is considered in file mode, a hybrid vault with individually encrypted variables will be counted as plain.
 
+### rekey
+
+Re-encrypts a vault file with a different encryption key and/or salt. The key specified in the global `--encryption-key|-K <identifier>` flag is used for encryption, along with an optional fixed salt set via the global `--fixed-salt|-S <salt>` flag.
+
 #### convert
 
 Convenience function to convert between fully encrypted vaults and hybrid vaults. Useful if you wish to convert your "legacy" fully encrypted vaults to plain files with all string values individually encrypted. Works both ways.
@@ -198,6 +206,10 @@ Set the tempfile/staging root as you would with `-T <path>`.
 
 Invert the default creation mode for files: If unset or `no`, files are created with full encryption unless specified otherwise via the `--plain|-p` flag. This behavior mirrors that of `ansible-vault`. When set to `yes`, the behavior and flag are inverted as files are created without encryption by default unless specified otherwise via the `--no-plain|-P` flag.
 
+#### AV_SALT
+
+Set a fixed salt as you would with `-S <salt>`.
+
 ### Python library
 
 When using `ansible-vars` as a library, import any of these modules from the `ansible_vars` module.
@@ -248,7 +260,6 @@ When editing a file or creating a daemon, decrypted vaults are written to disk t
     - Changes to file metadata (permissions, ...) are not mirrored.
 - `ansible-vars` does not support files which are not (Jinja2) YAML dictionaries, except for limited support in these commands:
     - `edit`, `view` (without `--json` support), `encrypt`, `decrypt`, `is-encrypted`
-- When a vault is modified, all of its ciphers will change due to new salts, even if only one encrypted variable has been changed.
 
 ## Extension plans
 

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ansible-vars"
-version = "1.0.7"
+version = "1.0.9"
 authors = [
   { name="xorwow", email="pip@xorwow.de" },
 ]

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/src/ansible_vars/cli.py

@@ -84,6 +84,10 @@ Specify vault keys to load for en-/decryption. Not required for vars files with
 A key is a combination of an identifier (can be a vault ID or anything else, ideally unique) and a passphrase.
 By default, available keys are auto-detected if your current directory contains an Ansible config and appended to the ones you supplied.
 If no explicit encryption key is specified, the first supplied/available key is used.
+
+[!] When editing a hybrid vault file, changing even a single variable will change all variables' ciphers, as salts are generated randomly.
+You can prevent this by passing a fixed salt via `-S <salt>`, which will result in any plaintext always resolving to the same cipher.
+For Ansible's AES-256, a length of at least 32 characters is recommended.
 ''',
     'log_args': '''
 Log a diff of any vault changes performed with this program to an encrypted or plain logfile, creating it if necessary.
@@ -130,6 +134,10 @@ Decrypt a string and return it or fully decrypt a file in-place. Uses the first
 ''',
     'cmd_is_enc': '''
 Check if a string or file is (fully) vault-encrypted.
+''',
+    'cmd_rekey': '''
+Update a vault's ciphers with a new encryption key and/or salt.
+The key referenced by `--encryption-key|-K <identifier>` and/or the salt set by `--fixed-salt|-S <salt>` are used for re-encryption.
 ''',
     'cmd_convert': '''
 Switch a file between full outer and full inner encryption for convenient migrating between encryption schemes.
@@ -198,6 +206,7 @@ DEFAULT_EDITOR: str = os.environ.get('EDITOR', 'notepad.exe' if os.name == 'nt'
 DEFAULT_COLOR_MODE: str = os.environ.get('AV_COLOR_MODE', '256' if sys.stdout.isatty() else 'none')
 DEFAULT_TEMP_DIR: str = os.environ.get('AV_TEMP_DIR', gettempdir())
 DEFAULT_CREATE_PLAIN: bool = os.environ.get('AV_CREATE_PLAIN', 'no').lower() in [ 'yes', 'y', 'true', 't', '1' ]
+DEFAULT_SALT: str | None = os.environ.get('AV_SALT', None)
 
 args: ArgumentParser = ArgumentParser(
     prog = 'ansible-vars',
@@ -243,6 +252,10 @@ key_args.add_argument(
 )
 key_args.add_argument('--no-detect-keys', '-D', action='store_false', dest='detect_keys', help='disable automatic key detection')
 key_args.add_argument('--encryption-key', '-K', type=str, metavar='<identifier>', help='which of the loaded keys to use for encryption')
+key_args.add_argument(
+    '--fixed-salt', '-S', type=str, metavar='<salt>', default=DEFAULT_SALT,
+    help='a fixed salt to use for encryption (should be 32+ chars!)'
+)
 
 log_args = args.add_argument_group('logging vault changes', description=HELP['log_args'])
 log_mutex = log_args.add_mutually_exclusive_group()
@@ -329,6 +342,13 @@ cmd_is_enc.add_argument('target', type=str, metavar='<vault path | string>', hel
     .completer = _prefixed_path_completer # type: ignore
 cmd_is_enc.add_argument('--quiet', '-q', action='store_true', help='no output, only set the rc to 0 if encrypted or 100 if unencrypted')
 
+cmd_rekey = commands.add_parser(
+    'rekey', help='update a vault\'s encryption key (from -K) and/or salt (from -S)', description=HELP['cmd_rekey'],
+    formatter_class=RawDescriptionHelpFormatter
+)
+cmd_rekey.add_argument('vault_path', type=str, metavar='<vault path>', help='path of vault to rekey') \
+    .completer = _prefixed_path_completer # type: ignore
+
 cmd_convert = commands.add_parser(
     'convert', help='switch vault between outer (file) and inner (vars) encryption', description=HELP['cmd_convert'],
     formatter_class=RawDescriptionHelpFormatter
@@ -565,7 +585,7 @@ sys.excepthook = _exc_hook
 # Load vault keys
 
 _explicit_keys: list[VaultKey] = [ VaultKey(passphrase, vault_id=id) for id, passphrase in config.keys ]
-keyring = VaultKeyring(_explicit_keys.copy(), detect_available_keys=config.detect_keys)
+keyring = VaultKeyring(_explicit_keys.copy(), detect_available_keys=config.detect_keys, default_salt=config.fixed_salt)
 
 if config.encryption_key:
     keyring.default_encryption_key = keyring.key_by_id(config.encryption_key)
@@ -575,6 +595,8 @@ try:
     debug(f"Encryption key: { keyring.encryption_key.id }")
 except:
     debug('Encryption key: unavailable')
+if config.fixed_salt:
+    debug(f"Using fixed encryption salt: { config.fixed_salt }")
 
 # Set up logging
 
@@ -690,7 +712,6 @@ if config.command in [ 'create', 'edit' ]:
                     def _find_new_plain_vars(path: tuple[Hashable, ...], value: Any) -> Any:
                         if path != ( SENTINEL_KEY, ) and type(value) is not EncryptedVar:
                             if (old_value := vault.get(path, default=Unset)) != value:
-                                std_print(path[-1], type(old_value), type(value))
                                 if type(old_value) is EncryptedVar:
                                     decrypted_vars.append(path)
                                 else:
@@ -822,6 +843,21 @@ if config.command in [ 'encrypt', 'decrypt', 'is-encrypted' ]:
             else:
                 print(f"Value is { 'encrypted' if is_encrypted else 'plain' }.", Color.GOOD if is_encrypted else Color.MEH)
 
+# Rekey command
+
+if config.command == 'rekey':
+    vault_path: str = resolve_vault_path(config.vault_path)
+    if not config.encryption_key:
+        print(f"No explicit encryption key specified, falling back to '{ keyring.encryption_key.id }'", Color.MEH)
+    # Since ciphers are usually not changed from load to save, we force re-encryption by loading from an editable
+    vault = VaultFile(vault_path, keyring=keyring)
+    vault = VaultFile.from_editable(vault, vault.as_editable())
+    vault.save()
+    print(
+        f"Re-encrypted vault with key '{ keyring.encryption_key.id }' and a { 'fixed' if config.fixed_salt else 'random' } salt",
+        Color.GOOD
+    )
+
 # Convert command
 
 if config.command == 'convert':

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/src/ansible_vars/util.py

@@ -338,7 +338,7 @@ class VaultDaemon(FileSystemEventHandler):
                         content: str = src.read()
                     with open(self.target_file, 'w') as tgt:
                         try:
-                            tgt.write(Vault(content, keyring=self.keyring).as_editable(with_header=False))
+                            tgt.write(Vault(content, keyring=self.keyring).as_plain())
                             self.debug(f"Created/Updated file { self.target_file } from vault contents")
                         except:
                             tgt.write(content)
@@ -373,7 +373,7 @@ class VaultDaemon(FileSystemEventHandler):
                 content: str = src.read()
             with open(target_path, 'w') as tgt:
                 try:
-                    tgt.write(Vault(content, keyring=self.keyring).as_editable(with_header=False))
+                    tgt.write(Vault(content, keyring=self.keyring).as_plain())
                     self.debug(f"Created/Updated file { target_path } from vault contents")
                 except:
                     tgt.write(content)

{ansible_vars-1.0.7 → ansible_vars-1.0.9}/src/ansible_vars/vault_crypt.py

@@ -54,12 +54,12 @@ class VaultKey():
         '''
         return VaultLib.is_encrypted(VaultKey._strip_vault_tag(test_me))
 
-    def encrypt(self, plain: str) -> str:
-        '''Encrypts a string using this `VaultKey`'s secret.'''
+    def encrypt(self, plain: str, salt: str | None = None) -> str:
+        '''Encrypts a string using this `VaultKey`'s secret. You can specify an optional fixed salt (ideally 32+ chars).'''
         # Pass our secret directly to the encrypt call to skip expensive secret matching
         # Beware: the encrypt function takes a `secret`, but means just the VaultSecret and not a tuple of (vault_id, VaultSecret)
         # In other calls, `secret` or `secrets` may refer to the tuple(s)
-        return self._vaultlib.encrypt(plain, secret=self.secret, vault_id=self.id).decode('utf-8').strip()
+        return self._vaultlib.encrypt(plain, secret=self.secret, vault_id=self.id, salt=salt).decode('utf-8').strip()
 
     def decrypt(self, vault_cipher: str) -> str:
         '''
@@ -96,6 +96,7 @@ class VaultKeyring():
             self,
             keys: list[VaultKey] | None = None,
             default_encryption_key: VaultKey | None = None,
+            default_salt: str | None = None,
             detect_available_keys: bool = True
         ) -> None:
         '''
@@ -107,9 +108,13 @@ class VaultKeyring():
         
         When encrypting data, you can specify an explicit `VaultKey` to use. If none is specified, `default_encryption_key` is used.
         If no explicit or default keys are available, the first key of the `keys` parameter is used.
+
+        You can also set a fixed salt to use for encryption tasks, either passing it to the `encrypt` function directly
+        or as a `default_salt` here. A length of at least 32 chars is recommended for Ansible's AES-256.
         '''
         self.keys: list[VaultKey] = keys or []
         self.default_encryption_key: VaultKey | None = default_encryption_key
+        self.default_salt: str | None = default_salt
         if detect_available_keys:
             self.keys.extend(VaultKeyring.load_cli_secrets())
     
@@ -124,16 +129,15 @@ class VaultKeyring():
             raise NoVaultKeysError('No vault keys available for encryption')
         return self.default_encryption_key or self.keys[0]
 
-    def encrypt(self, plain: str, key: VaultKey | None = None) -> str:
+    def encrypt(self, plain: str, key: VaultKey | None = None, salt: str | None = None) -> str:
         '''
         Encrypts the given vault data using the supplied `VaultKey`.
         If no key is supplied, the `VaultKeyring`'s `default_encryption_key` is used.
         If that key is also unset, the first key of the `VaultKeyring`'s `keys` is used.
+        You can specify an optional fixed salt for encrypting (ideally 32+ chars).
         '''
         # If no key is provided, use the default encryption key or first key in `keys`
-        if not key:
-            key = self.encryption_key
-        return key.encrypt(plain)
+        return (key or self.encryption_key).encrypt(plain, salt=(salt or self.default_salt))
 
     def decrypt(self, vault_cipher: str, key: VaultKey | None = None) -> str:
         '''
@@ -143,7 +147,7 @@ class VaultKeyring():
 
         Expects a cipher with optional YAML tag preamble (`!vault | $ANSIBLE_VAULT;<options>\\n<cipher>`).
         '''
-        if not key and not self.keys:
+        if not (key or self.keys):
             raise NoVaultKeysError('No vault keys available for decryption')
         if key:
             return key.decrypt(vault_cipher)