DOCUMENTATION:
  name: vault
  author: Brian Coca (@bcoca)
  version_added: "2.12"
  short_description: vault your secrets
  description:
    - Put your information into an encrypted Ansible Vault.
  positional: secret
  options:
    _input:
      description: Data to vault.
      type: string
      required: true
    secret:
      description: Vault secret, the key that lets you open the vault.
      type: string
      required: true
    salt:
      description:
        - Encryption salt, will be random if not provided.
        - While providing one makes the resulting encrypted string reproducible, it can lower the security of the vault.
      type: string
    vault_id:
      description: Secret identifier, used internally to try to best match a secret when multiple are provided.
      type: string
      default: 'filter_default'
    wrap_object:
      description:
        - This toggle can force the return of a C(VaultedValue)-tagged string object, when V(False), you get a simple string.
        - Mostly useful when combining with the C(to_yaml) filter to output the 'inline vault' format.
      type: bool
      default: False

EXAMPLES: |
  # Encrypt a value using the vault filter
  vars:
    myvaultedkey: "{{ 'my_secret_key' | vault('my_vault_password') }}"

  # Encrypt a value and save it to a file using the template module
  vars:
    template_data: "{{ 'my_sensitive_data' | vault('another_vault_password', salt=(2**256 | random(seed=inventory_hostname))) }}"

  # The content of dump_template_data.j2 looks like
  #     Encrypted secret: {{ template_data }}
  - name: Save vaulted data
    template:
      src: dump_template_data.j2
      dest: /some/key/vault.txt

RETURN:
  _value:
    description: The vault string that contains the secret data (or C(VaultedValue)-tagged string object).
    type: string
