Deprecation warning for grains.get_or_set_hash w/ docs guidance on avoiding grains storage for secrets

CONTRIBUTING.rst

@@ -488,7 +488,7 @@ PR Time!
 
 Once you’ve done all your dev work and tested locally, you should check
 out our `PR
-guidelines <https://docs.saltproject.io/en/develop/topics/development/pull_requests.html>`__.
+guidelines <https://docs.saltproject.io/en/master/topics/development/pull_requests.html>`__.
 After you read that page, it’s time to `open a new
 PR <https://github.com/saltstack/salt/compare>`__. Fill out the PR
 template - you should have updated or created any necessary docs, and

SUPPORT.rst

@@ -25,7 +25,7 @@ salt-users@googlegroups.com
 
 **Reporting Issues** - To report an issue with Salt, please follow the
 guidelines for filing bug reports:
-`<https://docs.saltstack.com/en/develop/topics/development/reporting_bugs.html>`_
+`<https://docs.saltstack.com/en/master/topics/development/reporting_bugs.html>`_
 
 **SaltStack Support** - If you need dedicated, prioritized support, please
 consider a SaltStack Support package that fits your needs:

changelog/59425.deprecated

@@ -0,0 +1 @@
+Added deprecation warning for grains.get_or_set_hash

doc/_incl/grains_passwords.rst

@@ -0,0 +1,6 @@
+.. warning::
+
+   Grains can be set by users that have access to the minion configuration files on
+   the local system, making them less secure than other identifiers in Salt. Avoid
+   storing sensitive data, such as passwords or keys, on minions. Instead, make
+   use of :ref:`pillar` and/or :ref:`sdb`.

doc/faq.rst

@@ -456,6 +456,8 @@ state could be done the same way as for the Salt minion described :ref:`above
 Is Targeting using Grain Data Secure?
 -------------------------------------
 
+.. include:: _incl/grains_passwords.rst
+
 Because grains can be set by users that have access to the minion configuration
 files on the local system, grains are considered less secure than other
 identifiers in Salt. Use caution when targeting sensitive operations or setting

doc/topics/best_practices.rst

@@ -22,6 +22,7 @@ General rules
 5. Don't use grains for matching in your pillar top file for any sensitive
    pillars.
 
+   .. include:: ../_incl/grains_passwords.rst
 
 Structuring States and Formulas
 -------------------------------

doc/topics/grains/index.rst

@@ -125,6 +125,8 @@ For this example to work, you would need to have defined the grain
 Writing Grains
 ==============
 
+.. include:: ../../_incl/grains_passwords.rst
+
 The grains are derived by executing all of the "public" functions (i.e. those
 which do not begin with an underscore) found in the modules located in the
 Salt's core grains code, followed by those in any custom grains modules. The

doc/topics/hardening.rst

@@ -50,6 +50,8 @@ General hardening tips
 Salt hardening tips
 ===================
 
+.. include:: ../_incl/grains_passwords.rst
+
 - Subscribe to `salt-users`_ or `salt-announce`_ so you know when new Salt
   releases are available.
 - Keep your systems up-to-date with the latest patches.

pkg/rpm/README.fedora

@@ -8,4 +8,4 @@ pymongo
 python-redis / redis
 
 A semi-canonical list of the optional salt modules can be found at
-https://github.com/saltstack/salt/blob/develop/doc/conf.py#L30
+https://github.com/saltstack/salt/blob/master/doc/conf.py under MOCK_MODULES

salt/modules/grains.py

@@ -639,6 +639,13 @@ def get_or_set_hash(
         issues when using the output of this function in an SLS file containing YAML+Jinja,
         surround the call with single quotes.
     """
+    salt.utils.versions.warn_until(
+        "Phosphorus",
+        "The 'grains.get_or_set_hash' function has been deprecated and it's "
+        "functionality will be completely removed. Reference pillar and SDB "
+        "documentation for secure ways to manage sensitive information. Grains "
+        "are an insecure way to store secrets.",
+    )
     ret = get(name, None)
 
     if ret is None: