include/boost/corosio/tls_context.hpp

100.0% Lines (20/20) 93.8% List of functions (30/32) 100.0% Branches (3/3)

[ ] prev/next file

tls_context.hpp

f(x) Functions (32)

Function Calls Lines Branches Blocks

Line	Branch	Hits	Source Code
1			//
2			// Copyright (c) 2025 Vinnie Falco ([email protected])
3			// Copyright (c) 2026 Michael Vandeberg
4			//
5			// Distributed under the Boost Software License, Version 1.0. (See accompanying
6			// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
7			//
8			// Official repository: https://github.com/cppalliance/corosio
9			//
10
11			#ifndef BOOST_COROSIO_TLS_CONTEXT_HPP
12			#define BOOST_COROSIO_TLS_CONTEXT_HPP
13
14			#include <boost/corosio/detail/config.hpp>
15
16			#include <cstddef>
17			#include <functional>
18			#include <span>
19			#include <system_error>
20			#include <memory>
21			#include <string_view>
22
23			namespace boost::corosio {
24
25			//
26			// Enumerations
27			//
28
29			/** TLS protocol version.
30
31			Specifies the minimum or maximum TLS protocol version to use
32			for connections. Only modern, secure versions are supported.
33
34			@see tls_context::set_min_protocol_version
35			@see tls_context::set_max_protocol_version
36			*/
37			enum class tls_version
38			{
39			/// TLS 1.2 (RFC 5246).
40			tls_1_2,
41
42			/// TLS 1.3 (RFC 8446).
43			tls_1_3
44			};
45
46			/** Certificate and key file format.
47
48			Specifies the encoding format for certificate and key data.
49
50			@see tls_context::use_certificate
51			@see tls_context::use_private_key
52			*/
53			enum class tls_file_format
54			{
55			/// PEM format (Base64-encoded with header/footer lines).
56			pem,
57
58			/// DER format (raw ASN.1 binary encoding).
59			der
60			};
61
62			/** Peer certificate verification mode.
63
64			Controls how the TLS implementation verifies the peer's
65			certificate during the handshake.
66
67			@see tls_context::set_verify_mode
68			*/
69			enum class tls_verify_mode
70			{
71			/// Do not request or verify the peer certificate.
72			none,
73
74			/// Request and verify the peer certificate if presented.
75			peer,
76
77			/// Require and verify the peer certificate (fail if not presented).
78			require_peer
79			};
80
81			/** Certificate revocation checking policy.
82
83			Controls how certificate revocation status is checked during
84			verification.
85
86			@see tls_context::set_revocation_policy
87			*/
88			enum class tls_revocation_policy
89			{
90			/// Do not check revocation status.
91			disabled,
92
93			/// Check revocation but allow connection if status is unknown.
94			soft_fail,
95
96			/// Require successful revocation check (fail if status is unknown).
97			hard_fail
98			};
99
100			/** Purpose for password callback invocation.
101
102			Indicates whether the password is needed for reading (decrypting)
103			or writing (encrypting) key material.
104
105			@see tls_context::set_password_callback
106			*/
107			enum class tls_password_purpose
108			{
109			/// Password needed to decrypt/read protected key material.
110			for_reading,
111
112			/// Password needed to encrypt/write protected key material.
113			for_writing
114			};
115
116			class tls_context;
117
118			/** A non-owning view of certificate verification state.
119
120			An instance is passed to the callback installed via
121			tls_context::set_verify_callback during the TLS handshake. It
122			exposes the backend's native verification handle so the callback
123			can inspect the certificate and chain currently being verified.
124
125			The value returned by native_handle() is, for the OpenSSL and
126			WolfSSL backends, an `X509_STORE_CTX*`. For portable inspection that
127			works across backends (for example certificate pinning), prefer
128			certificate(), which returns the DER encoding of the certificate
129			currently being verified.
130
131			@par Lifetime
132
133			The wrapped handle and the certificate() bytes are owned by the TLS
134			backend and are valid only for the duration of a single callback
135			invocation. Do not retain them beyond the call.
136
137			@see tls_context::set_verify_callback
138			*/
139			class verify_context
140			{
141			void* handle_;
142			unsigned char const* der_;
143			std::size_t der_len_;
144
145			public:
146			/** Construct from a native handle and the current certificate.
147
148			@param handle The backend verification handle (for OpenSSL and
149			WolfSSL, an `X509_STORE_CTX*`).
150			@param der Pointer to the DER encoding of the certificate under
151			verification, or `nullptr` if unavailable.
152			@param der_len Length of the DER encoding in bytes.
153			*/
154		6x	verify_context(
155			void* handle, unsigned char const* der, std::size_t der_len) noexcept
156		6x	: handle_(handle), der_(der), der_len_(der_len)
157			{
158		6x	}
159
160			/** Return the native verification handle.
161
162			Cast the result to the backend's verification context type
163			(e.g. `X509_STORE_CTX*`) to inspect the certificate chain using
164			backend-specific APIs.
165
166			@return The native handle, or `nullptr` if none is available.
167			*/
168		1x	void* native_handle() const noexcept { return handle_; }
169
170			/** Return the DER encoding of the certificate being verified.
171
172			This is the portable way to inspect the peer certificate from a
173			verification callback: it works identically on every backend,
174			without depending on backend-specific build options. A DER
175			certificate is an ASN.1 `SEQUENCE`, so the first byte is `0x30`.
176
177			@return A view of the certificate's DER bytes, valid only for the
178			duration of the callback. Empty if the certificate is not
179			available.
180			*/
181		4x	std::span<unsigned char const> certificate() const noexcept
182			{
183		4x	return {der_, der_len_};
184			}
185			};
186
187			namespace detail {
188			struct tls_context_data;
189			tls_context_data const& get_tls_context_data(tls_context const&) noexcept;
190			} // namespace detail
191
192			/** A portable TLS context for certificate and settings storage.
193
194			The `tls_context` class provides a backend-agnostic interface for
195			configuring TLS connections. It stores credentials (certificates and
196			private keys), trust anchors, protocol settings, and verification
197			options that are used when establishing TLS connections.
198
199			This class is a shared handle to an opaque implementation. Copies
200			share the same underlying state. This allows contexts to be passed
201			by value and shared across multiple TLS streams.
202
203			This class abstracts the configuration phase of TLS across multiple
204			backend implementations (OpenSSL, WolfSSL, mbedTLS, Schannel, etc.),
205			allowing portable code that works regardless of which TLS library
206			is linked.
207
208			@par Modification After Stream Creation
209
210			Modifying a context after a TLS stream has been created from it
211			results in undefined behavior. The context's configuration is
212			captured when the first stream is constructed, and subsequent
213			modifications are not reflected in existing or new streams
214			sharing the context.
215
216			If different configurations are needed, create separate context
217			objects.
218
219			@par Thread Safety
220
221			Distinct objects: Safe.
222
223			Shared objects: Unsafe. A context must not be modified while
224			any thread is creating streams from it.
225
226			@par Example
227			@code
228			// Create a client context with system trust anchors
229			corosio::tls_context ctx;
230			if (auto ec = ctx.set_default_verify_paths())
231			co_return;
232			if (auto ec = ctx.set_verify_mode( corosio::tls_verify_mode::peer ))
233			co_return;
234
235			// Use with a TLS stream
236			corosio::openssl_stream secure( &sock, ctx );
237			secure.set_hostname( "example.com" );
238			if (auto [ec] = co_await secure.handshake( corosio::tls_role::client ); ec)
239			co_return;
240			@endcode
241
242			@see tls_role
243			*/
244			#ifdef _MSC_VER
245			#pragma warning(push)
246			#pragma warning(disable : 4251) // shared_ptr needs dll-interface
247			#endif
248			class BOOST_COROSIO_DECL tls_context
249			{
250			struct implementation;
251			std::shared_ptr<implementation> impl_;
252
253			friend detail::tls_context_data const&
254			detail::get_tls_context_data(tls_context const&) noexcept;
255
256			public:
257			/** Construct a default TLS context.
258
259			Creates a context with default settings suitable for TLS 1.2
260			and TLS 1.3 connections. No certificates or trust anchors are
261			loaded; call the appropriate methods to configure credentials
262			and verification.
263
264			@par Example
265			@code
266			corosio::tls_context ctx;
267			@endcode
268			*/
269			tls_context();
270
271			/** Copy constructor.
272
273			Creates a new handle that shares ownership of the underlying
274			TLS context state with `other`.
275
276			@param other The context to copy from.
277			*/
278		4307x	tls_context(tls_context const& other) = default;
279
280			/** Copy assignment operator.
281
282			Releases the current context's shared ownership and acquires
283			shared ownership of `other`'s underlying state.
284
285			@param other The context to copy from.
286
287			@return Reference to this context.
288			*/
289		1x	tls_context& operator=(tls_context const& other) = default;
290
291			/** Move constructor.
292
293			Transfers ownership of the TLS context from another instance.
294			After the move, `other` is in a valid but empty state.
295
296			@param other The context to move from.
297			*/
298		4213x	tls_context(tls_context&& other) noexcept = default;
299
300			/** Move assignment operator.
301
302			Releases the current context's shared ownership and transfers
303			ownership from another instance. After the move, `other` is
304			in a valid but empty state.
305
306			@param other The context to move from.
307
308			@return Reference to this context.
309			*/
310		1x	tls_context& operator=(tls_context&& other) noexcept = default;
311
312			/** Destructor.
313
314			Releases this handle's shared ownership of the underlying
315			context. The context state is destroyed when the last handle
316			is released.
317			*/
318		12780x	~tls_context() = default;
319
320			//
321			// Credential Loading
322			//
323
324			/** Load the entity certificate from a memory buffer.
325
326			Sets the certificate that identifies this endpoint to the peer.
327			For servers, this is the server certificate. For clients using
328			mutual TLS, this is the client certificate.
329
330			The certificate must match the private key loaded via
331			`use_private_key()` or `use_private_key_file()`.
332
333			@param certificate The certificate data.
334
335			@param format The encoding format of the certificate data.
336
337			@return Success. The certificate is recorded and decoded when the
338			native context is first built; a malformed certificate surfaces
339			as a handshake failure.
340
341			@see use_certificate_file
342			@see use_private_key
343			*/
344			[[nodiscard]] std::error_code
345			use_certificate(std::string_view certificate, tls_file_format format);
346
347			/** Load the entity certificate from a file.
348
349			Sets the certificate that identifies this endpoint to the peer.
350			For servers, this is the server certificate. For clients using
351			mutual TLS, this is the client certificate.
352
353			@param filename Path to the certificate file.
354
355			@param format The encoding format of the file.
356
357			@return Success, or an error if the file could not be read. The
358			certificate is decoded when the native context is first built;
359			a malformed certificate surfaces as a handshake failure.
360
361			@par Example
362			@code
363			if (auto ec = ctx.use_certificate_file(
364			"server.crt", tls_file_format::pem ))
365			return;
366			@endcode
367
368			@see use_certificate
369			@see use_private_key_file
370			*/
371			[[nodiscard]] std::error_code
372			use_certificate_file(std::string_view filename, tls_file_format format);
373
374			/** Load a certificate chain from a memory buffer.
375
376			Loads the entity certificate followed by intermediate CA certificates.
377			The chain should be ordered from leaf to root (excluding the root).
378			This is the typical format for PEM certificate bundles.
379
380			@param chain The certificate chain data in PEM format (concatenated
381			certificates).
382
383			@return Success. The chain is recorded and decoded when the native
384			context is first built; a malformed chain surfaces as a
385			handshake failure.
386
387			@see use_certificate_chain_file
388			*/
389			[[nodiscard]] std::error_code use_certificate_chain(std::string_view chain);
390
391			/** Load a certificate chain from a file.
392
393			Loads the entity certificate followed by intermediate CA certificates
394			from a PEM file. The file should contain concatenated PEM certificates
395			ordered from leaf to root (excluding the root).
396
397			@param filename Path to the certificate chain file.
398
399			@return Success, or an error if the file could not be read. The
400			chain is decoded when the native context is first built; a
401			malformed chain surfaces as a handshake failure.
402
403			@par Example
404			@code
405			if (auto ec = ctx.use_certificate_chain_file( "fullchain.pem" ))
406			return;
407			@endcode
408
409			@see use_certificate_chain
410			*/
411			[[nodiscard]] std::error_code use_certificate_chain_file(std::string_view filename);
412
413			/** Load the private key from a memory buffer.
414
415			Sets the private key corresponding to the entity certificate.
416			The key must match the certificate loaded via `use_certificate()`
417			or `use_certificate_chain()`.
418
419			If the key is encrypted, set a password callback via
420			`set_password_callback()` before calling this function.
421
422			@param private_key The private key data.
423
424			@param format The encoding format of the key data.
425
426			@return Success. The key is recorded and decoded when the native
427			context is first built; a malformed key, a missing password
428			callback for an encrypted key, or a certificate mismatch
429			surfaces as a handshake failure.
430
431			@see use_private_key_file
432			@see set_password_callback
433			*/
434			[[nodiscard]] std::error_code
435			use_private_key(std::string_view private_key, tls_file_format format);
436
437			/** Load the private key from a file.
438
439			Sets the private key corresponding to the entity certificate.
440			The key must match the certificate loaded via `use_certificate_file()`
441			or `use_certificate_chain_file()`.
442
443			If the key file is encrypted, set a password callback via
444			`set_password_callback()` before calling this function.
445
446			@param filename Path to the private key file.
447
448			@param format The encoding format of the file.
449
450			@return Success, or an error if the file could not be read. The
451			key is decoded when the native context is first built; a
452			malformed key or a certificate mismatch surfaces as a
453			handshake failure.
454
455			@par Example
456			@code
457			if (auto ec = ctx.use_private_key_file(
458			"server.key", tls_file_format::pem ))
459			return;
460			@endcode
461
462			@see use_private_key
463			@see set_password_callback
464			*/
465			[[nodiscard]] std::error_code
466			use_private_key_file(std::string_view filename, tls_file_format format);
467
468			/** Load credentials from a PKCS#12 bundle in memory.
469
470			PKCS#12 (also known as PFX) is a binary format that bundles a
471			certificate, private key, and optionally intermediate certificates
472			into a single password-protected file.
473
474			@param data The PKCS#12 bundle data.
475
476			@param passphrase The password protecting the bundle.
477
478			@return Success. The bundle is recorded and decoded into the
479			certificate, private key, and chain when the native context is
480			first built; a malformed bundle or wrong passphrase surfaces as
481			a handshake failure.
482
483			@note Intermediate certificates inside the bundle are loaded and
484			sent during the handshake on both backends.
485
486			@see use_pkcs12_file
487			*/
488			[[nodiscard]] std::error_code
489			use_pkcs12(std::string_view data, std::string_view passphrase);
490
491			/** Load credentials from a PKCS#12 file.
492
493			PKCS#12 (also known as PFX) is a binary format that bundles a
494			certificate, private key, and optionally intermediate certificates
495			into a single password-protected file. This is common on Windows
496			and for certificates exported from browsers.
497
498			@param filename Path to the PKCS#12 file.
499
500			@param passphrase The password protecting the file.
501
502			@return Success, or an error if the file could not be read. The
503			bundle is decoded when the native context is first built; a
504			malformed bundle or wrong passphrase surfaces as a handshake
505			failure.
506
507			@note Intermediate certificates inside the bundle are loaded and
508			sent during the handshake on both backends.
509
510			@par Example
511			@code
512			if (auto ec = ctx.use_pkcs12_file( "credentials.pfx", "secret" ))
513			return;
514			@endcode
515
516			@see use_pkcs12
517			*/
518			[[nodiscard]] std::error_code
519			use_pkcs12_file(std::string_view filename, std::string_view passphrase);
520
521			//
522			// Trust Anchors
523			//
524
525			/** Add a certificate authority for peer verification.
526
527			Adds a single CA certificate to the trust store used for verifying
528			peer certificates. Call this multiple times to add multiple CAs,
529			or use `load_verify_file()` for a bundle.
530
531			@param ca The CA certificate data in PEM format.
532
533			@return Success. The certificate is recorded and decoded when the
534			native context is first built; a malformed certificate
535			surfaces as a handshake failure.
536
537			@see load_verify_file
538			@see set_default_verify_paths
539			*/
540			[[nodiscard]] std::error_code add_certificate_authority(std::string_view ca);
541
542			/** Load CA certificates from a file.
543
544			Loads one or more CA certificates from a PEM file. The file may
545			contain multiple concatenated PEM certificates.
546
547			@param filename Path to a PEM file containing CA certificates.
548
549			@return Success, or an error if the file could not be read. The
550			certificates are decoded when the native context is first
551			built; malformed certificates surface as a handshake failure.
552
553			@par Example
554			@code
555			if (auto ec = ctx.load_verify_file(
556			"/etc/ssl/certs/ca-certificates.crt" ))
557			return;
558			@endcode
559
560			@see add_certificate_authority
561			@see add_verify_path
562			*/
563			[[nodiscard]] std::error_code load_verify_file(std::string_view filename);
564
565			/** Add a directory of CA certificates for verification.
566
567			Adds a directory of CA certificates to the trust store. The
568			directory is applied when the native context is first built from
569			this context.
570
571			The expected directory layout depends on the backend. OpenSSL
572			performs on-demand lookups and requires each certificate file to
573			be named by its subject-name hash (as generated by
574			`openssl rehash` or `c_rehash`); WolfSSL loads every certificate
575			file in the directory.
576
577			@param path Path to the directory of CA certificates.
578
579			@return Success. The path is recorded and applied when the native
580			context is built; a directory that cannot be read at that time
581			is skipped rather than reported here.
582
583			@par Example
584			@code
585			if (auto ec = ctx.add_verify_path( "/etc/ssl/certs" ))
586			return;
587			@endcode
588
589			@see load_verify_file
590			@see set_default_verify_paths
591			*/
592			[[nodiscard]] std::error_code add_verify_path(std::string_view path);
593
594			/** Use the system default CA certificate store.
595
596			Configures the context to use the operating system's default
597			trust store for peer certificate verification. This is the
598			recommended approach for HTTPS clients connecting to public
599			servers.
600
601			The system store is loaded when the native context is first built
602			from this context. For a verified-safe client, combine this with
603			`set_verify_mode( tls_verify_mode::peer )` and, when connecting by
604			name, `tls_stream::set_hostname()`.
605
606			@return Success. The request is recorded and applied when the
607			native context is built; if the system store cannot be loaded
608			at that time it is skipped rather than reported here, so a
609			context that must reject unverified peers should also use
610			`set_verify_mode( tls_verify_mode::peer )`.
611
612			@note The OpenSSL backend honors the `SSL_CERT_FILE` and
613			`SSL_CERT_DIR` environment variables. The WolfSSL backend
614			requires a build with `WOLFSSL_SYS_CA_CERTS`; without it the
615			system store is unavailable and this call has no effect.
616
617			@par Example
618			@code
619			// Trust the same CAs as the system
620			if (auto ec = ctx.set_default_verify_paths())
621			return;
622			if (auto ec = ctx.set_verify_mode( tls_verify_mode::peer ))
623			return;
624			@endcode
625
626			@see load_verify_file
627			@see add_verify_path
628			@see set_verify_mode
629			*/
630			[[nodiscard]] std::error_code set_default_verify_paths();
631
632			//
633			// Protocol Configuration
634			//
635
636			/** Set the minimum TLS protocol version.
637
638			Connections will reject protocol versions older than this.
639			The default allows TLS 1.2 and newer.
640
641			@param v The minimum protocol version to accept.
642
643			@return Success. The version is recorded and applied when the
644			native context is first built.
645
646			@par Example
647			@code
648			// Require TLS 1.3 minimum
649			if (auto ec = ctx.set_min_protocol_version( tls_version::tls_1_3 ))
650			return;
651			@endcode
652
653			@see set_max_protocol_version
654			*/
655			[[nodiscard]] std::error_code set_min_protocol_version(tls_version v);
656
657			/** Set the maximum TLS protocol version.
658
659			Connections will not negotiate protocol versions newer than this.
660			The default allows the newest supported version.
661
662			@param v The maximum protocol version to accept.
663
664			@return Success. The version is recorded and applied when the
665			native context is first built.
666
667			@note On WolfSSL the ceiling is applied by selecting a
668			version-specific method (no native set-max API exists); an
669			invalid window where the minimum exceeds the maximum yields a
670			context that fails the handshake.
671
672			@see set_min_protocol_version
673			*/
674			[[nodiscard]] std::error_code set_max_protocol_version(tls_version v);
675
676			/** Set the allowed cipher suites.
677
678			Configures which cipher suites may be used for connections.
679			The format is backend-specific but typically follows OpenSSL
680			cipher list syntax.
681
682			@param ciphers The cipher suite specification string.
683
684			@return Success. The string is recorded and applied when the
685			native context is first built; an invalid cipher string
686			surfaces as a handshake failure.
687
688			@par Example
689			@code
690			// TLS 1.2 cipher suites (OpenSSL format)
691			if (auto ec = ctx.set_ciphersuites( "ECDHE+AESGCM:ECDHE+CHACHA20" ))
692			return;
693			@endcode
694
695			@note This configures cipher suites for TLS 1.2 and below. For
696			TLS 1.3, use @ref set_ciphersuites_tls13.
697			*/
698			[[nodiscard]] std::error_code set_ciphersuites(std::string_view ciphers);
699
700			/** Set the allowed TLS 1.3 cipher suites.
701
702			TLS 1.3 uses a distinct, fixed set of cipher suites configured
703			separately from earlier versions. The format is a colon-separated
704			list of TLS 1.3 suite names.
705
706			@param ciphers The TLS 1.3 cipher suite list.
707
708			@return Success. The string is recorded and applied when the
709			native context is first built; an invalid cipher string
710			surfaces as a handshake failure.
711
712			@par Example
713			@code
714			if (auto ec = ctx.set_ciphersuites_tls13(
715			"TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256" ))
716			return;
717			@endcode
718
719			@note On the WolfSSL backend, TLS 1.2 and TLS 1.3 suites share a
720			single cipher list; this call and @ref set_ciphersuites are
721			merged into one list.
722
723			@see set_ciphersuites
724			*/
725			[[nodiscard]] std::error_code set_ciphersuites_tls13(std::string_view ciphers);
726
727			/** Set the ALPN protocol list.
728
729			Configures Application-Layer Protocol Negotiation (ALPN) for
730			the connection. ALPN is used to negotiate which application
731			protocol to use over the TLS connection (e.g., "h2" for HTTP/2,
732			"http/1.1" for HTTP/1.1).
733
734			The protocols are tried in preference order (first = highest).
735
736			@param protocols Ordered list of protocol identifiers.
737
738			@return Success, or an error if ALPN configuration fails.
739
740			@note Read the negotiated protocol after the handshake via
741			@ref tls_stream::alpn_protocol. On WolfSSL, ALPN requires a
742			build with `HAVE_ALPN`; without it, offering protocols fails
743			the handshake with `std::errc::function_not_supported` rather
744			than negotiate nothing silently.
745
746			@par Example
747			@code
748			// Prefer HTTP/2, fall back to HTTP/1.1
749			if (auto ec = ctx.set_alpn( { "h2", "http/1.1" } ))
750			return;
751			@endcode
752			*/
753			[[nodiscard]] std::error_code set_alpn(std::initializer_list<std::string_view> protocols);
754
755			//
756			// Certificate Verification
757			//
758
759			/** Set the peer certificate verification mode.
760
761			Controls whether and how peer certificates are verified during
762			the TLS handshake.
763
764			@param mode The verification mode to use.
765
766			@return Success. The mode is recorded and applied when the native
767			context is first built.
768
769			@par Example
770			@code
771			// Verify peer certificate (typical for clients; servers doing
772			// mTLS use tls_verify_mode::require_peer instead)
773			if (auto ec = ctx.set_verify_mode( tls_verify_mode::peer ))
774			return;
775			@endcode
776
777			@see tls_verify_mode
778			*/
779			[[nodiscard]] std::error_code set_verify_mode(tls_verify_mode mode);
780
781			/** Set the maximum certificate chain verification depth.
782
783			Limits how many intermediate certificates can appear between
784			the peer certificate and a trusted root. The default is
785			typically 100, which is sufficient for most certificate chains.
786
787			@param depth Maximum number of intermediate certificates allowed.
788
789			@return Success. The depth is recorded and applied when the native
790			context is first built.
791			*/
792			[[nodiscard]] std::error_code set_verify_depth(int depth);
793
794			/** Set a custom certificate verification callback.
795
796			Installs a callback that is invoked during certificate chain
797			verification. The callback can perform additional validation
798			beyond the standard checks and can override verification
799			results.
800
801			The callback receives the built-in verification result so far and
802			a verify_context describing the certificate being verified. Return
803			`true` to accept the certificate, `false` to reject. Inspect the
804			certificate portably via `verify_context::certificate()` (its DER
805			encoding) — for example to pin a specific certificate.
806
807			@par Backend Support
808
809			The exact set of certificates the callback sees differs by backend:
810
811			- OpenSSL: the callback runs once per certificate in the chain,
812			including certificates that passed the built-in checks. It can
813			therefore both relax verification (return `true` for a
814			certificate the library rejected) and tighten it (return `false`
815			for a certificate the library accepted, e.g. pinning).
816			- WolfSSL built with `WOLFSSL_ALWAYS_VERIFY_CB` (implied by
817			`--enable-opensslextra`): same as OpenSSL.
818			- WolfSSL without that option: the library invokes the callback
819			only on verification failure, so it cannot be honored on a
820			successful handshake. To avoid silently ignoring a
821			verification-tightening callback (which would fail open), a
822			context that carries a callback instead fails the handshake
823			with `std::errc::function_not_supported` on such a build. Rebuild
824			WolfSSL with `WOLFSSL_ALWAYS_VERIFY_CB`, or omit the callback.
825
826			@tparam Callback A callable with signature
827			`bool( bool preverified, verify_context& ctx )`.
828
829			@param callback The verification callback. Recorded here and
830			applied during the handshake; on a WolfSSL build that
831			cannot honor it, the handshake fails with
832			`std::errc::function_not_supported` (see Backend Support).
833
834			@par Example
835			@code
836			if (auto ec = ctx.set_verify_mode( tls_verify_mode::peer ))
837			return;
838			ctx.set_verify_callback(
839			[]( bool preverified, verify_context& ctx ) -> bool
840			{
841			if( ! preverified )
842			return false;
843			// Pin: accept only a certificate whose DER matches.
844			auto der = ctx.certificate();
845			return der.size() == expected_pin.size() &&
846			std::equal( der.begin(), der.end(), expected_pin.begin() );
847			});
848			@endcode
849
850			@see verify_context
851			@see set_verify_mode
852			*/
853			template<typename Callback>
854			void set_verify_callback(Callback callback);
855
856			/** Set a callback for Server Name Indication (SNI).
857
858			For server connections, this callback is invoked during the TLS
859			handshake when a client sends an SNI extension. The callback
860			receives the requested hostname and can accept or reject the
861			connection.
862
863			@tparam Callback A callable with signature
864			`bool( std::string_view hostname )`.
865
866			@param callback The SNI callback. Return `true` to accept the
867			connection or `false` to reject it with an alert.
868
869			@par Example
870			@code
871			// Accept connections for specific domains only
872			ctx.set_servername_callback(
873			[]( std::string_view hostname ) -> bool
874			{
875			return hostname == "api.example.com" \|\|
876			hostname == "www.example.com";
877			});
878			@endcode
879
880			@note For virtual hosting with different certificates per hostname,
881			create separate contexts and select the appropriate one before
882			creating the TLS stream.
883
884			@see tls_stream::set_hostname
885			*/
886			template<typename Callback>
887			void set_servername_callback(Callback callback);
888
889			private:
890			void set_servername_callback_impl(
891			std::function<bool(std::string_view)> callback);
892
893			void set_password_callback_impl(
894			std::function<std::string(std::size_t, tls_password_purpose)> callback);
895
896			void set_verify_callback_impl(
897			std::function<bool(bool, verify_context&)> callback);
898
899			public:
900			//
901			// Revocation Checking
902			//
903
904			/** Add a Certificate Revocation List from memory.
905
906			Adds a CRL to the verification store for checking whether
907			certificates have been revoked. CRLs are typically fetched
908			from the URLs in a certificate's CRL Distribution Points
909			extension.
910
911			@param crl The CRL data in DER or PEM format.
912
913			@return Success. The CRL is recorded and decoded when the native
914			context is first built; a malformed CRL surfaces as a
915			handshake failure.
916
917			@note CRLs are consulted only when a revocation policy is set via
918			@ref set_revocation_policy. On WolfSSL, CRL checking requires a
919			build with `HAVE_CRL`; without it, supplying a CRL or a
920			revocation policy fails the handshake with
921			`std::errc::function_not_supported`.
922
923			@see add_crl_file
924			@see set_revocation_policy
925			*/
926			[[nodiscard]] std::error_code add_crl(std::string_view crl);
927
928			/** Add a Certificate Revocation List from a file.
929
930			Adds a CRL to the verification store for checking whether
931			certificates have been revoked.
932
933			@param filename Path to a CRL file (DER or PEM format).
934
935			@return Success, or an error if the file could not be read. The
936			CRL is decoded when the native context is first built; a
937			malformed CRL surfaces as a handshake failure.
938
939			@note CRLs are consulted only when a revocation policy is set via
940			@ref set_revocation_policy (WolfSSL requires a `HAVE_CRL`
941			build).
942
943			@par Example
944			@code
945			if (auto ec = ctx.add_crl_file( "issuer.crl" ))
946			return;
947			@endcode
948
949			@see add_crl
950			@see set_revocation_policy
951			*/
952			[[nodiscard]] std::error_code add_crl_file(std::string_view filename);
953
954			/** Set the certificate revocation checking policy.
955
956			Controls how certificate revocation status is checked during
957			verification via CRLs.
958
959			@param policy The revocation checking policy.
960
961			@par Example
962			@code
963			// Require successful revocation check
964			ctx.set_revocation_policy( tls_revocation_policy::hard_fail );
965
966			// Check but allow unknown status
967			ctx.set_revocation_policy( tls_revocation_policy::soft_fail );
968			@endcode
969
970			@note Revocation is checked via CRLs supplied with @ref add_crl /
971			@ref add_crl_file. `soft_fail` accepts a certificate whose
972			status cannot be determined (missing/expired CRL) but rejects
973			one that is actually revoked; `hard_fail` also rejects unknown
974			status. OCSP-based revocation is not available (see the TLS
975			guide). On WolfSSL a non-disabled policy requires a `HAVE_CRL`
976			build, else the handshake fails with
977			`std::errc::function_not_supported`.
978
979			@see tls_revocation_policy
980			@see add_crl
981			*/
982			void set_revocation_policy(tls_revocation_policy policy);
983
984			//
985			// Password Handling
986			//
987
988			/** Set the password callback for encrypted keys.
989
990			Installs a callback that provides passwords for encrypted
991			private keys and PKCS#12 files. The callback is invoked when
992			loading encrypted key material.
993
994			@tparam Callback A callable with signature
995			`std::string( std::size_t max_length, password_purpose purpose )`.
996
997			@param callback The password callback. It receives the maximum
998			password length and the purpose (reading or writing), and
999			returns the password string.
1000
1001			@par Example
1002			@code
1003			ctx.set_password_callback(
1004			[]( std::size_t max_len, tls_password_purpose purpose )
1005			{
1006			// In practice, prompt user or read from secure storage
1007			return std::string( "my-key-password" );
1008			});
1009
1010			// Now load encrypted key
1011			if (auto ec = ctx.use_private_key_file(
1012			"encrypted.key", tls_file_format::pem ))
1013			return;
1014			@endcode
1015
1016			@see tls_password_purpose
1017			*/
1018			template<typename Callback>
1019			void set_password_callback(Callback callback);
1020			};
1021			#ifdef _MSC_VER
1022			#pragma warning(pop)
1023			#endif
1024
1025			template<typename Callback>
1026			void
1027		9x	tls_context::set_servername_callback(Callback callback)
1028			{
1029	1/1 ✓ Branch 4 → 5 taken 9 times.	9x	set_servername_callback_impl(std::move(callback));
1030		9x	}
1031
1032			template<typename Callback>
1033			void
1034		6x	tls_context::set_password_callback(Callback callback)
1035			{
1036	1/1 ✓ Branch 4 → 5 taken 6 times.	6x	set_password_callback_impl(std::move(callback));
1037		6x	}
1038
1039			template<typename Callback>
1040			void
1041		7x	tls_context::set_verify_callback(Callback callback)
1042			{
1043	1/1 ✓ Branch 4 → 5 taken 7 times.	7x	set_verify_callback_impl(std::move(callback));
1044		7x	}
1045
1046			} // namespace boost::corosio
1047
1048			#endif
1049