客户端 ClientHello（携带支持的密码套件与密钥交换组）
        │
        ▼
服务端 ServerHello（选定套件）+ 服务器证书
        │
        ▼
密钥交换（ECDHE 或后量子混合 ML-KEM）
        │
        ▼
双方派生会话密钥，此后应用数据在记录层加密传输

根证书（Root CA）
    │ 签发
    ▼
中间证书（Intermediate CA）
    │ 签发
    ▼
终端实体证书（End Entity Certificate，含公钥与身份信息）
    │
    ▼
验证者核对证书签名、有效期与撤销状态，并按目标主机名校验身份

# 带压缩与更多功能
python3 configure.py --with-zlib --with-bzip2 --with-lzma

# 最小化构建
python3 configure.py --without-documentation

find_package(Botan 3.3.0)
target_link_libraries(my_app PRIVATE Botan::Botan)

#include <botan/tls_client.h>
#include <botan/tls_callbacks.h>
#include <botan/tls_session_manager.h>
#include <botan/tls_policy.h>
#include <botan/certstor.h>
#include <botan/auto_rng.h>
#include <memory>

// 应用侧回调：一切需要进出网络的数据都经过这里
class Callbacks : public Botan::TLS::Callbacks {
  public:
    void tls_emit_data(std::span<const uint8_t> data) override {
        socket_write(data);              // 把握手/记录层字节写入网络
    }
    void tls_record_received(uint64_t seq_no, std::span<const uint8_t> data) override {
        process_application_data(data);  // 收到的应用层明文
    }
    void tls_alert(Botan::TLS::Alert alert) override {
        handle_alert(alert);             // 告警处理（关闭通知、错误等）
    }
};

// 凭据管理：告诉 TLS 信任哪些根证书
class Creds : public Botan::TLS::Credentials_Manager {
  public:
    std::vector<Botan::Certificate_Store*> trusted_certificate_authorities(
        const std::string&, const std::string&) override {
        return { &store_ };
    }
  private:
    Botan::Certificate_Store_In_Memory store_;  // 加入受信任的 CA 证书
};

int main() {
    auto callbacks = std::make_shared<Callbacks>();
    auto creds = std::make_shared<Creds>();
    auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
    auto session_mgr = std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng);
    auto policy = std::make_shared<Botan::TLS::Policy>();

    // 构造完成即发出 ClientHello，字节经 tls_emit_data 交给你的网络层
    Botan::TLS::Client client(callbacks, session_mgr, creds, policy, rng,
                              Botan::TLS::Server_Information("example.com", 443));

    // 主循环中每从 socket 读到字节都喂回 TLS，握手与应用数据随之推进
    client.from_peer(buf);
}

#include <botan/tls_policy.h>

class PostQuantumPolicy : public Botan::TLS::Policy {
  public:
    std::vector<Botan::TLS::Group_Params> key_exchange_groups() const override {
        // 经典曲线与 ML-KEM 混合组一起列出，保证后量子前向保密
        return {
            Botan::TLS::Group_Params::X25519,
            Botan::TLS::Group_Params::SECP256R1,
            Botan::TLS::Group_Params::HYBRID_X25519_ML_KEM_768,
            Botan::TLS::Group_Params::HYBRID_SECP256R1_ML_KEM_768,
        };
    }
};

#include <botan/rsa.h>
#include <botan/pk_sign.h>
#include <botan/pubkey.h>

// 生成密钥
Botan::RSA_PrivateKey rsa_key(rng, 3072);

// 签名：PSS（旧名 EMSA4）是推荐填充；EMSA3 指更旧的 PKCS#1 v1.5
Botan::PK_Signer signer(rsa_key, rng, "PSS(SHA-256)");
signer.update(message);
std::vector<uint8_t> signature = signer.signature();

// 验签
Botan::PK_Verifier verifier(rsa_key, "PSS(SHA-256)");
verifier.update(message);
bool valid = verifier.check_signature(signature);

#include <botan/ed25519.h>

Botan::Ed25519_PrivateKey ed_key(rng);
Botan::PK_Signer ed_signer(ed_key, rng, "Pure");   // EdDSA 纯签名
ed_signer.update(message);
std::vector<uint8_t> ed_sig = ed_signer.signature();

#include <botan/ml_dsa.h>

// ML_DSA_6x5 即 NIST 的 ML-DSA-65，目标安全性大致对应 AES-192
Botan::ML_DSA_PrivateKey mldsa_key(rng, Botan::ML_DSA_Mode::ML_DSA_6x5);
Botan::PK_Signer mldsa_signer(mldsa_key, rng, "Pure");   // FIPS 204 的 Pure 模式
mldsa_signer.update(message);
std::vector<uint8_t> mldsa_sig = mldsa_signer.signature();

