Skip to content
etcimon edited this page Aug 17, 2026 · 5 revisions

Getting started

Build with DUB. Add the registry package:

"dependencies": {
    "botan": "~>3.13.0"
}
import botan.rng.auto_rng;
import botan.libstate.global_state;

Library state

globalState() lazily constructs the process-wide LibraryState (algorithm factory, RNG entropy sources, lookup tables). The first lookup or TLS/X.509 call will do this for you.

auto state = globalState();   // optional; Unique-owned internally
Unique!AutoSeededRNG rng = new AutoSeededRNG;

LibraryInitializer in botan.libstate.init still exists (RAII around the same state). You do not need both. Prefer globalState() or just start using the library.

Do not construct Botan objects as globals / shared static members before the runtime has started: module constructors can run in an undefined order. Heap-allocate after main (or after globalState()).

Destroy Botan objects before process teardown if you care about memutils leak reports. Unique!T does that on scope exit.

Configurations

Config Role
full (default) Every compiled identifier: historic ciphers, TLS 1.3, PQC, OCSP, stores
standard Popular TLS 1.2 + X.509 + AES/GCM + RSA/ECDSA/Ed25519. No TLS 1.3, no PQC
lite / pubkey / hash Smaller slices
full_openssl full plus the optional OpenSSL engine (x86_64)

Feature flags are D version identifiers in dub.json, mapped to BOTAN_HAS_* in source/botan/constants.d. version(TLS) does not imply TLS_13. SIMD / AES-NI / ChaCha AVX2 live under versions-x86_64-ldc (DUB requires the compiler last). DMD SIGILL'd those kernels at startup.

Testing

A single dub test compiles every algorithm unittest into one process and can exhaust LDC. CI and incremental work run one family per process:

dub test --compiler=ldc2 --combined --d-version=FocusTests --d-version=Test_TLS
# Windows
.\scripts\inc-build.ps1 test tls
.\scripts\inc-build.ps1 test x509

Families used by CI: Test_TLS, Test_X509, Test_RSA, Test_ECDSA, Test_Hash, Test_AEAD, Test_MAC, Test_ASN1.

Unique

// yes
Unique!AutoSeededRNG rng = new AutoSeededRNG;
Unique!TLSSessionManagerInMemory sessions = new TLSSessionManagerInMemory(*rng);

// no — class news that are not Unique-wrapped leak under DebugAllocator
auto rng = new AutoSeededRNG;

PublicKey loadKey(...) returns a raw class pointer. Take ownership:

Unique!PublicKey pk = x509_key.loadKey(filename);

Exceptions

Catch Exception (or Botan’s DecodingError, TLSException, …) in main so a failed decode or handshake does not look like a mysterious runtime abort.

Next

Clone this wiki locally