Botan 3.14.1
Crypto and TLS for C&
ffi_tls.h
Go to the documentation of this file.
1/*
2* TLS interface for the FFI (C89 API)
3* (C) 2026 Moritz Schmitt
4*
5* Botan is released under the Simplified BSD License (see license.txt)
6*/
7
8#ifndef BOTAN_FFI_TLS_H_
9#define BOTAN_FFI_TLS_H_
10
11#include <botan/ffi.h>
12
13#ifdef __cplusplus
14extern "C" {
15#endif
16
17/*
18* This header is provided by the experimental module ffi_tls, which is not
19* part of a default build (configure with --enable-modules=ffi_tls or
20* --enable-experimental-features). The functions declared here may change
21* incompatibly in a future release until the module is marked stable.
22*
23* C code can detect the module at compile time by including <botan/build.h>
24* and testing BOTAN_HAS_FFI_TLS, and at run time by calling
25* botan_ffi_tls_api_version() (declared in ffi.h, always available, returns
26* 0 when the module is absent).
27*
28* The conventions of ffi.h apply: every object is an opaque handle, every
29* function returns 0 (BOTAN_FFI_SUCCESS) or a negative BOTAN_FFI_ERROR code,
30* no memory ownership crosses the boundary, variable-length outputs use view
31* functions, and strings are NUL-terminated.
32*/
33
34/**
35* The compile time version of the TLS FFI API (YYYYMMDD). Matches the value
36* returned by botan_ffi_tls_api_version() and BOTAN_HAS_FFI_TLS in build.h.
37*/
38/* NOLINTNEXTLINE(*-macro-usage) */
39#define BOTAN_FFI_TLS_API_VERSION 20260916
40
41/*
42* TLS policies
43*
44* A policy (Botan::TLS::Policy) controls which protocol versions,
45* ciphersuites and parameters a TLS channel accepts. A policy object is
46* immutable after creation and may be shared between several channels.
47*/
48typedef struct botan_tls_policy_struct* botan_tls_policy_t;
49
50/**
51* Create one of the library's stock policies.
52*
53* @param policy the output handle; set to NULL on failure
54* @param name "default" (Botan::TLS::Policy), "strict" (Strict_Policy) or
55* "bsi_tr_02102_2" (BSI_TR_02102_2); NULL selects "default"
56*
57* Returns BOTAN_FFI_ERROR_BAD_PARAMETER for an unknown name.
58*/
60
61/**
62* Create a policy from text in the format of Botan::TLS::Text_Policy: one
63* "key = value" setting per line, '#' starts a comment, and any key that is
64* not mentioned keeps the value of the default policy. See the TLS policy
65* section of the handbook for the available keys.
66*
67* @param policy the output handle; set to NULL on failure
68* @param text the policy text
69*
70* A line that is not of the form "key = value" is rejected with
71* BOTAN_FFI_ERROR_INVALID_INPUT. Values are checked only when the policy is
72* consulted, so an invalid value (such as a boolean key set to "maybe") is
73* reported by a later call that uses the policy, not by this function.
74*/
76
77/**
78* View the main settings of the policy as text (Botan::TLS::Policy::to_string),
79* one "key = value" line per setting, using the key names of Text_Policy.
80* Not every setting is included.
81*/
84
85/**
86* @return 0 if success, error if invalid object handle
87*/
89
90/*
91* TLS credentials
92*
93* A credentials object holds what a channel needs to authenticate the peer
94* and itself: trust anchors and CRLs for verifying the peer's certificate
95* chain, and certificate chains with private keys for authenticating this
96* side (as a server, or as a client when the server requests a client
97* certificate).
98*
99* Certificates and CRLs passed to the setters are copied and a private key
100* is shared with the object, so the handles may be destroyed after the
101* call. The object may be shared by
102* any number of channels, which keep it alive, and its setters may be called
103* at any time; later handshakes see the change. It is not synchronized, so
104* modifying it while a channel on another thread uses it is a data race.
105*/
106typedef struct botan_tls_credentials_struct* botan_tls_credentials_t;
107
108/**
109* Create an empty credentials object with no trust anchors and no
110* certificate chains.
111*/
113
114/**
115* Add a certificate (copied) as a trust anchor for verifying the peer.
116*/
117BOTAN_FFI_EXPORT(3, 14)
119
120/**
121* Add a CRL (copied) to the revocation data consulted when verifying the
122* peer. Note that the default policy requires revocation information for
123* the peer's certificates (require_cert_revocation_info), so without CRLs
124* or stapled OCSP responses verification fails unless the policy relaxes
125* that requirement.
126*/
128
129/**
130* Add every certificate found in the files below the directory path
131* (searched recursively; files that do not contain a certificate are
132* skipped) as a trust anchor, as Botan::Certificate_Store_In_Memory does.
133* All of them are loaded at once and kept in memory for the lifetime of the
134* credentials object.
135* Returns BOTAN_FFI_ERROR_BAD_PARAMETER if no certificate was found, which
136* includes a directory that does not exist or cannot be read, and
137* BOTAN_FFI_ERROR_NOT_IMPLEMENTED in a build without filesystem support.
138*/
140
141/**
142* Also trust the certificates in the operating system's certificate store
143* (Botan::System_Certificate_Store). Returns BOTAN_FFI_ERROR_NOT_IMPLEMENTED
144* in a build without the certstor_system module.
145*/
147
148/**
149* Add a certificate chain, leaf first, together with the private key of the
150* leaf certificate. The chain must contain at least one certificate. The
151* certificates are copied; the key object is shared between the key handle
152* and the credentials, so the handle may be destroyed afterwards and a key
153* that cannot be exported, such as a hardware backed key, can be used.
154*
155* Returns BOTAN_FFI_ERROR_BAD_PARAMETER if chain_len is 0 or the key does
156* not belong to the leaf certificate.
157*
158* Several chains may be added, for instance one with an RSA and one with an
159* ECDSA key, or chains for different server names. A channel uses the first
160* chain whose key type the peer accepts. A server that has a chain whose
161* leaf certificate matches the server name the client asked for offers only
162* such chains. If the peer named acceptable certificate authorities, a chain
163* with a certificate issued by one of them is preferred.
164*/
165BOTAN_FFI_EXPORT(3, 14)
167 const botan_x509_cert_t* chain,
168 size_t chain_len,
169 botan_privkey_t key);
170
171/**
172* @return 0 if success, error if invalid object handle
173*/
175
176/*
177* TLS session managers
178*
179* A session manager stores the information needed to resume sessions. It
180* may be shared by any number of channels, which keep it alive; the
181* in-memory manager synchronizes its own state.
182*/
183typedef struct botan_tls_session_manager_struct* botan_tls_session_manager_t;
184
185/**
186* Create a session manager that keeps sessions in memory
187* (Botan::TLS::Session_Manager_In_Memory).
188*
189* @param mgr the output handle; set to NULL on failure
190* @param rng the random number generator the manager uses; may be NULL, in
191* which case an internal system RNG is used. The manager keeps its own
192* reference to a non-NULL rng, so the handle may be destroyed after
193* the call; the RNG object then lives on until the manager and every
194* channel using the manager have been destroyed.
195* @param max_sessions the maximum number of sessions kept, 0 for no limit
196*/
197BOTAN_FFI_EXPORT(3, 14)
199
200/**
201* Create a session manager that stores nothing
202* (Botan::TLS::Session_Manager_Noop), which disables session resumption.
203*
204* @param mgr the output handle; set to NULL on failure
205*/
207
208/**
209* @return 0 if success, error if invalid object handle
210*/
212
213#ifdef __cplusplus
214}
215#endif
216
217#endif
#define BOTAN_FFI_EXPORT(maj, min)
Definition ffi.h:89
struct botan_privkey_struct * botan_privkey_t
Definition ffi.h:1874
struct botan_x509_crl_struct * botan_x509_crl_t
Definition ffi.h:4211
struct botan_x509_cert_struct * botan_x509_cert_t
Definition ffi.h:3608
void * botan_view_ctx
Definition ffi.h:152
struct botan_rng_struct * botan_rng_t
Definition ffi.h:343
int(* botan_view_str_fn)(botan_view_ctx view_ctx, const char *str, size_t len)
Definition ffi.h:170
int botan_tls_credentials_use_system_store(botan_tls_credentials_t creds)
Definition ffi_tls.cpp:231
int botan_tls_credentials_add_crl(botan_tls_credentials_t creds, botan_x509_crl_t crl)
Definition ffi_tls.cpp:205
int botan_tls_session_manager_init_noop(botan_tls_session_manager_t *mgr)
Definition ffi_tls.cpp:301
int botan_tls_policy_init(botan_tls_policy_t *policy, const char *name)
Definition ffi_tls.cpp:144
int botan_tls_credentials_init(botan_tls_credentials_t *creds)
Definition ffi_tls.cpp:190
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)
Definition ffi_tls.cpp:243
int botan_tls_credentials_add_trusted_dir(botan_tls_credentials_t creds, const char *path)
Definition ffi_tls.cpp:209
int botan_tls_policy_init_from_text(botan_tls_policy_t *policy, const char *text)
Definition ffi_tls.cpp:166
int botan_tls_session_manager_init_memory(botan_tls_session_manager_t *mgr, botan_rng_t rng, size_t max_sessions)
Definition ffi_tls.cpp:281
int botan_tls_session_manager_destroy(botan_tls_session_manager_t mgr)
Definition ffi_tls.cpp:312
int botan_tls_credentials_add_trusted_cert(botan_tls_credentials_t creds, botan_x509_cert_t cert)
Definition ffi_tls.cpp:201
int botan_tls_policy_view_text(botan_tls_policy_t policy, botan_view_ctx ctx, botan_view_str_fn view)
Definition ffi_tls.cpp:178
int botan_tls_credentials_destroy(botan_tls_credentials_t creds)
Definition ffi_tls.cpp:273
int botan_tls_policy_destroy(botan_tls_policy_t policy)
Definition ffi_tls.cpp:182
const char * text
Definition ffi_tls.h:75
struct botan_tls_policy_struct * botan_tls_policy_t
Definition ffi_tls.h:48
const char * path
Definition ffi_tls.h:139
botan_x509_crl_t crl
Definition ffi_tls.h:127
struct botan_tls_session_manager_struct * botan_tls_session_manager_t
Definition ffi_tls.h:183
const char * name
Definition ffi_tls.h:59
struct botan_tls_credentials_struct * botan_tls_credentials_t
Definition ffi_tls.h:106