#include <botan/rng.h>
#include <botan/cipher_mode.h>

auto& rng = Botan::system_rng();

// 32 字节密钥与 12 字节 nonce（GCM 标准 nonce 长 96 位）
const Botan::secure_vector<uint8_t> key = rng.random_vec(32);
const Botan::secure_vector<uint8_t> nonce = rng.random_vec(12);

auto enc = Botan::Cipher_Mode::create_or_throw("AES-256/GCM", Botan::Cipher_Dir::Encryption);
enc->set_key(key);
enc->start(nonce);

Botan::secure_vector<uint8_t> buf(plaintext.begin(), plaintext.end());
enc->finish(buf);   // buf 就地变为「密文 + 16 字节认证标签」

// 网络传输时把 buf 整体发给对端；对端用同一 nonce 与密钥解密

#include <botan/hash.h>

// SHA-256
auto sha256 = Botan::HashFunction::create("SHA-256");
sha256->update(data);
std::vector<uint8_t> hash = sha256->final();

// BLAKE2b：在多数平台更快
auto blake2b = Botan::HashFunction::create("BLAKE2b-512");
blake2b->update(data);
std::vector<uint8_t> hash512 = blake2b->final();

#include <botan/argon2fmt.h>
#include <botan/rng.h>

auto& rng = Botan::system_rng();

// 参数顺序为 p、M（KiB）、t、y；y=2 即 Argon2id
// 此处取 RFC 9106 的"低内存第二推荐"：M=64 MiB、t=3、p=4
std::string hash = Botan::argon2_generate_pwhash(
    password.data(), password.size(),
    rng,
    /*p*/ 4,
    /*M*/ 64 * 1024,   // 64 MiB
    /*t*/ 3,
    /*y*/ 2,           // Argon2id
    /*salt_len*/ 16,
    /*output_len*/ 32);

// 校验
bool ok = Botan::argon2_check_pwhash(password.data(), password.size(), hash);

#include <botan/x509cert.h>
#include <botan/x509path.h>
#include <botan/certstor.h>

Botan::X509_Certificate cert("server.pem");
Botan::X509_Certificate root("ca.pem");

// 把根证书放进内存证书存储
Botan::Certificate_Store_In_Memory store;
store.add_certificate(root);

// 参数顺序：待验证书、校验约束、信任存储、目标主机名
// Path_Validation_Restrictions() 默认要求至少 110 位安全强度
Botan::Path_Validation_Result result = Botan::x509_path_validate(
    cert,
    Botan::Path_Validation_Restrictions(),
    store,
    "example.com");

if (result.successful_validation()) {
    // example.com 的证书可信
}

# Ubuntu（24.04 起提供 Botan 3，命令行工具包名为 botan）
sudo apt install botan libbotan-3-dev

# Fedora
sudo dnf install botan3 botan3-devel

# macOS (Homebrew)
brew install botan

# Arch Linux
sudo pacman -S botan

git clone https://github.com/randombit/botan.git
cd botan

python3 configure.py --with-zlib --with-bzip2 --with-lzma
make -j$(nproc)
sudo make install
sudo ldconfig

python3 configure.py --amalgamation
# 生成 botan_all.h 与 botan_all.cpp
g++ -O3 -o botan_app botan_all.cpp -pthread
# 若 configure 时启用了 zlib/bzip2/lzma，还需追加 -lz -lbz2 -llzma 等链接参数

from botan3 import HashFunction, SymmetricCipher, RandomNumberGenerator

# SHA-256 哈希
sha256 = HashFunction("SHA-256")
sha256.update(b"hello world")
print(sha256.final().hex())

# AES-256-GCM 认证加密
key = RandomNumberGenerator().get(32)       # 256-bit 密钥
nonce = RandomNumberGenerator().get(12)     # 96-bit nonce（GCM 默认）
cipher = SymmetricCipher("AES-256/GCM", encrypt=True)
cipher.set_key(key)
cipher.start(nonce)
ct = cipher.finish(b"secret message")        # 密文（含认证标签）

#include <botan/ffi.h>

botan_hash_t hash;
botan_hash_init(&hash, "SHA-256", 0);
botan_hash_update(hash, data, data_len);
uint8_t digest[32];
botan_hash_final(hash, digest);
botan_hash_destroy(hash);

/* 公钥从内存位串加载：先把 PEM/DER 文件内容读进 bits 缓冲 */
botan_pubkey_t pubkey;
botan_pubkey_load(&pubkey, bits, bits_len);

