luks_device: allow to provide passphrases base64-encoded

[felixfontein]

SUMMARY

Fixes #827.

ISSUE TYPE

• Feature Pull Request

COMPONENT NAME

luks_device

[github-actions]

Docs Build 📝

Thank you for contribution!✨

The docs for this PR have been published here:
https://ansible-collections.github.io/community.crypto/pr/829

You can compare to the docs for the main branch here:
https://ansible-collections.github.io/community.crypto/branch/main

The docsite for this PR is also available for download as an artifact from this run:
https://github.com/ansible-collections/community.crypto/actions/runs/12528355951

File changes:

• M luks_device_module.html

Click to see the diff comparison.

NOTE: only file modifications are shown here. New and deleted files are excluded.
See the file list and check the published docs to see those files.

diff --git a/home/runner/work/community.crypto/community.crypto/docsbuild/base/luks_device_module.html b/home/runner/work/community.crypto/community.crypto/docsbuild/head/luks_device_module.html
index 27c93cd..000d867 100644
--- a/home/runner/work/community.crypto/community.crypto/docsbuild/base/luks_device_module.html
+++ b/home/runner/work/community.crypto/community.crypto/docsbuild/head/luks_device_module.html
@@ -340,6 +340,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </div></td>
 <td><div class="ansible-option-cell"><p>Adds additional passphrase to given container on <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-device"><span class="std std-ref"><span class="pre">device</span></span></a></strong></code>. Needs <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-keyfile"><span class="std std-ref"><span class="pre">keyfile</span></span></a></strong></code> or <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase"><span class="std std-ref"><span class="pre">passphrase</span></span></a></strong></code> option for authorization. LUKS container supports up to 8 keyslots. Parameter value is a string with the new passphrase.</p>
 <p>NOTE that adding additional passphrase is idempotent only since community.crypto 1.4.0. For older versions, a new keyslot will be used even if another keyslot already exists for this passphrase.</p>
+<p><strong>Note</strong> that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase-encoding"><span class="std std-ref"><span class="pre">passphrase_encoding</span></span></a></strong></code> option and provide the passphrase Base64 encoded.</p>
 </div></td>
 </tr>
 <tr class="row-odd"><td><div class="ansible-option-cell">
@@ -348,9 +349,28 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p><em class="ansible-option-versionadded">added in community.crypto 1.0.0</em></p>
 </div></td>
 <td><div class="ansible-option-cell"><p>Used to unlock the container. Either a <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase"><span class="std std-ref"><span class="pre">passphrase</span></span></a></strong></code> or a <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-keyfile"><span class="std std-ref"><span class="pre">keyfile</span></span></a></strong></code> is needed for most of the operations. Parameter value is a string with the passphrase.</p>
+<p><strong>Note</strong> that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase-encoding"><span class="std std-ref"><span class="pre">passphrase_encoding</span></span></a></strong></code> option and provide the passphrase Base64 encoded.</p>
 </div></td>
 </tr>
 <tr class="row-even"><td><div class="ansible-option-cell">
