Botan 3.7.1
Crypto and TLS for C&
tls_client.h
Go to the documentation of this file.
1/*
2* TLS Client
3* (C) 2004-2011 Jack Lloyd
4* 2016 Matthias Gierlings
5* 2021 Elektrobit Automotive GmbH
6* 2022 René Meusel, Hannes Rantzsch - neXenio GmbH
7*
8* Botan is released under the Simplified BSD License (see license.txt)
9*/
10
11#ifndef BOTAN_TLS_CLIENT_H_
12#define BOTAN_TLS_CLIENT_H_
13
14#include <botan/credentials_manager.h>
15#include <botan/tls_channel.h>
16#include <botan/tls_policy.h>
17#include <memory>
18#include <vector>
19
20namespace Botan::TLS {
21
22class Channel_Impl;
23class Handshake_IO;
24
25/**
26* SSL/TLS Client
27*/
28class BOTAN_PUBLIC_API(2, 0) Client final : public Channel {
29 public:
30 /**
31 * Initialize a new TLS client. The constructor will immediately initiate a
32 * new session.
33 *
34 * The @p callbacks parameter specifies the various application callbacks
35 * which pertain to this particular client connection.
36 *
37 * The @p session_manager is an interface for storing TLS sessions, which
38 * allows for session resumption upon reconnecting to a server. In the
39 * absence of a need for persistent sessions, use
40 * TLS::Session_Manager_In_Memory which caches connections for the lifetime
41 * of a single process.
42 *
43 * The @p credentials_manager is an interface that will be called to
44 * retrieve any certificates, private keys, or pre-shared keys.
45 *
46 * Use the optional @p server_info to specify the DNS name of the server
47 * you are attempting to connect to, if you know it. This helps the server
48 * select what certificate to use and helps the client validate the
49 * connection.
50 *
51 * Use the optional @p offer_version to control the version of TLS you wish
52 * the client to offer. Normally, you'll want to offer the most recent
53 * version of (D)TLS that is available, however some broken servers are
54 * intolerant of certain versions being offered, and for classes of
55 * applications that have to deal with such servers (typically web
56 * browsers) it may be necessary to implement a version backdown strategy
57 * if the initial attempt fails.
58 *
59 * @warning Implementing such a backdown strategy allows an attacker to
60 * downgrade your connection to the weakest protocol that both you
61 * and the server support.
62 *
63 * Setting @p offer_version is also used to offer DTLS instead of TLS; use
64 * TLS::Protocol_Version::latest_dtls_version().
65 *
66 * Optionally, the client will advertise @p next_protocols to the server
67 * using the ALPN extension.
68 *
69 * The optional @p reserved_io_buffer_size specifies how many bytes to
70 * pre-allocate in the I/O buffers. Use this if you want to control how
71 * much memory the channel uses initially (the buffers will be resized as
72 * needed to process inputs). Otherwise some reasonable default is used.
73 * The TLS 1.3 implementation ignores this.
74 */
75 Client(const std::shared_ptr<Callbacks>& callbacks,
76 const std::shared_ptr<Session_Manager>& session_manager,
77 const std::shared_ptr<Credentials_Manager>& creds,
78 const std::shared_ptr<const Policy>& policy,
79 const std::shared_ptr<RandomNumberGenerator>& rng,
82 const std::vector<std::string>& next_protocols = {},
83 size_t reserved_io_buffer_size = TLS::Client::IO_BUF_DEFAULT_SIZE);
84
85 ~Client() override;
86
87 /**
88 * @return network protocol as advertised by the TLS server, if server sent the ALPN extension
89 */
90 std::string application_protocol() const override;
91
92 size_t from_peer(std::span<const uint8_t> data) override;
93
94 bool is_handshake_complete() const override;
95
96 bool is_active() const override;
97
98 bool is_closed() const override;
99
100 bool is_closed_for_reading() const override;
101 bool is_closed_for_writing() const override;
102
103 std::vector<X509_Certificate> peer_cert_chain() const override;
104 std::shared_ptr<const Public_Key> peer_raw_public_key() const override;
105 std::optional<std::string> external_psk_identity() const override;
106
107 SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override;
108
109 void renegotiate(bool force_full_renegotiation = false) override;
110
111 void update_traffic_keys(bool request_peer_update = false) override;
112
113 bool secure_renegotiation_supported() const override;
114
115 void to_peer(std::span<const uint8_t> data) override;
116
117 void send_alert(const Alert& alert) override;
118
119 void send_warning_alert(Alert::Type type) override;
120
121 void send_fatal_alert(Alert::Type type) override;
122
123 void close() override;
124
125 bool timeout_check() override;
126
127 private:
128 size_t downgrade();
129
130 private:
131 std::unique_ptr<Channel_Impl> m_impl;
132};
133} // namespace Botan::TLS
134
135#endif
#define BOTAN_PUBLIC_API(maj, min)
Definition api.h:19
AlertType Type
Definition tls_alert.h:71
static constexpr size_t IO_BUF_DEFAULT_SIZE
Definition tls_channel.h:32
bool is_closed_for_reading() const override
bool is_handshake_complete() const override
void renegotiate(bool force_full_renegotiation=false) override
void close() override
std::string application_protocol() const override
std::shared_ptr< const Public_Key > peer_raw_public_key() const override
Client(const std::shared_ptr< Callbacks > &callbacks, const std::shared_ptr< Session_Manager > &session_manager, const std::shared_ptr< Credentials_Manager > &creds, const std::shared_ptr< const Policy > &policy, const std::shared_ptr< RandomNumberGenerator > &rng, Server_Information server_info=Server_Information(), Protocol_Version offer_version=Protocol_Version::latest_tls_version(), const std::vector< std::string > &next_protocols={}, size_t reserved_io_buffer_size=TLS::Client::IO_BUF_DEFAULT_SIZE)
bool secure_renegotiation_supported() const override
bool is_active() const override
SymmetricKey key_material_export(std::string_view label, std::string_view context, size_t length) const override
bool is_closed_for_writing() const override
void send_fatal_alert(Alert::Type type) override
bool timeout_check() override
void send_warning_alert(Alert::Type type) override
void to_peer(std::span< const uint8_t > data) override
~Client() override
std::vector< X509_Certificate > peer_cert_chain() const override
bool is_closed() const override
void update_traffic_keys(bool request_peer_update=false) override
std::optional< std::string > external_psk_identity() const override
void send_alert(const Alert &alert) override
size_t from_peer(std::span< const uint8_t > data) override
static Protocol_Version latest_tls_version()
Definition tls_version.h:44
OctetString SymmetricKey
Definition symkey.h:140