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