MDL-71420 environment: Add some strategic comments and todos.

This isn't really a deprecations where something is replaced
by another and all uses must adapt to. Instead it's just a
fallback functionality that will stop working in Moodle 4.2.

Because of that, I've tried to add TODO/@todo comments to
the places that will need to modified, always pointing to
MDL-71421 that is where the removal will happen.

Also, haven't added any debugging() output, after thinking
a lot about it, because this isn't anything that developers
can be using but a internal implementation detail (a fallback)
that we want to remove in some versions.

admin/cli/generate_key.php

@@ -39,6 +39,8 @@ if ($unrecognized) {
     cli_error(get_string('cliunknowoption', 'admin', $unrecognized));
 }
 
+// TODO: MDL-71421 - Remove the openssl alternative once sodium becomes a requirement in Moodle 4.2.
+
 if ($options['help']) {
     echo "Generate secure key
 

lib/classes/encryption.php

@@ -30,10 +30,15 @@ namespace core;
  * @package core
  * @copyright 2020 The Open University
  * @license http://www.gnu.org/copyleft/gpl.html GNU GPL v3 or later
+ * @deprecated since Moodle 3.11 MDL-71420 - the openssl part of the class only.
+ * @todo MDL-71421 Remove the openssl part in Moodle 4.2.
  */
 class encryption {
     /** @var string Encryption method: Sodium */
     const METHOD_SODIUM = 'sodium';
+
+    // TODO: MDL-71421 - Remove the following openssl constants and all uses once sodium becomes a requirement in Moodle 4.2.
+
     /** @var string Encryption method: hand-coded OpenSSL (less safe) */
     const METHOD_OPENSSL = 'openssl-aes-256-ctr';
 

lib/upgrade.txt

@@ -79,6 +79,8 @@ information provided here is intended especially for developers.
   default the key is stored in moodledata but admins can configure a different, more secure
   location in config.php if required. To get the best possible security for this feature, we
   recommend enabling the Sodium PHP extension.
+  The OpenSSL alternative for this API, used when Sodium is not available, is considered deprecated
+  at all effects, and will be removed in Moodle 4.2. See MDL-71421 for more information.
 * Behat timeout constants behat_base::TIMEOUT, EXTENDED_TIMEOUT, and REDUCED_TIMEOUT, which were deprecated in 3.7, have been removed.
 * \core_table\local\filter\filterset::JOINTYPE_DEFAULT is being changed from 1 (ANY) to 2 (ALL). Filterset implementations
   can override the default filterset join type by overriding \core_table\local\filter\filterset::get_join_type() instead.