botan hash --algo=SHA-256 data.txt
botan cipher --cipher=AES-256/GCM --key=<hex-key> --nonce=<hex-nonce> data.bin      # 加密
botan cipher --decrypt --cipher=AES-256/GCM --key=<hex-key> --nonce=<hex-nonce> data.bin.enc
botan keygen --algo=RSA --params=3072        # RSA 位长走 --params
botan sign --hash=SHA-256 key.pem data.txt   # RSA 默认用 PSS 填充
botan verify --hash=SHA-256 pubkey.pem data.txt signature.bin
botan cert_verify server.pem ca.pem          # 校验证书链
botan version --full                         # 查看版本与编译特性

#include <botan/p11.h>
#include <botan/p11_rsa.h>
#include <botan/p11_types.h>

Botan::PKCS11::Module module("/usr/lib/softhsm/libsofthsm2.so");  // 或真实 HSM 驱动

// 找到第一个插有令牌的槽位，打开读写会话并登录
auto slots = Botan::PKCS11::Slot::get_available_slots(module, /*token_present=*/true);
Botan::PKCS11::Slot slot(module, slots.at(0));
Botan::PKCS11::Session session(slot, /*readonly=*/false);
session.login(Botan::PKCS11::UserType::User, pin);   // pin 为 PKCS11::secure_string

// 直接在令牌内生成 RSA 私钥：私钥材料不离开设备
Botan::PKCS11::RSA_PrivateKeyGenerationProperties props;
props.set_token(true);
props.set_private(true);
props.set_sign(true);
Botan::PKCS11::PKCS11_RSA_PrivateKey key(session, 2048, props);

#include <botan/tpm2_context.h>
#include <botan/tpm2_rng.h>
#include <botan/tpm2_rsa.h>
#include <botan/tpm2_session.h>

// TCTI 配置串指定 TPM 访问方式（此处经 tabrmd 守护进程）
auto ctx = Botan::TPM2::Context::create(
    "tabrmd:bus_name=net.randombit.botan.tabrmd,bus_type=session");

// 可选：把 Botan 挂为 tpm2-tss 的加密后端，避免引入第二个密码库
if(ctx->supports_botan_crypto_backend()) {
    ctx->use_botan_crypto_backend(rng);
}

// TPM 背书的随机数；配合 TPM2::Session 与 TPM2::RSA_PrivateKey
// 可把密钥生成与签名操作放进 TPM
auto tpm_rng = Botan::TPM2::RandomNumberGenerator(ctx);

#include <botan/asio_stream.h>
#include <botan/auto_rng.h>
#include <botan/tls_session_manager.h>
#include <boost/asio.hpp>

auto rng = std::make_shared<Botan::AutoSeeded_RNG>();
// Context 汇集凭据、RNG、会话存储与策略，角色相当于 OpenSSL 的 SSL_CTX
Botan::TLS::Context ctx(
    creds_mgr,                                                       // shared_ptr<Credentials_Manager>
    rng,
    std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng),
    std::make_shared<Botan::TLS::Policy>());

boost::asio::io_context io;
boost::asio::ip::tcp::socket tcp(io);
Botan::TLS::Stream<boost::asio::ip::tcp::socket> stream(std::move(tcp), ctx);

// 此后按普通 Asio 流读写，TLS 握手与记录层加密在内部完成

auto& rng = Botan::system_rng();          // 系统熵源

Botan::RSA_PrivateKey rsa_key(rng, 3072); // RSA 至少 3072 位
Botan::EC_Group secp256r1("secp256r1");
Botan::ECDSA_PrivateKey ecdsa_key(rng, secp256r1);

#include <botan/tls_policy.h>

class SecurePolicy : public Botan::TLS::Policy {
  public:
    // TLS 1.2 / 1.3 共用的 cipher 名（注意用斜杠，不是连字符）
    std::vector<std::string> allowed_ciphers() const override {
        return { "AES-256/GCM", "ChaCha20Poly1305" };
    }
    // 曲线与后量子混合组由 key_exchange_groups() 控制
    std::vector<Botan::TLS::Group_Params> key_exchange_groups() const override {
        return {
            Botan::TLS::Group_Params::X25519,
            Botan::TLS::Group_Params::HYBRID_X25519_ML_KEM_768, // 后量子混合
        };
    }
    bool allow_tls12() const override { return false; }
};

try {
    auto enc = Botan::Cipher_Mode::create_or_throw("AES-256/GCM",
                                                    Botan::Cipher_Dir::Encryption);
} catch (const Botan::Algorithm_Not_Found& e) {
    // 构建时未启用该算法
} catch (const Botan::Invalid_Key_Length& e) {
    // 密钥长度不合法
}

// create 返回空表示不支持，create_or_throw 直接抛异常
auto hash = Botan::HashFunction::create("SHA-256");
if (!hash) {
    // 创建失败
}

botan version --full

python3 -c "import botan3; print(botan3.version_string())"

./configure.py --os=android --cpu=arm64