. /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
  409 + `std::errc::function_not_supported`. Load the certificate
  410 + and key separately via `use_certificate_chain()` and
  411 + `use_private_key()` instead.
  412 +
408   @see use_pkcs12_file 413   @see use_pkcs12_file
409   */ 414   */
410   std::error_code 415   std::error_code
411   use_pkcs12(std::string_view data, std::string_view passphrase); 416   use_pkcs12(std::string_view data, std::string_view passphrase);
412   417  
413   /** Load credentials from a PKCS#12 file. 418   /** Load credentials from a PKCS#12 file.
414   419  
415   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
416   certificate, private key, and optionally intermediate certificates 421   certificate, private key, and optionally intermediate certificates
417   into a single password-protected file. This is common on Windows 422   into a single password-protected file. This is common on Windows
418   and for certificates exported from browsers. 423   and for certificates exported from browsers.
419   424  
420   @param filename Path to the PKCS#12 file. 425   @param filename Path to the PKCS#12 file.
421   426  
422   @param passphrase The password protecting the file. 427   @param passphrase The password protecting the file.
423   428  
424   @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,
425   parsed, or the passphrase is incorrect. 430   parsed, or the passphrase is incorrect.
426   431  
  432 + @note Not yet implemented in this release; returns
  433 + `std::errc::function_not_supported`. Load the certificate
  434 + and key separately via `use_certificate_chain_file()` and
  435 + `use_private_key_file()` instead.
  436 +
427   @par Example 437   @par Example
428   @code 438   @code
429   ctx.use_pkcs12_file( "credentials.pfx", "secret" ); 439   ctx.use_pkcs12_file( "credentials.pfx", "secret" );
430   @endcode 440   @endcode
431   441  
432   @see use_pkcs12 442   @see use_pkcs12
433   */ 443   */
434   std::error_code 444   std::error_code
435   use_pkcs12_file(std::string_view filename, std::string_view passphrase); 445   use_pkcs12_file(std::string_view filename, std::string_view passphrase);
436   446  
437   // 447   //
438   // Trust Anchors 448   // Trust Anchors
439   // 449   //
440   450  
441   /** Add a certificate authority for peer verification. 451   /** Add a certificate authority for peer verification.
442   452  
443   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
444   peer certificates. Call this multiple times to add multiple CAs, 454   peer certificates. Call this multiple times to add multiple CAs,
445   or use `load_verify_file()` for a bundle. 455   or use `load_verify_file()` for a bundle.
446   456  
447   @param ca The CA certificate data in PEM format. 457   @param ca The CA certificate data in PEM format.
448   458  
449   @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.
450   460  
451   @see load_verify_file 461   @see load_verify_file
452   @see set_default_verify_paths 462   @see set_default_verify_paths
453   */ 463   */
454   std::error_code add_certificate_authority(std::string_view ca); 464   std::error_code add_certificate_authority(std::string_view ca);
455   465  
456   /** Load CA certificates from a file. 466   /** Load CA certificates from a file.
457   467  
458   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
459   contain multiple concatenated PEM certificates. 469   contain multiple concatenated PEM certificates.
460   470  
461   @param filename Path to a PEM file containing CA certificates. 471   @param filename Path to a PEM file containing CA certificates.
462   472  
463   @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.
464   474  
465   @par Example 475   @par Example
466   @code 476   @code
467   // Load a custom CA bundle 477   // Load a custom CA bundle
468   ctx.load_verify_file( "/etc/ssl/certs/ca-certificates.crt" ); 478   ctx.load_verify_file( "/etc/ssl/certs/ca-certificates.crt" );
469   @endcode 479   @endcode
470   480  
471   @see add_certificate_authority 481   @see add_certificate_authority
472   @see add_verify_path 482   @see add_verify_path
473   */ 483   */
474   std::error_code load_verify_file(std::string_view filename); 484   std::error_code load_verify_file(std::string_view filename);
475   485  
476   /** Add a directory of CA certificates for verification. 486   /** Add a directory of CA certificates for verification.
477   487  
478   Adds a directory containing CA certificate files. Each file must 488   Adds a directory containing CA certificate files. Each file must
479   contain a single certificate in PEM format, named using the 489   contain a single certificate in PEM format, named using the
480   subject name hash (as generated by `openssl rehash` or 490   subject name hash (as generated by `openssl rehash` or
481   `c_rehash`). 491   `c_rehash`).
482   492  
483   @param path Path to the directory containing hashed CA certificates. 493   @param path Path to the directory containing hashed CA certificates.
484   494  
485   @return Success, or an error if the directory is invalid. 495   @return Success, or an error if the directory is invalid.
486   496  
  497 + @note Not yet applied by the backends in this release; the
  498 + directory is accepted but never loaded. Use
  499 + `load_verify_file()` or `add_certificate_authority()` to
  500 + supply trust anchors.
  501 +
487   @par Example 502   @par Example
488   @code 503   @code
489   ctx.add_verify_path( "/etc/ssl/certs" ); 504   ctx.add_verify_path( "/etc/ssl/certs" );
490   @endcode 505   @endcode
491   506  
492   @see load_verify_file 507   @see load_verify_file
493   @see set_default_verify_paths 508   @see set_default_verify_paths
494   */ 509   */
495   std::error_code add_verify_path(std::string_view path); 510   std::error_code add_verify_path(std::string_view path);
496   511  
497   /** Use the system default CA certificate store. 512   /** Use the system default CA certificate store.
498   513  
499   Configures the context to use the operating system's default 514   Configures the context to use the operating system's default
500   trust store for peer certificate verification. This is the 515   trust store for peer certificate verification. This is the
501   recommended approach for HTTPS clients connecting to public 516   recommended approach for HTTPS clients connecting to public
502   servers. 517   servers.
503   518  
504   On different platforms this uses: 519   On different platforms this uses:
505   - Linux: `/etc/ssl/certs` or distribution-specific paths 520   - Linux: `/etc/ssl/certs` or distribution-specific paths
506   - macOS: System Keychain 521   - macOS: System Keychain
507   - Windows: Windows Certificate Store 522   - Windows: Windows Certificate Store
508   523  
509   @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.
510   525  
  526 + @note Not yet applied by the backends in this release. This is a
  527 + no-op: the OS trust store is never loaded, so a client that
  528 + relies on it has an empty trust store and cannot verify a
  529 + public server. To verify a peer today, supply CA certificates
  530 + explicitly via `load_verify_file()` or
  531 + `add_certificate_authority()`.
  532 +
511   @par Example 533   @par Example
512   @code 534   @code
513   // Trust the same CAs as the system 535   // Trust the same CAs as the system
514   ctx.set_default_verify_paths(); 536   ctx.set_default_verify_paths();
515   @endcode 537   @endcode
516   538  
517   @see load_verify_file 539   @see load_verify_file
518   @see add_verify_path 540   @see add_verify_path
519   */ 541   */
520   std::error_code set_default_verify_paths(); 542   std::error_code set_default_verify_paths();
521   543  
522   // 544   //
523   // Protocol Configuration 545   // Protocol Configuration
524   // 546   //
525   547  
526   /** Set the minimum TLS protocol version. 548   /** Set the minimum TLS protocol version.
527   549  
528   Connections will reject protocol versions older than this. 550   Connections will reject protocol versions older than this.
529   The default allows TLS 1.2 and newer. 551   The default allows TLS 1.2 and newer.
530   552  
531   @param v The minimum protocol version to accept. 553   @param v The minimum protocol version to accept.
532   554  
533   @return Success, or an error if the version is not supported 555   @return Success, or an error if the version is not supported
534   by the backend. 556   by the backend.
535   557  
  558 + @note Not yet applied by the backends in this release; the bound
  559 + is accepted but has no effect. The negotiated range is
  560 + whatever the native default method provides.
  561 +
536   @par Example 562   @par Example
537   @code 563   @code
538   // Require TLS 1.3 minimum 564   // Require TLS 1.3 minimum
539   ctx.set_min_protocol_version( tls_version::tls_1_3 ); 565   ctx.set_min_protocol_version( tls_version::tls_1_3 );
540   @endcode 566   @endcode
541   567  
542   @see set_max_protocol_version 568   @see set_max_protocol_version
543   */ 569   */
544   std::error_code set_min_protocol_version(tls_version v); 570   std::error_code set_min_protocol_version(tls_version v);
545   571  
546   /** Set the maximum TLS protocol version. 572   /** Set the maximum TLS protocol version.
547   573  
548   Connections will not negotiate protocol versions newer than this. 574   Connections will not negotiate protocol versions newer than this.
549   The default allows the newest supported version. 575   The default allows the newest supported version.
550   576  
551   @param v The maximum protocol version to accept. 577   @param v The maximum protocol version to accept.
552   578  
553   @return Success, or an error if the version is not supported 579   @return Success, or an error if the version is not supported
554   by the backend. 580   by the backend.
555   581  
  582 + @note Not yet applied by the backends in this release; the bound
  583 + is accepted but has no effect. The negotiated range is
  584 + whatever the native default method provides.
  585 +
556   @see set_min_protocol_version 586   @see set_min_protocol_version
557   */ 587   */
558   std::error_code set_max_protocol_version(tls_version v); 588   std::error_code set_max_protocol_version(tls_version v);
559   589  
560   /** Set the allowed cipher suites. 590   /** Set the allowed cipher suites.
561   591  
562   Configures which cipher suites may be used for connections. 592   Configures which cipher suites may be used for connections.
563   The format is backend-specific but typically follows OpenSSL 593   The format is backend-specific but typically follows OpenSSL
564   cipher list syntax. 594   cipher list syntax.
565   595  
566   @param ciphers The cipher suite specification string. 596   @param ciphers The cipher suite specification string.
567   597  
568   @return Success, or an error if the cipher string is invalid. 598   @return Success, or an error if the cipher string is invalid.
569   599  
570   @par Example 600   @par Example
571   @code 601   @code
572   // TLS 1.2 cipher suites (OpenSSL format) 602   // TLS 1.2 cipher suites (OpenSSL format)
573   ctx.set_ciphersuites( "ECDHE+AESGCM:ECDHE+CHACHA20" ); 603   ctx.set_ciphersuites( "ECDHE+AESGCM:ECDHE+CHACHA20" );
574   @endcode 604   @endcode
575   605  
576   @note For TLS 1.3, use `set_ciphersuites_tls13()` on backends 606   @note For TLS 1.3, use `set_ciphersuites_tls13()` on backends
577   that distinguish between TLS 1.2 and 1.3 cipher configuration. 607   that distinguish between TLS 1.2 and 1.3 cipher configuration.
  608 +
  609 + @note Applied by the OpenSSL backend only in this release; the
  610 + WolfSSL backend accepts the string but silently ignores it.
578   */ 611   */
579   std::error_code set_ciphersuites(std::string_view ciphers); 612   std::error_code set_ciphersuites(std::string_view ciphers);
580   613  
581   /** Set the ALPN protocol list. 614   /** Set the ALPN protocol list.
582   615  
583   Configures Application-Layer Protocol Negotiation (ALPN) for 616   Configures Application-Layer Protocol Negotiation (ALPN) for
584   the connection. ALPN is used to negotiate which application 617   the connection. ALPN is used to negotiate which application
585   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,
586   "http/1.1" for HTTP/1.1). 619   "http/1.1" for HTTP/1.1).
587   620  
588   The protocols are tried in preference order (first = highest). 621   The protocols are tried in preference order (first = highest).
589   622  
590   @param protocols Ordered list of protocol identifiers. 623   @param protocols Ordered list of protocol identifiers.
591   624  
592   @return Success, or an error if ALPN configuration fails. 625   @return Success, or an error if ALPN configuration fails.
593   626  
  627 + @note Not yet applied by the backends in this release; the
  628 + protocol list is accepted but ALPN is never negotiated.
  629 +
594   @par Example 630   @par Example
595   @code 631   @code
596   // Prefer HTTP/2, fall back to HTTP/1.1 632   // Prefer HTTP/2, fall back to HTTP/1.1
597   ctx.set_alpn( { "h2", "http/1.1" } ); 633   ctx.set_alpn( { "h2", "http/1.1" } );
598   @endcode 634   @endcode
599   */ 635   */
600   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);
601   637  
602   // 638   //
603   // Certificate Verification 639   // Certificate Verification
604   // 640   //
605   641  
606   /** Set the peer certificate verification mode. 642   /** Set the peer certificate verification mode.
607   643  
608   Controls whether and how peer certificates are verified during 644   Controls whether and how peer certificates are verified during
609   the TLS handshake. 645   the TLS handshake.
610   646  
611   @param mode The verification mode to use. 647   @param mode The verification mode to use.
612   648  
613   @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.
614   650  
615   @par Example 651   @par Example
616   @code 652   @code
617   // Verify peer certificate (typical for clients) 653   // Verify peer certificate (typical for clients)
618   ctx.set_verify_mode( tls_verify_mode::peer ); 654   ctx.set_verify_mode( tls_verify_mode::peer );
619   655  
620   // Require client certificate (server-side mTLS) 656   // Require client certificate (server-side mTLS)
621   ctx.set_verify_mode( tls_verify_mode::require_peer ); 657   ctx.set_verify_mode( tls_verify_mode::require_peer );
622   @endcode 658   @endcode
623   659  
624   @see tls_verify_mode 660   @see tls_verify_mode
625   */ 661   */
626   std::error_code set_verify_mode(tls_verify_mode mode); 662   std::error_code set_verify_mode(tls_verify_mode mode);
627   663  
628   /** Set the maximum certificate chain verification depth. 664   /** Set the maximum certificate chain verification depth.
629   665  
630   Limits how many intermediate certificates can appear between 666   Limits how many intermediate certificates can appear between
631   the peer certificate and a trusted root. The default is 667   the peer certificate and a trusted root. The default is
632   typically 100, which is sufficient for most certificate chains. 668   typically 100, which is sufficient for most certificate chains.
633   669  
634   @param depth Maximum number of intermediate certificates allowed. 670   @param depth Maximum number of intermediate certificates allowed.
635   671  
636   @return Success, or an error if the depth is invalid. 672   @return Success, or an error if the depth is invalid.
637   */ 673   */
638   std::error_code set_verify_depth(int depth); 674   std::error_code set_verify_depth(int depth);
639   675  
640   /** Set a custom certificate verification callback. 676   /** Set a custom certificate verification callback.
641   677  
642   Installs a callback that is invoked during certificate chain 678   Installs a callback that is invoked during certificate chain
643   verification. The callback can perform additional validation 679   verification. The callback can perform additional validation
644   beyond the standard checks and can override verification 680   beyond the standard checks and can override verification
645   results. 681   results.
646   682  
647   The callback receives the verification result so far and 683   The callback receives the verification result so far and
648   information about the certificate being verified. Return 684   information about the certificate being verified. Return
649   `true` to accept the certificate, `false` to reject. 685   `true` to accept the certificate, `false` to reject.
650   686  
651   @tparam Callback A callable with signature 687   @tparam Callback A callable with signature
652   `bool( bool preverified, verify_context& ctx )`. 688   `bool( bool preverified, verify_context& ctx )`.
653   689  
654   @param callback The verification callback. 690   @param callback The verification callback.
655   691  
656   @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.
657   693  
  694 + @note Not yet implemented in this release. This template is
  695 + declared but not defined; code that instantiates it fails to
  696 + link. Use `set_verify_mode()` with explicitly supplied trust
  697 + anchors instead.
  698 +
658   @note The `verify_context` type provides access to the 699   @note The `verify_context` type provides access to the
659   certificate and chain information. Its exact interface 700   certificate and chain information. Its exact interface
660   depends on the TLS backend. 701   depends on the TLS backend.
661   */ 702   */
662   template<typename Callback> 703   template<typename Callback>
663   std::error_code set_verify_callback(Callback callback); 704   std::error_code set_verify_callback(Callback callback);
664   705  
665   /** Set the expected server hostname for verification. 706   /** Set the expected server hostname for verification.
666   707  
667   For client connections, sets the hostname that the server 708   For client connections, sets the hostname that the server
668   certificate must match. This enables: 709   certificate must match. This enables:
669   710  
670   1. SNI (Server Name Indication) — tells the server which 711   1. SNI (Server Name Indication) — tells the server which
671   certificate to present (for virtual hosting) 712   certificate to present (for virtual hosting)
672   2. Hostname verification — validates the certificate's 713   2. Hostname verification — validates the certificate's
673   Subject Alternative Name or Common Name matches 714   Subject Alternative Name or Common Name matches
674   715  
675   @param hostname The expected server hostname. 716   @param hostname The expected server hostname.
676   717  
677   @par Example 718   @par Example
678   @code 719   @code
679   ctx.set_hostname( "api.example.com" ); 720   ctx.set_hostname( "api.example.com" );
680   @endcode 721   @endcode
681   722  
682   @note This is typically required for HTTPS clients to ensure 723   @note This is typically required for HTTPS clients to ensure
683   they're connecting to the intended server. 724   they're connecting to the intended server.
684   */ 725   */
685   void set_hostname(std::string_view hostname); 726   void set_hostname(std::string_view hostname);
686   727  
687   /** Set a callback for Server Name Indication (SNI). 728   /** Set a callback for Server Name Indication (SNI).
688   729  
689   For server connections, this callback is invoked during the TLS 730   For server connections, this callback is invoked during the TLS
690   handshake when a client sends an SNI extension. The callback 731   handshake when a client sends an SNI extension. The callback
691   receives the requested hostname and can accept or reject the 732   receives the requested hostname and can accept or reject the
692   connection. 733   connection.
693   734  
694   @tparam Callback A callable with signature 735   @tparam Callback A callable with signature
695   `bool( std::string_view hostname )`. 736   `bool( std::string_view hostname )`.
696   737  
697   @param callback The SNI callback. Return `true` to accept the 738   @param callback The SNI callback. Return `true` to accept the
698   connection or `false` to reject it with an alert. 739   connection or `false` to reject it with an alert.
699   740  
700   @par Example 741   @par Example
701   @code 742   @code
702   // Accept connections for specific domains only 743   // Accept connections for specific domains only
703   ctx.set_servername_callback( 744   ctx.set_servername_callback(
704   []( std::string_view hostname ) -> bool 745   []( std::string_view hostname ) -> bool
705   { 746   {
706   return hostname == "api.example.com" || 747   return hostname == "api.example.com" ||
707   hostname == "www.example.com"; 748   hostname == "www.example.com";
708   }); 749   });
709   @endcode 750   @endcode
710   751  
711   @note For virtual hosting with different certificates per hostname, 752   @note For virtual hosting with different certificates per hostname,
712   create separate contexts and select the appropriate one before 753   create separate contexts and select the appropriate one before
713   creating the TLS stream. 754   creating the TLS stream.
714   755  
715   @see set_hostname 756   @see set_hostname
716   */ 757   */
717   template<typename Callback> 758   template<typename Callback>
718   void set_servername_callback(Callback callback); 759   void set_servername_callback(Callback callback);
719   760  
720   private: 761   private:
721   void set_servername_callback_impl( 762   void set_servername_callback_impl(
722   std::function<bool(std::string_view)> callback); 763   std::function<bool(std::string_view)> callback);
723   764  
724   void set_password_callback_impl( 765   void set_password_callback_impl(
725   std::function<std::string(std::size_t, tls_password_purpose)> callback); 766   std::function<std::string(std::size_t, tls_password_purpose)> callback);
726   767  
727   public: 768   public:
728   // 769   //
729   // Revocation Checking 770   // Revocation Checking
730   // 771   //
731   772  
732   /** Add a Certificate Revocation List from memory. 773   /** Add a Certificate Revocation List from memory.
733   774  
734   Adds a CRL to the verification store for checking whether 775   Adds a CRL to the verification store for checking whether
735   certificates have been revoked. CRLs are typically fetched 776   certificates have been revoked. CRLs are typically fetched
736   from the URLs in a certificate's CRL Distribution Points 777   from the URLs in a certificate's CRL Distribution Points
737   extension. 778   extension.
738   779  
739   @param crl The CRL data in DER or PEM format. 780   @param crl The CRL data in DER or PEM format.
740   781  
741   @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.
742   783  
  784 + @note Not yet applied by the backends in this release; the CRL is
  785 + accepted but never used during verification.
  786 +
743   @see add_crl_file 787   @see add_crl_file
744   @see set_revocation_policy 788   @see set_revocation_policy
745   */ 789   */
746   std::error_code add_crl(std::string_view crl); 790   std::error_code add_crl(std::string_view crl);
747   791  
748   /** Add a Certificate Revocation List from a file. 792   /** Add a Certificate Revocation List from a file.
749   793  
750   Adds a CRL to the verification store for checking whether 794   Adds a CRL to the verification store for checking whether
751   certificates have been revoked. 795   certificates have been revoked.
752   796  
753   @param filename Path to a CRL file (DER or PEM format). 797   @param filename Path to a CRL file (DER or PEM format).
754   798  
755   @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
756   or the CRL is invalid. 800   or the CRL is invalid.
757   801  
  802 + @note Not yet applied by the backends in this release; the CRL is
  803 + accepted but never used during verification.
  804 +
758   @par Example 805   @par Example
759   @code 806   @code
760   ctx.add_crl_file( "issuer.crl" ); 807   ctx.add_crl_file( "issuer.crl" );
761   @endcode 808   @endcode
762   809  
763   @see add_crl 810   @see add_crl
764   @see set_revocation_policy 811   @see set_revocation_policy
765   */ 812   */
766   std::error_code add_crl_file(std::string_view filename); 813   std::error_code add_crl_file(std::string_view filename);
767   814  
768   /** Set the OCSP staple response for server-side stapling. 815   /** Set the OCSP staple response for server-side stapling.
769   816  
770   For servers, provides a pre-fetched OCSP response to send 817   For servers, provides a pre-fetched OCSP response to send
771   to clients during the handshake. This proves the server's 818   to clients during the handshake. This proves the server's
772   certificate hasn't been revoked without requiring the client 819   certificate hasn't been revoked without requiring the client
773   to contact the OCSP responder. 820   to contact the OCSP responder.
774   821  
775   The OCSP response must be periodically refreshed (typically 822   The OCSP response must be periodically refreshed (typically
776   every few hours to days) before it expires. 823   every few hours to days) before it expires.
777   824  
778   @param response The DER-encoded OCSP response. 825   @param response The DER-encoded OCSP response.
779   826  
780   @return Success, or an error if the response is invalid. 827   @return Success, or an error if the response is invalid.
781   828  
  829 + @note Not yet applied by the backends in this release; the
  830 + response is accepted but never stapled into the handshake.
  831 +
782   @note This is a server-side operation. Clients use 832   @note This is a server-side operation. Clients use
783   `set_require_ocsp_staple()` to require stapled responses. 833   `set_require_ocsp_staple()` to require stapled responses.
784   */ 834   */
785   std::error_code set_ocsp_staple(std::string_view response); 835   std::error_code set_ocsp_staple(std::string_view response);
786   836  
787   /** Require OCSP stapling from the server. 837   /** Require OCSP stapling from the server.
788   838  
789   For clients, requires the server to provide a stapled OCSP 839   For clients, requires the server to provide a stapled OCSP
790   response proving its certificate hasn't been revoked. If 840   response proving its certificate hasn't been revoked. If
791   the server doesn't provide a stapled response, the handshake 841   the server doesn't provide a stapled response, the handshake
792   fails. 842   fails.
793   843  
794   @param require Whether to require OCSP stapling. 844   @param require Whether to require OCSP stapling.
795   845  
  846 + @note Not yet applied by the backends in this release; the flag
  847 + is accepted but has no effect. Setting it to `true` does not
  848 + make the handshake fail when no staple is present.
  849 +
796   @note Not all servers support OCSP stapling. Enable this only 850   @note Not all servers support OCSP stapling. Enable this only
797   when connecting to servers known to support it. 851   when connecting to servers known to support it.
798   */ 852   */
799   void set_require_ocsp_staple(bool require); 853   void set_require_ocsp_staple(bool require);
800   854  
801   /** Set the certificate revocation checking policy. 855   /** Set the certificate revocation checking policy.
802   856  
803   Controls how certificate revocation status is checked during 857   Controls how certificate revocation status is checked during
804   verification. This affects both CRL and OCSP checking. 858   verification. This affects both CRL and OCSP checking.
805   859  
806   @param policy The revocation checking policy. 860   @param policy The revocation checking policy.
807   861  
808   @par Example 862   @par Example
809   @code 863   @code
810   // Require successful revocation check 864   // Require successful revocation check
811   ctx.set_revocation_policy( tls_revocation_policy::hard_fail ); 865   ctx.set_revocation_policy( tls_revocation_policy::hard_fail );
812   866  
813   // Check but allow unknown status 867   // Check but allow unknown status
814   ctx.set_revocation_policy( tls_revocation_policy::soft_fail ); 868   ctx.set_revocation_policy( tls_revocation_policy::soft_fail );
815   @endcode 869   @endcode
  870 +
  871 + @note Not yet applied by the backends in this release; the policy
  872 + is accepted but has no effect. `soft_fail` and `hard_fail` do
  873 + not change verification behavior.
816   874  
817   @see tls_revocation_policy 875   @see tls_revocation_policy
818   @see add_crl 876   @see add_crl
819   */ 877   */
820   void set_revocation_policy(tls_revocation_policy policy); 878   void set_revocation_policy(tls_revocation_policy policy);
821   879  
822   // 880   //
823   // Password Handling 881   // Password Handling
824   // 882   //
825   883  
826   /** Set the password callback for encrypted keys. 884   /** Set the password callback for encrypted keys.
827   885  
828   Installs a callback that provides passwords for encrypted 886   Installs a callback that provides passwords for encrypted
829   private keys and PKCS#12 files. The callback is invoked when 887   private keys and PKCS#12 files. The callback is invoked when
830   loading encrypted key material. 888   loading encrypted key material.
831   889  
832   @tparam Callback A callable with signature 890   @tparam Callback A callable with signature
833   `std::string( std::size_t max_length, password_purpose purpose )`. 891   `std::string( std::size_t max_length, password_purpose purpose )`.
834   892  
835   @param callback The password callback. It receives the maximum 893   @param callback The password callback. It receives the maximum
836   password length and the purpose (reading or writing), and 894   password length and the purpose (reading or writing), and
837   returns the password string. 895   returns the password string.
838   896  
839   @par Example 897   @par Example
840   @code 898   @code
841   ctx.set_password_callback( 899   ctx.set_password_callback(
842   []( std::size_t max_len, tls_password_purpose purpose ) 900   []( std::size_t max_len, tls_password_purpose purpose )
843   { 901   {
844   // In practice, prompt user or read from secure storage 902   // In practice, prompt user or read from secure storage
845   return std::string( "my-key-password" ); 903   return std::string( "my-key-password" );
846   }); 904   });
847   905  
848   // Now load encrypted key 906   // Now load encrypted key
849   ctx.use_private_key_file( "encrypted.key", tls_file_format::pem ); 907   ctx.use_private_key_file( "encrypted.key", tls_file_format::pem );
850   @endcode 908   @endcode
851   909  
852   @see tls_password_purpose 910   @see tls_password_purpose
853   */ 911   */
854   template<typename Callback> 912   template<typename Callback>
855   void set_password_callback(Callback callback); 913   void set_password_callback(Callback callback);
856   }; 914   };
857   #ifdef _MSC_VER 915   #ifdef _MSC_VER
858   #pragma warning(pop) 916   #pragma warning(pop)
859   #endif 917   #endif
860   918  
861   template<typename Callback> 919   template<typename Callback>
862   void 920   void
HITCBC 863   1 tls_context::set_servername_callback(Callback callback) 921   1 tls_context::set_servername_callback(Callback callback)
864   { 922   {
HITCBC 865   1 set_servername_callback_impl(std::move(callback)); 923   1 set_servername_callback_impl(std::move(callback));
HITCBC 866   1 } 924   1 }
867   925  
868   template<typename Callback> 926   template<typename Callback>
869   void 927   void
HITCBC 870   1 tls_context::set_password_callback(Callback callback) 928   1 tls_context::set_password_callback(Callback callback)
871   { 929   {
HITCBC 872   1 set_password_callback_impl(std::move(callback)); 930   1 set_password_callback_impl(std::move(callback));
HITCBC 873   1 } 931   1 }
874   932  
875   } // namespace boost::corosio 933   } // namespace boost::corosio
876   934  
877   #endif 935   #endif