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