Improve notification and documentation of deprecated features

doc/deprecated.rst

@@ -46,13 +46,26 @@ in a future major release:
   TLS PSKs for given identities and hosts. Instead, use the dedicated methods in
   ``Credentials_Manager`` and do not override the ``psk()`` method any longer.
 
-Deprecated Functionality
+Elliptic Curve Deprecations
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-This section lists cryptographic functionality which will be removed
-in a future major release.
+A number of features relating to elliptic curves are deprecated.  As a typical
+user you would probably not notice these; their removal would not affect for
+example using ECDSA signatures or TLS, but only applications doing usual things
+such as custom elliptic curve parameters, or creating your own protocol using
+elliptic curve points.
 
-- Kyber 90s mode is deprecated and will be removed.
+- Support for explicit ECC curve parameters and ImplicitCA encoded parameters in
+  ``EC_Group`` and all users (including X.509 certificates and PKCS#8 private keys).
+
+- Currently it is possible to create an ``EC_Group`` with cofactor > 1. None of
+  the builtin groups have composite order, and in the future it will be
+  impossible to create composite order ``EC_Group``.
+
+- Currently it is possible to create an application specific ``EC_Group``
+  with parameters of effectively arbitrary size. In a future release
+  the maximum allowed bitlength of application provided groups will be
+  at most 521 bits.
 
 - Elliptic curve points can be encoded in several different ways.  The
   most common are "compressed" and "uncompressed"; both are widely
@@ -62,14 +75,68 @@ in a future major release.
   format is quite obscure and seemingly rarely implemented. Support
   for this encoding will be removed in a future release.
 
-- Currently it is possible to create an EC_Group with cofactor > 1.
-  None of the builtin groups have composite order, and in the future
-  it will be impossible to create composite order EC_Groups.
+- Botan currently contains support for a number of relatively weak or little
+  used elliptic curves. These are deprecated. These include "secp160k1",
+  "secp160r1", "secp160r2", "secp192k1", "secp224k1", "brainpool160r1",
+  "brainpool192r1", "brainpool224r1", "brainpool320r1", "x962_p192v2",
+  "x962_p192v3", "x962_p239v1", "x962_p239v2", "x962_p239v3"
 
-- Currently it is possible to create an application specific EC_Group
-  with parameters of effectively arbitrary size. In a future release
-  the maximum allowed bitlength of application provided groups will be
-  at most 521 bits.
+Deprecated Modules
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In a number of cases an entire module is deprecated. If the build is configured
+with ``--disable-deprecated`` then these will not be included. In a future major
+release the source for these modules will be entirely removed.
+
+Deprecated modules include
+
+- Kyber mode ``kyber_90s``: Kyber's "90s mode" is not in the NIST ML-KEM
+  standard, and seems to have been never implemented widely.
+
+- Dilithium mode ``dilithium_aes``: Similar situation to Kyber 90s mode.
+
+- Block cipher ``gost_28147``: This cipher was obsolete 20 years ago.
+
+- Block cipher ``noekeon``: An interesting design but not widely implemented.
+
+- Block cipher ``lion``: Similar situation to Noekeon
+
+- Hash function ``gost_3411``: Very weak and questionable hash function.
+
+- Hash function ``streebog``: Incredibly sketchy situation with the sbox
+
+- Hash function ``md4``: It's time to let go
+
+- Signature scheme ``gost_3410``
+
+- McEliece implementation ``mce``. Will be replaced by the proposal Classic
+  McEliece.
+
+- Stream cipher ``shake_cipher``. Note this deprecation affects only
+  using SHAKE as a ``StreamCipher`` not as a hash or XOF
+
+- `cryptobox`: A not unreasonable password based encryption utility
+  but neither modern (these days) nor widely implemented.
+
+- ``dlies``: DLIES is considered quite obsolete
+
+- ``tpm`` (TPM 1.2 only, rarely tested)
+
+Other Deprecated Functionality
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+This section lists other functionality which will be removed in a future major
+release, or where a backwards incompatible change is expected.
+
+- The ``PBKDF`` class is deprecated in favor of ``PasswordHash`` and
+  ``PasswordHashFamily``.
+
+- Implicit conversion of a private key into a public key. Currently
+  ``Private_Key`` derives from ``Public_Key`` (and likewise for each of the
+  algorithm specfic classes, eg ``RSA_PrivateKey`` derives from
+  ``RSA_PublicKey``). In a future release these derivations will not exist. To
+  correctly extract the public key from a private key, use the function
+  ``Private_Key::public_key()``
 
 - Prior to 2.8.0, SM2 algorithms were implemented as two distinct key
   types, one used for encryption and the other for signatures. In 2.8,
@@ -81,36 +148,16 @@ in a future major release.
   required that the hash be named as "EMSA1(HASH_NAME)". This is no longer
   required. In a future major release, only "HASH_NAME" will be accepted.
 
-- Block cipher GOST 28147, Noekeon, Lion
-
-- Hash function GOST 34.11-94, Streebog, MD4
-
-- GOST 34.10 signature scheme
-
-- Stream cipher SHAKE (this does not affect SHAKE used as a HashFunction or XOF)
-
-- The utility functions in cryptobox.h
-
-- X9.42 KDF
-
-- The current McEliece implementation (in ``pubkey/mce``) will be
-  replaced by a more modern code-based KEM from the NIST
-  competition. (Probably the "Classic McEliece" submission.)
-
-- DLIES
+- The ``Buffered_Computation`` base class. In a future release the
+  class will be removed, and all of member functions instead declared
+  directly on ``MessageAuthenticationCode`` and ``HashFunction``. So
+  this only affects you if you are directly referencing
+  ``Botan::Buffered_Computation`` in some way.
 
 - GCM support for 64-bit tags
 
-- Weak or rarely used ECC builtin groups including "secp160k1", "secp160r1",
-  "secp160r2", "secp192k1", "secp224k1",
-  "brainpool160r1", "brainpool192r1", "brainpool224r1", "brainpool320r1",
-  "x962_p192v2", "x962_p192v3", "x962_p239v1", "x962_p239v2", "x962_p239v3".
-
 - All built in MODP groups < 2048 bits
 
-- Support for explicit ECC curve parameters and ImplicitCA encoded parameters in
-  EC_Group and all users (including X.509 certificates and PKCS#8 private keys).
-
 - All pre-created DSA groups
 
 - All support for loading, generating or using RSA keys with a public
@@ -119,6 +166,9 @@ in a future major release.
 Deprecated Headers
 ^^^^^^^^^^^^^^^^^^^^^^
 
+These headers are currently publically available, but will be made
+internal to the library in the future.
+
   PBKDF headers: ``bcrypt_pbkdf.h``, ``pbkdf2.h``, ``pgp_s2k.h``, ``scrypt.h``,
   and ``argon2.h``: Use the ``PasswordHash`` interface instead.
 
@@ -133,15 +183,3 @@ Deprecated Headers
   to implement other functionality.
   ``compiler.h``,
   ``uuid.h``,
-
-Other API deprecations
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-- The ``PBKDF`` class is deprecated in favor of ``PasswordHash`` and
-  ``PasswordHashFamily``.
-
-- The ``Buffered_Computation`` base class. In a future release the
-  class will be removed, and all of member functions instead declared
-  directly on ``MessageAuthenticationCode`` and ``HashFunction``. So
-  this only affects you if you are directly referencing
-  ``Botan::Buffered_Computation`` in some way.

src/lib/block/gost_28147/info.txt

@@ -4,4 +4,5 @@ GOST_28147_89 -> 20131128
 
 <module_info>
 name -> "GOST 28147-89"
+lifecycle -> "Deprecated"
 </module_info>

src/lib/block/lion/info.txt

@@ -4,6 +4,7 @@ LION -> 20131128
 
 <module_info>
 name -> "Lion"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/block/noekeon/info.txt

@@ -4,4 +4,5 @@ NOEKEON -> 20131128
 
 <module_info>
 name -> "Noekeon"
+lifecycle -> "Deprecated"
 </module_info>

src/lib/hash/md4/info.txt

@@ -4,6 +4,7 @@ MD4 -> 20131128
 
 <module_info>
 name -> "MD4"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/hash/streebog/info.txt

@@ -4,4 +4,5 @@ STREEBOG -> 20170623
 
 <module_info>
 name -> "Streebog"
+lifecycle -> "Deprecated"
 </module_info>

src/lib/kdf/prf_x942/info.txt

@@ -4,6 +4,7 @@ X942_PRF -> 20131128
 
 <module_info>
 name -> "PRF X9.42"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/math/numbertheory/reducer.h

@@ -10,6 +10,8 @@
 
 #include <botan/numthry.h>
 
+BOTAN_FUTURE_INTERNAL_HEADER(reducer.h)
+
 namespace Botan {
 
 /**

src/lib/pbkdf/pbkdf.h

@@ -37,13 +37,15 @@ class BOTAN_PUBLIC_API(2, 0) PBKDF {
       * @param provider provider implementation to choose
       * @return a null pointer if the algo/provider combination cannot be found
       */
+      BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
       static std::unique_ptr<PBKDF> create(std::string_view algo_spec, std::string_view provider = "");
 
       /**
       * Create an instance based on a name, or throw if the
       * algo/provider combination cannot be found. If provider is
       * empty then best available is chosen.
       */
+      BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
       static std::unique_ptr<PBKDF> create_or_throw(std::string_view algo_spec, std::string_view provider = "");
 
       /**

src/lib/pbkdf/pbkdf2/pbkdf2.h

@@ -123,6 +123,8 @@ class BOTAN_PUBLIC_API(2, 0) PKCS5_PBKDF2 final : public PBKDF {
       * Create a PKCS #5 instance using the specified message auth code
       * @param mac_fn the MAC object to use as PRF
       */
+      BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash")
+
       explicit PKCS5_PBKDF2(std::unique_ptr<MessageAuthenticationCode> mac_fn) : m_mac(std::move(mac_fn)) {}
 
    private:

src/lib/prov/tpm/info.txt

@@ -5,6 +5,7 @@ TPM -> 20151126
 <module_info>
 name -> "TPM"
 brief -> "Wrappers and Utilites to interact with TPMs"
+lifecycle -> "Deprecated"
 </module_info>
 
 load_on vendor

src/lib/prov/tpm/tpm.h

@@ -16,6 +16,8 @@
 #include <botan/uuid.h>
 #include <functional>
 
+BOTAN_DEPRECATED_HEADER("tpm.h")
+
 //TODO remove this
 #include <tss/tspi.h>
 
@@ -46,6 +48,7 @@ class BOTAN_PUBLIC_API(2, 0) TPM_Context final {
       */
       typedef std::function<std::string(std::string)> pin_cb;
 
+      BOTAN_DEPRECATED("TPM support is deprecated see #3877")
       TPM_Context(pin_cb cb, const char* srk_password);
 
       ~TPM_Context();

src/lib/pubkey/dilithium/dilithium_aes/info.txt

@@ -4,6 +4,7 @@ DILITHIUM_AES -> 20221018
 
 <module_info>
 name -> "Dilithium (AES)"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/pubkey/dlies/dlies.h

@@ -15,6 +15,8 @@
 #include <botan/mac.h>
 #include <botan/pubkey.h>
 
+BOTAN_DEPRECATED_HEADER("dlies.h")
+
 namespace Botan {
 
 /**

src/lib/pubkey/dlies/info.txt

@@ -4,6 +4,7 @@ DLIES -> 20160713
 
 <module_info>
 name -> "DLIES"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/pubkey/gost_3410/info.txt

@@ -5,6 +5,7 @@ GOST_34_10_2012 -> 20190801
 
 <module_info>
 name -> "GOST 34.10-2001"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/pubkey/kyber/kyber_round3/kyber_90s/info.txt

@@ -4,6 +4,7 @@ KYBER_90S -> 20220107
 
 <module_info>
 name -> "Kyber 90s"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/pubkey/mce/info.txt

@@ -4,6 +4,7 @@ MCELIECE -> 20150922
 
 <module_info>
 name -> "McEliece"
+lifecycle -> "Deprecated"
 </module_info>
 
 <header:public>

src/lib/pubkey/mce/mceliece.h

@@ -14,6 +14,8 @@
 
 #include <botan/pk_keys.h>
 
+BOTAN_DEPRECATED_HEADER("mceliece.h")
+
 namespace Botan {
 
 typedef uint16_t gf2m;

src/lib/stream/shake_cipher/info.txt

@@ -5,6 +5,7 @@ SHAKE_CIPHER -> 20161018
 <module_info>
 name -> "SHAKE-based XOFs"
 brief -> "SHAKE-128 and SHAKE-256 XOF presented as stream ciphers"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

src/lib/utils/uuid/uuid.h

@@ -12,7 +12,7 @@
 #include <string>
 #include <vector>
 
-//BOTAN_FUTURE_INTERNAL_HEADER(uuid.h)
+BOTAN_DEPRECATED_HEADER("uuid.h")
 
 namespace Botan {