Repository: ansible/ansible

Issue:
The documentation of ansible lookup plugin's encrypt option is incorrect
<!---
Verify first that your issue/request is not already reported on GitHub.
THIS FORM WILL BE READ BY A MACHINE, COMPLETE ALL SECTIONS AS DESCRIBED.
Also test if the latest release, and devel branch are affected too.
ALWAYS add information AFTER (OUTSIDE) these html comments.
Otherwise it may end up being automatically closed by our bot. -->

##### SUMMARY
<!--- Explain the problem briefly -->
The encrypt option is documented as being boolean, but it is not. It is the name of the encryption method, and apparently to disable encryption it should be set to empty.

##### ISSUE TYPE
 - Bug Report

##### COMPONENT NAME
<!--- Insert, BELOW THIS COMMENT, the name of the module, plugin, task or feature.
Do not include extra details here, e.g. "vyos_command" not "the network module vyos_command" or the full path-->
password

##### ANSIBLE VERSION
<!--- Paste, BELOW THIS COMMENT, verbatim output from "ansible --version" between quotes below -->
```
ansible 2.5.2
  config file = /home/hedayat/projects/devops/kebrit/ansible.cfg
  configured module search path = [u'/home/hedayat/projects/devops/kebrit/third_party/kubespray/library']
  ansible python module location = /usr/lib/python2.7/site-packages/ansible
  executable location = /usr/bin/ansible
  python version = 2.7.15 (default, May 16 2018, 17:50:09) [GCC 8.1.1 20180502 (Red Hat 8.1.1-1)]

```

##### CONFIGURATION
<!--- If using Ansible 2.4 or above, paste, BELOW THIS COMMENT, the results of "ansible-config dump --only-changed"
Otherwise, mention any settings you have changed/added/removed in ansible.cfg
(or using the ANSIBLE_* environment variables).-->

##### OS / ENVIRONMENT
<!--- Mention, BELOW THIS COMMENT, the OS you are running Ansible from, and the OS you are
managing, or say "N/A" for anything that is not platform-specific.
Also mention the specific version of what you are trying to control,
e.g. if this is a network bug the version of firmware on the network device.-->
N/A

##### STEPS TO REPRODUCE
<!--- For bugs, show exactly how to reproduce the problem, using a minimal test-case.
For new features, show how the feature would be used. -->
Just try to use password lookup plugin with encrypt=no or encrypt=false
<!--- Paste example playbooks or commands between quotes below -->
```yaml
command: "echo {{ lookup('password', '/dev/null encrypt=no') }}"
```

<!--- You can also paste gist.github.com links for larger files -->

##### EXPECTED RESULTS
<!--- What did you expect to happen when running the steps above? -->
Generate a plain password rather than an encrypted one

##### ACTUAL RESULTS
<!--- What actually happened? If possible run with extra verbosity (-vvvv) -->
fatal: [test]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'password'. Error was a <class 'ansible.errors.AnsibleError'>, original message: passlib does not support 'no' algorithm"}

<!--- Paste verbatim command output between quotes below -->
```
TASK [test : create db secrets] ************************************************************************************************************
fatal: [test]: FAILED! => {"msg": "An unhandled exception occurred while running the lookup plugin 'password'. Error was a <class 'ansible.errors.AnsibleError'>, original message: passlib does not support 'no' algorithm"}

```



Discussion:
Files identified in the description:
* [lib/ansible/plugins/lookup/password.py](https://github.com/ansible/ansible/blob/devel/lib/ansible/plugins/lookup/password.py)

If these files are inaccurate, please update the `component name` section of the description or use the `!component` bot command.

[click here for bot help](https://github.com/ansible/ansibullbot/blob/master/ISSUE_HELP.md)
<!--- boilerplate: components_banner --->

Resolving patch:
diff --git a/lib/ansible/plugins/lookup/password.py b/lib/ansible/plugins/lookup/password.py
--- a/lib/ansible/plugins/lookup/password.py
+++ b/lib/ansible/plugins/lookup/password.py
@@ -28,11 +28,12 @@
          required: True
       encrypt:
         description:
-           - Whether the user requests that this password is returned encrypted or in plain text.
-           - Note that the password is always stored as plain text.
+           - Which hash scheme to encrypt the returning password, should be one hash scheme from C(passlib.hash).
+           - If not provided, the password will be returned in plain text.
+           - Note that the password is always stored as plain text, only the returning password is encrypted.
            - Encrypt also forces saving the salt value for idempotence.
-        type: boolean
-        default: True
+           - Note that before 2.6 this option was incorrectly labeled as a boolean for a long time.
+        default: None
       chars:
         version_added: "1.4"
         description:
@@ -234,13 +235,13 @@ def _parse_content(content):
     return password, salt
 
 
-def _format_content(password, salt, encrypt=True):
+def _format_content(password, salt, encrypt=None):
     """Format the password and salt for saving
     :arg password: the plaintext password to save
     :arg salt: the salt to use when encrypting a password
-    :arg encrypt: Whether the user requests that this password is encrypted.
+    :arg encrypt: Which method the user requests that this password is encrypted.
         Note that the password is saved in clear.  Encrypt just tells us if we
-        must save the salt value for idempotence.  Defaults to True.
+        must save the salt value for idempotence.  Defaults to None.
     :returns: a text string containing the formatted information
 
     .. warning:: Passwords are saved in clear.  This is because the playbooks


Test patch:
diff --git a/test/units/plugins/lookup/test_password.py b/test/units/plugins/lookup/test_password.py
--- a/test/units/plugins/lookup/test_password.py
+++ b/test/units/plugins/lookup/test_password.py
@@ -333,7 +333,7 @@ def test_no_encrypt_no_salt(self):
         self.assertEqual(
             password._format_content(password=u'hunter42',
                                      salt=None,
-                                     encrypt=False),
+                                     encrypt=None),
             u'hunter42')
 
     def test_encrypt(self):