Botan 2.x to 3.x Migration¶
This is a guide on migrating applications from Botan 2.x to 3.0.
Many headers have been removed from the public API.
In some cases, such as
tls_blocking.h, the functionality
presented was entirely deprecated, in which case it has been removed.
In other cases (such as
rotate.h) the header was really an
implementation header of the library and not intended to be consumed as a public
API. In these cases the header is still used internally, but not installed for
However in most cases there is a better way of performing the same operations,
which usually works in both 2.x and 3.x. For example, in 3.0 all of the
algorithm headers (such as
aes.h) have been removed. Instead you should
create objects via the factory methods (in the case of AES,
BlockCipher::create) which works in both 2.x and 3.0
TLS Functionality Removed¶
Functionality removed from the TLS implementation includes
TLS 1.0, 1.1 and DTLS 1.0
Camellia CBC ciphersuites
AES-128 OCB ciphersuites
TLS 1.3 API adaptions¶
Old (pre-Botan 3.0) sessions won’t load in Botan 3.0 anymore and should be discarded.
Session::session_id() is equal to the “session ticket” for TLS 1.3 sessions.
This ticket might be longer than a typical ID (up to 64kB). If your application
depends on a short ID for each session, it is safe to just hash the returned
The algorithms CAST-256, MISTY1, Kasumi, DESX, XTEA, PBKDF1, MCEIES, CBC-MAC and Tiger have been removed. The expectation is that literally nobody was using any of these algorithms for anything. All are obscure, and many are broken.
All Or Nothing Package Transform¶
This code was deprecated and has been removed.
Several exceptions, mostly ones not used by the library, were removed.
A few others that were very specific (such as Illegal_Point) were replaced by throws of their immediate base class exception type.
The base class of Encoding_Error and Decoding_Error changed from Invalid_Argument to Exception. If you are explicitly catching Invalid_Argument, verify that you do not need to now also explicitly catch Encoding_Error and/or Decoding_Error.
X.509 Certificate Info Access¶
issuer_info could be used
to query information about extensions. This is not longer the case; instead you
should either call a specific function on
X509_Certificate which returns the
same information, or lacking that, iterate over the result of
Several enumerations where modified to become
enum class, including
ASN1_Tag has been split into
ASN1_Tag, these new enums are
enum class. The members of the
enums have changed from
Also an important change related to
ASN1_Tag::PRIVATE. This enum value was
incorrect, and actually was used for explicitly tagged context specific values.
ASN1_Class::Private refers to the correct class, but would lead to a
different encoding vs 2.x’s
ASN1_Tag::PRIVATE. The correct value to use in
3.0 to match