include/boost/corosio/tls_context.hpp

100.0% Lines (11/11) 100.0% List of functions (11/11) 100.0% Branches (2/2)

[ ] prev/next file

tls_context.hpp

f(x) Functions (11)

Function Calls Lines Branches Blocks

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