+<div class="ansibleOptionAnchor" id="parameter-passphrase_encoding"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-passphrase-encoding"><strong>passphrase_encoding</strong></p>
+<a class="ansibleOptionLink" href="#parameter-passphrase_encoding" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
+<p><em class="ansible-option-versionadded">added in community.crypto 2.23.0</em></p>
+</div></td>
+<td><div class="ansible-option-cell"><p>Determine how passphrases are provided to parameters such as <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase"><span class="std std-ref"><span class="pre">passphrase</span></span></a></strong></code>, <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-new-passphrase"><span class="std std-ref"><span class="pre">new_passphrase</span></span></a></strong></code>, and <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-remove-passphrase"><span class="std std-ref"><span class="pre">remove_passphrase</span></span></a></strong></code>.</p>
+<p>Please note that binary passphrases cannot contain all possible binary octets. For example, a newline (0x0A) cannot be used since it indicates that the passphrase is over. If you want to use arbitrary binary data, you must use keyfiles.</p>
+<p class="ansible-option-line"><strong class="ansible-option-choices">Choices:</strong></p>
+<ul>
+<li><p><code class="ansible-option-choices-entry docutils literal notranslate"><span class="pre">&quot;base64&quot;</span></code>:
+The passphrase is provided as Base64 encoded bytes.</p>
+<p>Use the <a class="reference external" href="https://docs.ansible.com/ansible/devel/collections/ansible/builtin/b64encode_filter.html#ansible-collections-ansible-builtin-b64encode-filter" title="(in Ansible vdevel)"><span class="xref std std-ref">ansible.builtin.b64encode</span></a> filter to Base64-encode binary data.</p>
+</li>
+<li><p><code class="ansible-option-default-bold docutils literal notranslate"><strong><span class="pre">&quot;text&quot;</span></strong></code> <span class="ansible-option-choices-default-mark">(default)</span>:
+The passphrase is provided as UTF-8 encoded text.</p></li>
+</ul>
+</div></td>
+</tr>
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf"><strong>pbkdf</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">dictionary</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.4.0</em></p>
@@ -359,7 +379,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>Will only be used on container creation, and when adding keys to an existing container.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf/algorithm"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-algorithm"><strong>algorithm</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf/algorithm" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 </div></td>
@@ -373,7 +393,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf/iteration_count"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-iteration-count"><strong>iteration_count</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf/iteration_count" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -381,7 +401,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>Mutually exclusive with <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-iteration-time"><span class="std std-ref"><span class="pre">pbkdf.iteration_time</span></span></a></strong></code>.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf/iteration_time"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-iteration-time"><strong>iteration_time</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf/iteration_time" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">float</span></p>
 </div></td>
@@ -390,7 +410,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>Mutually exclusive with <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-iteration-count"><span class="std std-ref"><span class="pre">pbkdf.iteration_count</span></span></a></strong></code>.</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf/memory"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-memory"><strong>memory</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf/memory" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -398,7 +418,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>This is not used for PBKDF2, but only for the Argon PBKDFs.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-indent"></div><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-pbkdf/parallel"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-pbkdf-parallel"><strong>parallel</strong></p>
 <a class="ansibleOptionLink" href="#parameter-pbkdf/parallel" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 </div></td>
@@ -406,7 +426,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>This is not used for PBKDF2, but only for the Argon PBKDFs.</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-perf_no_read_workqueue"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-perf-no-read-workqueue"><strong>perf_no_read_workqueue</strong></p>
 <a class="ansibleOptionLink" href="#parameter-perf_no_read_workqueue" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.3.0</em></p>
@@ -420,7 +440,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-perf_no_write_workqueue"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-perf-no-write-workqueue"><strong>perf_no_write_workqueue</strong></p>
 <a class="ansibleOptionLink" href="#parameter-perf_no_write_workqueue" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.3.0</em></p>
@@ -434,7 +454,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-perf_same_cpu_crypt"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-perf-same-cpu-crypt"><strong>perf_same_cpu_crypt</strong></p>
 <a class="ansibleOptionLink" href="#parameter-perf_same_cpu_crypt" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.3.0</em></p>
@@ -449,7 +469,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-perf_submit_from_crypt_cpus"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-perf-submit-from-crypt-cpus"><strong>perf_submit_from_crypt_cpus</strong></p>
 <a class="ansibleOptionLink" href="#parameter-perf_submit_from_crypt_cpus" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.3.0</em></p>
@@ -465,7 +485,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-persistent"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-persistent"><strong>persistent</strong></p>
 <a class="ansibleOptionLink" href="#parameter-persistent" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">boolean</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.3.0</em></p>
@@ -480,7 +500,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-remove_keyfile"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-remove-keyfile"><strong>remove_keyfile</strong></p>
 <a class="ansibleOptionLink" href="#parameter-remove_keyfile" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">path</span></p>
 </div></td>
