TLA Line data Source code
1 : //
2 : // Copyright (c) 2025 Vinnie Falco (vinnie.falco@gmail.com)
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 HIT 1 : 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 1 : 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 1 : 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 1 : 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 36 : ~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 1 : tls_context::set_servername_callback(Callback callback)
922 : {
923 1 : set_servername_callback_impl(std::move(callback));
924 1 : }
925 :
926 : template<typename Callback>
927 : void
928 1 : tls_context::set_password_callback(Callback callback)
929 : {
930 1 : set_password_callback_impl(std::move(callback));
931 1 : }
932 :
933 : } // namespace boost::corosio
934 :
935 : #endif
|
