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