From 90001378a0f2484731b99526f0b7ed89b6b33f44 Mon Sep 17 00:00:00 2001 From: Jack Lloyd Date: Sat, 11 May 2024 12:46:13 -0400 Subject: [PATCH] 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. --- doc/deprecated.rst | 134 +++++++++++------- src/lib/block/gost_28147/info.txt | 1 + src/lib/block/lion/info.txt | 1 + src/lib/block/noekeon/info.txt | 1 + src/lib/hash/md4/info.txt | 1 + src/lib/hash/streebog/info.txt | 1 + src/lib/kdf/prf_x942/info.txt | 1 + src/lib/math/numbertheory/reducer.h | 2 + src/lib/pbkdf/pbkdf.h | 2 + src/lib/pbkdf/pbkdf2/pbkdf2.h | 2 + src/lib/prov/tpm/info.txt | 1 + src/lib/prov/tpm/tpm.h | 3 + .../pubkey/dilithium/dilithium_aes/info.txt | 1 + src/lib/pubkey/dlies/dlies.h | 2 + src/lib/pubkey/dlies/info.txt | 1 + src/lib/pubkey/gost_3410/info.txt | 1 + .../kyber/kyber_round3/kyber_90s/info.txt | 1 + src/lib/pubkey/mce/info.txt | 1 + src/lib/pubkey/mce/mceliece.h | 2 + src/lib/stream/shake_cipher/info.txt | 1 + src/lib/utils/uuid/uuid.h | 2 +- 21 files changed, 113 insertions(+), 49 deletions(-) diff --git a/doc/deprecated.rst b/doc/deprecated.rst index 498a20dc5c1..353d5bed8b2 100644 --- 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 index 8c55a9b6e5f..38b3722b9f6 100644 --- a/src/lib/block/gost_28147/info.txt +++ b/src/lib/block/gost_28147/info.txt @@ -4,4 +4,5 @@ GOST_28147_89 -> 20131128 name -> "GOST 28147-89" +lifecycle -> "Deprecated" diff --git a/src/lib/block/lion/info.txt b/src/lib/block/lion/info.txt index 1d5891bca5f..6068545c585 100644 --- a/src/lib/block/lion/info.txt +++ b/src/lib/block/lion/info.txt @@ -4,6 +4,7 @@ LION -> 20131128 name -> "Lion" +lifecycle -> "Deprecated" diff --git a/src/lib/block/noekeon/info.txt b/src/lib/block/noekeon/info.txt index 2d5e03bda37..212e2f17fdd 100644 --- a/src/lib/block/noekeon/info.txt +++ b/src/lib/block/noekeon/info.txt @@ -4,4 +4,5 @@ NOEKEON -> 20131128 name -> "Noekeon" +lifecycle -> "Deprecated" diff --git a/src/lib/hash/md4/info.txt b/src/lib/hash/md4/info.txt index 55a697b19cb..dda5f008ee6 100644 --- a/src/lib/hash/md4/info.txt +++ b/src/lib/hash/md4/info.txt @@ -4,6 +4,7 @@ MD4 -> 20131128 name -> "MD4" +lifecycle -> "Deprecated" diff --git a/src/lib/hash/streebog/info.txt b/src/lib/hash/streebog/info.txt index 45640c54476..747de8b6083 100644 --- a/src/lib/hash/streebog/info.txt +++ b/src/lib/hash/streebog/info.txt @@ -4,4 +4,5 @@ STREEBOG -> 20170623 name -> "Streebog" +lifecycle -> "Deprecated" diff --git a/src/lib/kdf/prf_x942/info.txt b/src/lib/kdf/prf_x942/info.txt index 6bafcda17a8..c02d7d7598b 100644 --- a/src/lib/kdf/prf_x942/info.txt +++ b/src/lib/kdf/prf_x942/info.txt @@ -4,6 +4,7 @@ X942_PRF -> 20131128 name -> "PRF X9.42" +lifecycle -> "Deprecated" diff --git a/src/lib/math/numbertheory/reducer.h b/src/lib/math/numbertheory/reducer.h index f42fbc84560..7ea742b998a 100644 --- a/src/lib/math/numbertheory/reducer.h +++ b/src/lib/math/numbertheory/reducer.h @@ -10,6 +10,8 @@ #include +BOTAN_FUTURE_INTERNAL_HEADER(reducer.h) + namespace Botan { /** diff --git a/src/lib/pbkdf/pbkdf.h b/src/lib/pbkdf/pbkdf.h index f830a48579f..cec5c94fbf8 100644 --- a/src/lib/pbkdf/pbkdf.h +++ b/src/lib/pbkdf/pbkdf.h @@ -37,6 +37,7 @@ 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 create(std::string_view algo_spec, std::string_view provider = ""); /** @@ -44,6 +45,7 @@ class BOTAN_PUBLIC_API(2, 0) PBKDF { * algo/provider combination cannot be found. If provider is * empty then best available is chosen. */ + BOTAN_DEPRECATED("Use PasswordHashFamily + PasswordHash") static std::unique_ptr 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 index a0f21749935..90052a18760 100644 --- 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 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 index 0218e2237f4..692e641a5ca 100644 --- a/src/lib/prov/tpm/info.txt +++ b/src/lib/prov/tpm/info.txt @@ -5,6 +5,7 @@ TPM -> 20151126 name -> "TPM" brief -> "Wrappers and Utilites to interact with TPMs" +lifecycle -> "Deprecated" load_on vendor diff --git a/src/lib/prov/tpm/tpm.h b/src/lib/prov/tpm/tpm.h index 00088c9f001..710c52ad5fc 100644 --- a/src/lib/prov/tpm/tpm.h +++ b/src/lib/prov/tpm/tpm.h @@ -16,6 +16,8 @@ #include #include +BOTAN_DEPRECATED_HEADER("tpm.h") + //TODO remove this #include @@ -46,6 +48,7 @@ class BOTAN_PUBLIC_API(2, 0) TPM_Context final { */ typedef std::function 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 index 13920cb7a24..8720bb62508 100644 --- 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 name -> "Dilithium (AES)" +lifecycle -> "Deprecated" diff --git a/src/lib/pubkey/dlies/dlies.h b/src/lib/pubkey/dlies/dlies.h index 4ed7f654276..840a69d055e 100644 --- a/src/lib/pubkey/dlies/dlies.h +++ b/src/lib/pubkey/dlies/dlies.h @@ -15,6 +15,8 @@ #include #include +BOTAN_DEPRECATED_HEADER("dlies.h") + namespace Botan { /** diff --git a/src/lib/pubkey/dlies/info.txt b/src/lib/pubkey/dlies/info.txt index 26742b31e61..6797c3ffa01 100644 --- a/src/lib/pubkey/dlies/info.txt +++ b/src/lib/pubkey/dlies/info.txt @@ -4,6 +4,7 @@ DLIES -> 20160713 name -> "DLIES" +lifecycle -> "Deprecated" diff --git a/src/lib/pubkey/gost_3410/info.txt b/src/lib/pubkey/gost_3410/info.txt index 60cfbba1299..a82d0608b0b 100644 --- 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 name -> "GOST 34.10-2001" +lifecycle -> "Deprecated" diff --git a/src/lib/pubkey/kyber/kyber_round3/kyber_90s/info.txt b/src/lib/pubkey/kyber/kyber_round3/kyber_90s/info.txt index ccad2eb5ec3..37106602a11 100644 --- 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 name -> "Kyber 90s" +lifecycle -> "Deprecated" diff --git a/src/lib/pubkey/mce/info.txt b/src/lib/pubkey/mce/info.txt index 9cf9ddf53f1..e79a5a0bb3b 100644 --- a/src/lib/pubkey/mce/info.txt +++ b/src/lib/pubkey/mce/info.txt @@ -4,6 +4,7 @@ MCELIECE -> 20150922 name -> "McEliece" +lifecycle -> "Deprecated" diff --git a/src/lib/pubkey/mce/mceliece.h b/src/lib/pubkey/mce/mceliece.h index 5b7e9c0bd81..59fcd1aa2c2 100644 --- a/src/lib/pubkey/mce/mceliece.h +++ b/src/lib/pubkey/mce/mceliece.h @@ -14,6 +14,8 @@ #include +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 index 7bfeed59048..c57d48b8cbe 100644 --- a/src/lib/stream/shake_cipher/info.txt +++ b/src/lib/stream/shake_cipher/info.txt @@ -5,6 +5,7 @@ SHAKE_CIPHER -> 20161018 name -> "SHAKE-based XOFs" brief -> "SHAKE-128 and SHAKE-256 XOF presented as stream ciphers" +lifecycle -> "Deprecated" diff --git a/src/lib/utils/uuid/uuid.h b/src/lib/utils/uuid/uuid.h index ff57e8ed5e9..b1fb0334fad 100644 --- a/src/lib/utils/uuid/uuid.h +++ b/src/lib/utils/uuid/uuid.h @@ -12,7 +12,7 @@ #include #include -//BOTAN_FUTURE_INTERNAL_HEADER(uuid.h) +BOTAN_DEPRECATED_HEADER("uuid.h") namespace Botan {