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