@@ -490,7 +510,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>BEWARE that working with keyfiles in plaintext is dangerous. Make sure that they are protected.</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-remove_keyslot"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-remove-keyslot"><strong>remove_keyslot</strong></p>
 <a class="ansibleOptionLink" href="#parameter-remove_keyslot" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 2.16.0</em></p>
@@ -500,7 +520,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p><strong>Note</strong> that the given <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-keyfile"><span class="std std-ref"><span class="pre">keyfile</span></span></a></strong></code> or <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase"><span class="std std-ref"><span class="pre">passphrase</span></span></a></strong></code> must not be in the slot to be removed.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-remove_passphrase"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-remove-passphrase"><strong>remove_passphrase</strong></p>
 <a class="ansibleOptionLink" href="#parameter-remove_passphrase" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.0.0</em></p>
@@ -508,9 +528,10 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <td><div class="ansible-option-cell"><p>Removes given passphrase from the container on <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-device"><span class="std std-ref"><span class="pre">device</span></span></a></strong></code>. Parameter value is a string with the passphrase to remove.</p>
 <p>NOTE that removing passphrases is idempotent only since community.crypto 1.4.0. For older versions, trying to remove a passphrase which no longer exists results in an error.</p>
 <p>NOTE that to remove the last keyslot from a LUKS container, the <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-force-remove-last-key"><span class="std std-ref"><span class="pre">force_remove_last_key</span></span></a></strong></code> option must be set to <code class="ansible-value docutils literal notranslate"><span class="pre">true</span></code>.</p>
+<p><strong>Note</strong> that the passphrase must be UTF-8 encoded text. If you want to use arbitrary binary data, or text using another encoding, use the <code class="ansible-option docutils literal notranslate"><strong><a class="reference internal" href="#ansible-collections-community-crypto-luks-device-module-parameter-passphrase-encoding"><span class="std std-ref"><span class="pre">passphrase_encoding</span></span></a></strong></code> option and provide the passphrase Base64 encoded.</p>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-sector_size"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-sector-size"><strong>sector_size</strong></p>
 <a class="ansibleOptionLink" href="#parameter-sector_size" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">integer</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.5.0</em></p>
@@ -519,7 +540,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 <p>Will only be used on container creation.</p>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-state"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-state"><strong>state</strong></p>
 <a class="ansibleOptionLink" href="#parameter-state" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 </div></td>
@@ -537,7 +558,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-even"><td><div class="ansible-option-cell">
+<tr class="row-odd"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-type"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-type"><strong>type</strong></p>
 <a class="ansibleOptionLink" href="#parameter-type" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.0.0</em></p>
@@ -550,7 +571,7 @@ see <a class="reference internal" href="#ansible-collections-community-crypto-lu
 </ul>
 </div></td>
 </tr>
-<tr class="row-odd"><td><div class="ansible-option-cell">
+<tr class="row-even"><td><div class="ansible-option-cell">
 <div class="ansibleOptionAnchor" id="parameter-uuid"></div><p class="ansible-option-title" id="ansible-collections-community-crypto-luks-device-module-parameter-uuid"><strong>uuid</strong></p>
 <a class="ansibleOptionLink" href="#parameter-uuid" title="Permalink to this option"></a><p class="ansible-option-type-line"><span class="ansible-option-type">string</span></p>
 <p><em class="ansible-option-versionadded">added in community.crypto 1.0.0</em></p>

[russoz]

curiousity, what tripped the test? text as a value?

[felixfontein]

Nope, choices as a dictionary in DOCUMENTATION.

[russoz]

Why is that not allowed? It makes the docs better!

[felixfontein]

It's only allowed since ansible-core 2.17; before it wasn't allowed. That's why I had to add it to the ignore files for 2.9 ... 2.16, but not to 2.17 and 2.18 and devel/2.19 :)

[russoz]

LGTM

[felixfontein]

@russoz thanks for reviewing this!