Improve notification and documentation of deprecated features

In #3910 we introduced a nice way of marking specific modules as deprecated. However this change did not set the lifecycles of any specific modules. Additionally, officially deprecate the TPM support which is pretty obsolete and these days not well tested. (GH #3877) Mark various headers and classes that are entirely deprecated as such to provide some additional compile time warning for users.
randombit · May 11, 2024 · 9000137 · 9000137
1 parent 7606d70
commit 9000137
Show file tree

Hide file tree

Showing 21 changed files with 113 additions and 49 deletions.
diff --git a/doc/deprecated.rst b/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.
diff --git a/src/lib/block/gost_28147/info.txt b/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>
diff --git a/src/lib/block/lion/info.txt b/src/lib/block/lion/info.txt
@@ -4,6 +4,7 @@ LION -> 20131128
 
 <module_info>
 name -> "Lion"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

diff --git a/src/lib/block/noekeon/info.txt b/src/lib/block/noekeon/info.txt
@@ -4,4 +4,5 @@ NOEKEON -> 20131128
 
 <module_info>
 name -> "Noekeon"
+lifecycle -> "Deprecated"
 </module_info>
diff --git a/src/lib/hash/md4/info.txt b/src/lib/hash/md4/info.txt
@@ -4,6 +4,7 @@ MD4 -> 20131128
 
 <module_info>
 name -> "MD4"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

diff --git a/src/lib/hash/streebog/info.txt b/src/lib/hash/streebog/info.txt
@@ -4,4 +4,5 @@ STREEBOG -> 20170623
 
 <module_info>
 name -> "Streebog"
+lifecycle -> "Deprecated"
 </module_info>
diff --git a/src/lib/kdf/prf_x942/info.txt b/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>

diff --git a/src/lib/math/numbertheory/reducer.h b/src/lib/math/numbertheory/reducer.h
@@ -10,6 +10,8 @@
 
 #include <botan/numthry.h>
 
+BOTAN_FUTURE_INTERNAL_HEADER(reducer.h)
+
 namespace Botan {
 
 /**

diff --git a/src/lib/pbkdf/pbkdf.h b/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 = "");
 
       /**

diff --git a/src/lib/pbkdf/pbkdf2/pbkdf2.h b/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:

diff --git a/src/lib/prov/tpm/info.txt b/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

diff --git a/src/lib/prov/tpm/tpm.h b/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();

diff --git a/src/lib/pubkey/dilithium/dilithium_aes/info.txt b/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>

diff --git a/src/lib/pubkey/dlies/dlies.h b/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 {
 
 /**

diff --git a/src/lib/pubkey/dlies/info.txt b/src/lib/pubkey/dlies/info.txt
@@ -4,6 +4,7 @@ DLIES -> 20160713
 
 <module_info>
 name -> "DLIES"
+lifecycle -> "Deprecated"
 </module_info>
 
 <requires>

diff --git a/src/lib/pubkey/gost_3410/info.txt b/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>

diff --git a/src/lib/pubkey/kyber/kyber_round3/kyber_90s/info.txt b/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>

diff --git a/src/lib/pubkey/mce/info.txt b/src/lib/pubkey/mce/info.txt
@@ -4,6 +4,7 @@ MCELIECE -> 20150922
 
 <module_info>
 name -> "McEliece"
+lifecycle -> "Deprecated"
 </module_info>
 
 <header:public>

diff --git a/src/lib/pubkey/mce/mceliece.h b/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;

diff --git a/src/lib/stream/shake_cipher/info.txt b/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>

diff --git a/src/lib/utils/uuid/uuid.h b/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 {