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