From 562e739408ce4aef14400dc6aea91c12a3f5c425 Mon Sep 17 00:00:00 2001 From: jeanluc Date: Tue, 5 Mar 2024 09:45:23 +0100 Subject: [PATCH] Correct docstrings --- salt/states/gpg.py | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/salt/states/gpg.py b/salt/states/gpg.py index 596678fd5f0..34e45c3ffcb 100644 --- a/salt/states/gpg.py +++ b/salt/states/gpg.py @@ -70,28 +70,35 @@ def present( .. versionadded:: 3007.0 source - A path/URI or list of paths/URI to retrieve the key from. - By default, this works as a backup to retrieving the key from - the keyserver. + A (list of) path(s)/URI to retrieve the key(s) from. + By default, this works as a backup option in case retrieving a key + from the keyserver fails. .. note:: - This works like the ``source`` parameter to ``file.managed``. - Only the first succesfully retrievable source is taken into account. + All listed sources will be iterated over in order until the first one found + to contain the requested key. If multiple keys are managed in a single + state, the effective sources are allowed to differ between keys. + + .. important:: + Internally, this uses :py:func:`gpg.read_key ` + to list keys in the sources. If a source is not a keyring, on GnuPG <2.1, + this can lead to unintentional decryption. .. versionadded:: 3008.0 skip_keyserver Do not attempt to retrieve the key from the keyserver, only use ``source``. - Defaults to false. + Irrelevant when ``text`` is passed. Defaults to false. .. versionadded:: 3008.0 text - Instead of retrieving the key(s) to import from a keyserver or - a local file source, import the key(s) from this (armored) string. + Instead of retrieving the key(s) to import from a keyserver/URI, + import them from this (armored) string. .. note:: - ``name`` or ``keys`` must still specify the expected key ID(s). + ``name`` or ``keys`` must still specify the expected key ID(s), + so this cannot be used to indiscriminately import a keyring. Requires python-gnupg v0.5.1. .. versionadded:: 3008.0