Botan  1.11.15
src/lib/tls/tls_channel.h
Go to the documentation of this file.
00001 /*
00002 * TLS Channel
00003 * (C) 2011,2012,2014,2015 Jack Lloyd
00004 *
00005 * Botan is released under the Simplified BSD License (see license.txt)
00006 */
00007 
00008 #ifndef BOTAN_TLS_CHANNEL_H__
00009 #define BOTAN_TLS_CHANNEL_H__
00010 
00011 #include <botan/tls_policy.h>
00012 #include <botan/tls_session.h>
00013 #include <botan/tls_alert.h>
00014 #include <botan/tls_session_manager.h>
00015 #include <botan/x509cert.h>
00016 #include <vector>
00017 #include <string>
00018 #include <map>
00019 
00020 namespace Botan {
00021 
00022 namespace TLS {
00023 
00024 class Connection_Cipher_State;
00025 class Connection_Sequence_Numbers;
00026 class Handshake_State;
00027 
00028 /**
00029 * Generic interface for TLS endpoint
00030 */
00031 class BOTAN_DLL Channel
00032    {
00033    public:
00034       typedef std::function<void (const byte[], size_t)> output_fn;
00035       typedef std::function<void (const byte[], size_t)> data_cb;
00036       typedef std::function<void (Alert, const byte[], size_t)> alert_cb;
00037       typedef std::function<bool (const Session&)> handshake_cb;
00038 
00039       Channel(output_fn out,
00040               data_cb app_data_cb,
00041               alert_cb alert_cb,
00042               handshake_cb hs_cb,
00043               Session_Manager& session_manager,
00044               RandomNumberGenerator& rng,
00045               bool is_datagram,
00046               size_t reserved_io_buffer_size);
00047 
00048       Channel(const Channel&) = delete;
00049 
00050       Channel& operator=(const Channel&) = delete;
00051 
00052       virtual ~Channel();
00053 
00054       /**
00055       * Inject TLS traffic received from counterparty
00056       * @return a hint as the how many more bytes we need to process the
00057       *         current record (this may be 0 if on a record boundary)
00058       */
00059       size_t received_data(const byte buf[], size_t buf_size);
00060 
00061       /**
00062       * Inject TLS traffic received from counterparty
00063       * @return a hint as the how many more bytes we need to process the
00064       *         current record (this may be 0 if on a record boundary)
00065       */
00066       size_t received_data(const std::vector<byte>& buf);
00067 
00068       /**
00069       * Inject plaintext intended for counterparty
00070       * Throws an exception if is_active() is false
00071       */
00072       void send(const byte buf[], size_t buf_size);
00073 
00074       /**
00075       * Inject plaintext intended for counterparty
00076       * Throws an exception if is_active() is false
00077       */
00078       void send(const std::string& val);
00079 
00080       /**
00081       * Inject plaintext intended for counterparty
00082       * Throws an exception if is_active() is false
00083       */
00084       template<typename Alloc>
00085          void send(const std::vector<unsigned char, Alloc>& val)
00086          {
00087          send(&val[0], val.size());
00088          }
00089 
00090       /**
00091       * Send a TLS alert message. If the alert is fatal, the internal
00092       * state (keys, etc) will be reset.
00093       * @param alert the Alert to send
00094       */
00095       void send_alert(const Alert& alert);
00096 
00097       /**
00098       * Send a warning alert
00099       */
00100       void send_warning_alert(Alert::Type type) { send_alert(Alert(type, false)); }
00101 
00102       /**
00103       * Send a fatal alert
00104       */
00105       void send_fatal_alert(Alert::Type type) { send_alert(Alert(type, true)); }
00106 
00107       /**
00108       * Send a close notification alert
00109       */
00110       void close() { send_warning_alert(Alert::CLOSE_NOTIFY); }
00111 
00112       /**
00113       * @return true iff the connection is active for sending application data
00114       */
00115       bool is_active() const;
00116 
00117       /**
00118       * @return true iff the connection has been definitely closed
00119       */
00120       bool is_closed() const;
00121 
00122 
00123       /**
00124       * @return certificate chain of the peer (may be empty)
00125       */
00126       std::vector<X509_Certificate> peer_cert_chain() const;
00127 
00128       /**
00129       * Key material export (RFC 5705)
00130       * @param label a disambiguating label string
00131       * @param context a per-association context value
00132       * @param length the length of the desired key in bytes
00133       * @return key of length bytes
00134       */
00135       SymmetricKey key_material_export(const std::string& label,
00136                                        const std::string& context,
00137                                        size_t length) const;
00138 
00139       /**
00140       * Attempt to renegotiate the session
00141       * @param force_full_renegotiation if true, require a full renegotiation,
00142       * otherwise allow session resumption
00143       */
00144       void renegotiate(bool force_full_renegotiation = false);
00145 
00146       /**
00147       * @return true iff the counterparty supports the secure
00148       * renegotiation extensions.
00149       */
00150       bool secure_renegotiation_supported() const;
00151 
00152       /**
00153       * Perform a handshake timeout check. This does nothing unless
00154       * this is a DTLS channel with a pending handshake state, in
00155       * which case we check for timeout and potentially retransmit
00156       * handshake packets.
00157       */
00158       bool timeout_check();
00159 
00160       /**
00161       * @return true iff the peer supports heartbeat messages
00162       */
00163       bool peer_supports_heartbeats() const;
00164 
00165       /**
00166       * @return true iff we are allowed to send heartbeat messages
00167       */
00168       bool heartbeat_sending_allowed() const;
00169 
00170       /**
00171       * Attempt to send a heartbeat message (if negotiated with counterparty)
00172       * @param payload will be echoed back
00173       * @param payload_size size of payload in bytes
00174       * @param pad_bytes include 16 + pad_bytes extra bytes in the message (not echoed)
00175       */
00176       void heartbeat(const byte payload[], size_t payload_size, size_t pad_bytes = 0);
00177 
00178       /**
00179       * Attempt to send a heartbeat message (if negotiated with counterparty)
00180       */
00181       void heartbeat() { heartbeat(nullptr, 0); }
00182    protected:
00183 
00184       virtual void process_handshake_msg(const Handshake_State* active_state,
00185                                          Handshake_State& pending_state,
00186                                          Handshake_Type type,
00187                                          const std::vector<byte>& contents) = 0;
00188 
00189       virtual void initiate_handshake(Handshake_State& state,
00190                                       bool force_full_renegotiation) = 0;
00191 
00192       virtual std::vector<X509_Certificate>
00193          get_peer_cert_chain(const Handshake_State& state) const = 0;
00194 
00195       virtual Handshake_State* new_handshake_state(class Handshake_IO* io) = 0;
00196 
00197       Handshake_State& create_handshake_state(Protocol_Version version);
00198 
00199       void activate_session();
00200 
00201       void change_cipher_spec_reader(Connection_Side side);
00202 
00203       void change_cipher_spec_writer(Connection_Side side);
00204 
00205       /* secure renegotiation handling */
00206 
00207       void secure_renegotiation_check(const class Client_Hello* client_hello);
00208       void secure_renegotiation_check(const class Server_Hello* server_hello);
00209 
00210       std::vector<byte> secure_renegotiation_data_for_client_hello() const;
00211       std::vector<byte> secure_renegotiation_data_for_server_hello() const;
00212 
00213       RandomNumberGenerator& rng() { return m_rng; }
00214 
00215       Session_Manager& session_manager() { return m_session_manager; }
00216 
00217       bool save_session(const Session& session) const { return m_handshake_cb(session); }
00218 
00219    private:
00220       size_t maximum_fragment_size() const;
00221 
00222       void send_record(byte record_type, const std::vector<byte>& record);
00223 
00224       void send_record_under_epoch(u16bit epoch, byte record_type,
00225                                    const std::vector<byte>& record);
00226 
00227       void send_record_array(u16bit epoch, byte record_type,
00228                              const byte input[], size_t length);
00229 
00230       void write_record(Connection_Cipher_State* cipher_state,
00231                         u16bit epoch, byte type, const byte input[], size_t length);
00232 
00233       Connection_Sequence_Numbers& sequence_numbers() const;
00234 
00235       std::shared_ptr<Connection_Cipher_State> read_cipher_state_epoch(u16bit epoch) const;
00236 
00237       std::shared_ptr<Connection_Cipher_State> write_cipher_state_epoch(u16bit epoch) const;
00238 
00239       void reset_state();
00240 
00241       const Handshake_State* active_state() const { return m_active_state.get(); }
00242 
00243       const Handshake_State* pending_state() const { return m_pending_state.get(); }
00244 
00245       bool m_is_datagram;
00246 
00247       /* callbacks */
00248       handshake_cb m_handshake_cb;
00249       data_cb m_data_cb;
00250       alert_cb m_alert_cb;
00251       output_fn m_output_fn;
00252 
00253       /* external state */
00254       RandomNumberGenerator& m_rng;
00255       Session_Manager& m_session_manager;
00256 
00257       /* sequence number state */
00258       std::unique_ptr<Connection_Sequence_Numbers> m_sequence_numbers;
00259 
00260       /* pending and active connection states */
00261       std::unique_ptr<Handshake_State> m_active_state;
00262       std::unique_ptr<Handshake_State> m_pending_state;
00263 
00264       /* cipher states for each epoch */
00265       std::map<u16bit, std::shared_ptr<Connection_Cipher_State>> m_write_cipher_states;
00266       std::map<u16bit, std::shared_ptr<Connection_Cipher_State>> m_read_cipher_states;
00267 
00268       /* I/O buffers */
00269       secure_vector<byte> m_writebuf;
00270       secure_vector<byte> m_readbuf;
00271    };
00272 
00273 }
00274 
00275 }
00276 
00277 #endif