Botan 3.14.1
Crypto and TLS for C&

Public Header. More...

#include <botan/ffi.h>

Go to the source code of this file.

Macros

#define BOTAN_FFI_TLS_API_VERSION   20260916

Typedefs

typedef struct botan_tls_credentials_struct * botan_tls_credentials_t
typedef struct botan_tls_policy_struct * botan_tls_policy_t
typedef struct botan_tls_session_manager_struct * botan_tls_session_manager_t

Functions

 BOTAN_FFI_EXPORT (3, 14) int botan_tls_policy_init(botan_tls_policy_t *policy
int botan_tls_credentials_add_cert_chain (botan_tls_credentials_t creds, const botan_x509_cert_t *chain, size_t chain_len, botan_privkey_t key)
int botan_tls_credentials_add_trusted_cert (botan_tls_credentials_t creds, botan_x509_cert_t cert)
int botan_tls_policy_view_text (botan_tls_policy_t policy, botan_view_ctx ctx, botan_view_str_fn view)
int botan_tls_session_manager_init_memory (botan_tls_session_manager_t *mgr, botan_rng_t rng, size_t max_sessions)

Variables

botan_x509_crl_t crl
const char * name
const char * path
const char * text

Detailed Description

Public Header.

Definition in file ffi_tls.h.

Macro Definition Documentation

◆ BOTAN_FFI_TLS_API_VERSION

#define BOTAN_FFI_TLS_API_VERSION   20260916

The compile time version of the TLS FFI API (YYYYMMDD). Matches the value returned by botan_ffi_tls_api_version() and BOTAN_HAS_FFI_TLS in build.h.

Definition at line 39 of file ffi_tls.h.

Typedef Documentation

◆ botan_tls_credentials_t

typedef struct botan_tls_credentials_struct* botan_tls_credentials_t

Definition at line 106 of file ffi_tls.h.

◆ botan_tls_policy_t

typedef struct botan_tls_policy_struct* botan_tls_policy_t

Definition at line 48 of file ffi_tls.h.

◆ botan_tls_session_manager_t

typedef struct botan_tls_session_manager_struct* botan_tls_session_manager_t

Definition at line 183 of file ffi_tls.h.

Function Documentation

◆ BOTAN_FFI_EXPORT()

BOTAN_FFI_EXPORT ( 3 ,
14  )

Create one of the library's stock policies.

Parameters
policythe output handle; set to NULL on failure
name"default" (Botan::TLS::Policy), "strict" (Strict_Policy) or "bsi_tr_02102_2" (BSI_TR_02102_2); NULL selects "default"

Returns BOTAN_FFI_ERROR_BAD_PARAMETER for an unknown name.

Create a policy from text in the format of Botan::TLS::Text_Policy: one "key = value" setting per line, '#' starts a comment, and any key that is not mentioned keeps the value of the default policy. See the TLS policy section of the handbook for the available keys.

Parameters
policythe output handle; set to NULL on failure
textthe policy text

A line that is not of the form "key = value" is rejected with BOTAN_FFI_ERROR_INVALID_INPUT. Values are checked only when the policy is consulted, so an invalid value (such as a boolean key set to "maybe") is reported by a later call that uses the policy, not by this function.

Returns
0 if success, error if invalid object handle

Create an empty credentials object with no trust anchors and no certificate chains.

Add a CRL (copied) to the revocation data consulted when verifying the peer. Note that the default policy requires revocation information for the peer's certificates (require_cert_revocation_info), so without CRLs or stapled OCSP responses verification fails unless the policy relaxes that requirement.

Add every certificate found in the files below the directory path (searched recursively; files that do not contain a certificate are skipped) as a trust anchor, as Botan::Certificate_Store_In_Memory does. All of them are loaded at once and kept in memory for the lifetime of the credentials object. Returns BOTAN_FFI_ERROR_BAD_PARAMETER if no certificate was found, which includes a directory that does not exist or cannot be read, and BOTAN_FFI_ERROR_NOT_IMPLEMENTED in a build without filesystem support.

Also trust the certificates in the operating system's certificate store (Botan::System_Certificate_Store). Returns BOTAN_FFI_ERROR_NOT_IMPLEMENTED in a build without the certstor_system module.

Create a session manager that stores nothing (Botan::TLS::Session_Manager_Noop), which disables session resumption.

Parameters
mgrthe output handle; set to NULL on failure

References botan_tls_policy_init(), and name.

◆ botan_tls_credentials_add_cert_chain()

int botan_tls_credentials_add_cert_chain ( botan_tls_credentials_t creds,
const botan_x509_cert_t * chain,
size_t chain_len,
botan_privkey_t key )

Add a certificate chain, leaf first, together with the private key of the leaf certificate. The chain must contain at least one certificate. The certificates are copied; the key object is shared between the key handle and the credentials, so the handle may be destroyed afterwards and a key that cannot be exported, such as a hardware backed key, can be used.

Returns BOTAN_FFI_ERROR_BAD_PARAMETER if chain_len is 0 or the key does not belong to the leaf certificate.

Several chains may be added, for instance one with an RSA and one with an ECDSA key, or chains for different server names. A channel uses the first chain whose key type the peer accepts. A server that has a chain whose leaf certificate matches the server name the client asked for offers only such chains. If the peer named acceptable certificate authorities, a chain with a certificate issued by one of them is preferred.

Definition at line 243 of file ffi_tls.cpp.

246 {
247 if(any_null_pointers(creds, chain, key)) {
249 }
250
251 if(chain_len == 0) {
253 }
254
255 return BOTAN_FFI_VISIT(creds, [=](auto& c) -> int {
256 std::vector<Botan::X509_Certificate> certs;
257 certs.reserve(chain_len);
258 for(size_t i = 0; i != chain_len; ++i) {
259 certs.push_back(safe_get(chain[i]));
260 }
261
262 std::shared_ptr<Botan::Private_Key> key_ptr = safe_get_sp(key);
263
264 if(key_ptr->public_key()->fingerprint_public() != certs.front().subject_public_key()->fingerprint_public()) {
266 }
267
268 c.add_cert_chain(std::move(certs), std::move(key_ptr));
269 return BOTAN_FFI_SUCCESS;
270 });
271}
@ BOTAN_FFI_ERROR_NULL_POINTER
Definition ffi.h:131
@ BOTAN_FFI_SUCCESS
Definition ffi.h:114
@ BOTAN_FFI_ERROR_BAD_PARAMETER
Definition ffi.h:132
#define BOTAN_FFI_VISIT(obj, lambda)
Definition ffi_util.h:327
auto safe_get_sp(T *p) -> const typename T::smart_pointer_type &
Definition ffi_util.h:212
auto safe_get(T *p) -> typename T::element_type &
Definition ffi_util.h:191
bool any_null_pointers(Ptrs... ptr)
Definition mem_utils.h:54

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_BAD_PARAMETER, BOTAN_FFI_ERROR_NULL_POINTER, BOTAN_FFI_SUCCESS, BOTAN_FFI_VISIT, Botan_FFI::safe_get(), and Botan_FFI::safe_get_sp().

◆ botan_tls_credentials_add_trusted_cert()

int botan_tls_credentials_add_trusted_cert ( botan_tls_credentials_t creds,
botan_x509_cert_t cert )

Add a certificate (copied) as a trust anchor for verifying the peer.

Definition at line 201 of file ffi_tls.cpp.

201 {
202 return BOTAN_FFI_VISIT(creds, [=](auto& c) { c.add_trusted_cert(safe_get(cert)); });
203}

References BOTAN_FFI_VISIT, and Botan_FFI::safe_get().

◆ botan_tls_policy_view_text()

int botan_tls_policy_view_text ( botan_tls_policy_t policy,
botan_view_ctx ctx,
botan_view_str_fn view )

View the main settings of the policy as text (Botan::TLS::Policy::to_string), one "key = value" line per setting, using the key names of Text_Policy. Not every setting is included.

Definition at line 178 of file ffi_tls.cpp.

178 {
179 return BOTAN_FFI_VISIT(policy, [=](const auto& p) { return invoke_view_callback(view, ctx, p.to_string()); });
180}
int invoke_view_callback(botan_view_bin_fn view, botan_view_ctx ctx, std::span< const uint8_t > buf)
Definition ffi_util.h:359

References BOTAN_FFI_VISIT, and Botan_FFI::invoke_view_callback().

◆ botan_tls_session_manager_init_memory()

int botan_tls_session_manager_init_memory ( botan_tls_session_manager_t * mgr,
botan_rng_t rng,
size_t max_sessions )

Create a session manager that keeps sessions in memory (Botan::TLS::Session_Manager_In_Memory).

Parameters
mgrthe output handle; set to NULL on failure
Random Number Generatorsthe random number generator the manager uses; may be NULL, in which case an internal system RNG is used. The manager keeps its own reference to a non-NULL rng, so the handle may be destroyed after the call; the RNG object then lives on until the manager and every channel using the manager have been destroyed.
max_sessionsthe maximum number of sessions kept, 0 for no limit

Definition at line 281 of file ffi_tls.cpp.

281 {
282 if(any_null_pointers(mgr)) {
284 }
285
286 *mgr = nullptr;
287
288 return ffi_guard_thunk(__func__, [=]() -> int {
289 const auto rng_ptr = [&]() -> std::shared_ptr<Botan::RandomNumberGenerator> {
290 if(rng != nullptr) {
291 return safe_get_sp(rng);
292 } else {
293 return std::make_shared<Botan::System_RNG>();
294 }
295 }();
296
297 return ffi_new_object(mgr, std::make_shared<Botan::TLS::Session_Manager_In_Memory>(rng_ptr, max_sessions));
298 });
299}
BOTAN_FFI_ERROR ffi_new_object(T *obj, Args &&... args)
Definition ffi_util.h:347
int ffi_guard_thunk(const char *func_name, T thunk)
Definition ffi_util.h:229

References Botan_FFI::any_null_pointers(), BOTAN_FFI_ERROR_NULL_POINTER, Botan_FFI::ffi_guard_thunk(), Botan_FFI::ffi_new_object(), and Botan_FFI::safe_get_sp().

Variable Documentation

◆ crl

◆ name

const char* name

Definition at line 59 of file ffi_tls.h.

Referenced by Botan::Extensions::add(), Botan::OID_Map::add_oid(), Botan::OIDS::add_oid(), Botan::OIDS::add_oid2str(), Botan::OIDS::add_oidstr(), Botan::OIDS::add_str2oid(), Botan::Algorithm_Not_Found::Algorithm_Not_Found(), botan_block_cipher_name(), botan_cipher_name(), botan_ec_group_from_name(), botan_ec_group_supports_named_group(), BOTAN_FFI_EXPORT(), botan_hash_name(), botan_mac_name(), botan_oid_register(), botan_rng_init_custom(), botan_rng_init_drbg(), botan_tls_policy_init(), botan_x509_cert_issuer_alternative_names(), botan_x509_cert_subject_alternative_names(), botan_x509_general_name_destroy(), botan_x509_general_name_get_type(), botan_x509_general_name_view_binary_value(), botan_x509_general_name_view_string_value(), botan_xof_name(), Botan::TLS::Certificate_Request_12::Certificate_Request_12(), Botan::Classic_McEliece_Parameters::create(), Botan::Sphincs_Parameters::create(), Botan::Sphincs_Parameters::create(), Botan::create_keccak_mb_engine(), Botan::DataSource_Stream::DataSource_Stream(), Botan::Cert_Extension::CRL_Distribution_Points::Distribution_Point::decode_from(), Botan::Decoding_Error::Decoding_Error(), Botan::Cert_Extension::CRL_Distribution_Points::Distribution_Point::Distribution_Point(), Botan::DL_Group::DL_Group(), Botan::DL_Group::DL_group_info(), Botan::AlternativeName::dns(), Botan::EC_Group_Data::EC_Group_Data(), Botan::AlternativeName::encode_into(), Botan::Encoding_Error::Encoding_Error(), Botan::PCurve::PrimeOrderCurve::for_named_curve(), Botan::DL_Group::from_name(), Botan::EC_Group::from_name(), Botan::OID::from_name(), Botan::TLS::Ciphersuite::from_name(), Botan::Classic_McEliece_Parameter_Set::from_oid(), Botan::Encrypted_PSK_Database::get(), Botan::PSK_Database::get(), Botan::get_aead(), Botan::PSK_Database::get_str(), Botan::ieee1363_hash_id(), Botan::Invalid_Algorithm_Name::Invalid_Algorithm_Name(), Botan::Invalid_Key_Length::Invalid_Key_Length(), Botan::PSK_Database::is_encrypted(), Botan::NameConstraints::is_excluded(), Botan::NameConstraints::is_permitted(), Botan::Cert_Extension::Issuer_Alternative_Name::Issuer_Alternative_Name(), Botan::load_private_key(), Botan::load_public_key(), Botan::OIDS::lookup(), Botan::make_commoncrypto_block_cipher(), Botan::make_commoncrypto_cipher_mode(), Botan::make_commoncrypto_hash(), Botan::X509_Certificate::matches_dns_name(), Botan::X509_Certificate::matches_dns_name(), Botan::OID::OID(), Botan::OID_Map::oid2str(), Botan::OIDS::oid2str_or_throw(), Botan::pbes2_decrypt(), Botan::pkcs_hash_id(), Botan::OS::read_env_variable(), Botan::OS::read_env_variable_sz(), Botan::OID::register_oid(), Botan::Encrypted_PSK_Database::remove(), Botan::PSK_Database::remove(), Botan::TPM2::rsa_encryption_padding_botan_to_tss2(), Botan::TPM2::rsa_signature_scheme_botan_to_tss2(), Botan::TLS::Certificate_Request_12::serialize(), Botan::Roughtime::servers_from_str(), Botan::Encrypted_PSK_Database::set(), Botan::PSK_Database::set(), Botan::PKCS12::set_friendly_name(), Botan::Keyed_Filter::set_iv(), Botan::PSK_Database::set_str(), Botan::PSK_Database::set_vec(), Botan::OIDS::str2oid_or_empty(), Botan::Cert_Extension::Subject_Alternative_Name::Subject_Alternative_Name(), Botan::EC_Group::supports_named_group(), Botan::OID::to_formatted_string(), Botan::PK_Encryption_Options::to_string(), Botan::PK_Signature_Options::to_string(), Botan::PKCS12_Export_Options::with_friendly_name(), Botan::x509_dn_subtree_match(), and Botan::Encrypted_PSK_Database::~Encrypted_PSK_Database().

◆ path

◆ text