Mark deprecated modules as such

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)
randombit · May 11, 2024 · 0be3dd2 · 0be3dd2
1 parent 7606d70
commit 0be3dd2
Show file tree

Hide file tree

Showing 14 changed files with 88 additions and 37 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,54 +75,79 @@ 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
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-- 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,
-  the two types were merged. However it is still possible to refer to
-  SM2 using the split names of "SM2_Enc" or "SM2_Sig". In a future major
-  release this will be removed, and only "SM2" will be recognized.
+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.
 
-- DSA, ECDSA, ECGDSA, ECKCDSA, and GOST-34.10 previously (before Botan 3)
-  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.
+Deprecated modules include
 
-- Block cipher GOST 28147, Noekeon, Lion
+- Kyber mode ``kyber_90s``: Kyber's "90s mode" is not in the NIST ML-KEM
+  standard, and seems to have been never implemented widely.
 
-- Hash function GOST 34.11-94, Streebog, MD4
+- Dilithium mode ``dilithium_aes``: Similar situation to Kyber 90s mode.
 
-- GOST 34.10 signature scheme
+- Block cipher ``gost_28147``: This cipher was obsolete 20 years ago.
 
-- Stream cipher SHAKE (this does not affect SHAKE used as a HashFunction or XOF)
+- Block cipher ``noekeon``: An interesting design but not widely implemented.
 
-- The utility functions in cryptobox.h
+- Block cipher ``lion``: Similar situation to Noekeon
 
-- X9.42 KDF
+- Hash function ``gost_3411``: Very weak and questionable hash function.
 
-- 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.)
+- Hash function ``streebog``: Incredibly sketchy situation with the sbox
 
-- DLIES
+- Hash function ``md4``: It's time to let go
 
-- GCM support for 64-bit tags
+- Signature scheme ``gost_3410``
 
-- 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".
+- McEliece implementation ``mce``. Will be replaced by the proposal Classic
+  McEliece.
 
-- All built in MODP groups < 2048 bits
+- Stream cipher ``shake_cipher``. Note this deprecation affects only
+  using SHAKE as a ``StreamCipher`` not as a hash or XOF
 
-- 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).
+- `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.
+
+- 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,
+  the two types were merged. However it is still possible to refer to
+  SM2 using the split names of "SM2_Enc" or "SM2_Sig". In a future major
+  release this will be removed, and only "SM2" will be recognized.
+
+- DSA, ECDSA, ECGDSA, ECKCDSA, and GOST-34.10 previously (before Botan 3)
+  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.
+
+- GCM support for 64-bit tags
+
+- All built in MODP groups < 2048 bits
 
 - All pre-created DSA groups
 

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/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/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/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/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>