libfilezilla
Public Member Functions | Static Public Member Functions | Friends | List of all members
tls_layer Class Referencefinal

A Transport Layer Security (TLS) layer. More...

#include <tls_layer.hpp>

Inheritance diagram for tls_layer:
Inheritance graph
[legend]
Collaboration diagram for tls_layer:
Collaboration graph
[legend]

Public Member Functions

 tls_layer (event_loop &event_loop, event_handler *evt_handler, socket_interface &layer, tls_system_trust_store *system_trust_store, logger_interface &logger)
 
bool client_handshake (std::vector< uint8_t > const &required_certificate, std::vector< uint8_t > const &session_to_resume=std::vector< uint8_t >(), native_string const &session_hostname=native_string())
 Starts shaking hands for a new TLS session as client. More...
 
bool client_handshake (event_handler *const verification_handler, std::vector< uint8_t > const &session_to_resume=std::vector< uint8_t >(), native_string const &session_hostname=native_string())
 Starts shaking hands for a new TLS session as client. More...
 
bool server_handshake ()
 Starts shaking hand for a new TLS session as server. More...
 
bool server_handshake (std::vector< uint8_t > const &session_to_resume)
 Starts shaking hand for a new TLS session as server. More...
 
std::vector< uint8_t > get_session_parameters () const
 Gets session parameters for resumption.
 
std::vector< uint8_t > get_raw_certificate () const
 Gets the session's peer certificate in DER.
 
void set_verification_result (bool trusted)
 Must be called after having received certificate_verification_event.
 
std::string get_protocol () const
 
std::string get_key_exchange () const
 
std::string get_cipher () const
 
std::string get_mac () const
 
int get_algorithm_warnings () const
 
bool resumed_session () const
 After a successful handshake, returns whether the session has been resumed.
 
bool set_certificate_file (native_string const &keyfile, native_string const &certsfile, native_string const &password, bool pem=true)
 Sets the file containing the certificate (and its chain) and the file with the corresponding private key. More...
 
bool set_certificate (std::string const &key, std::string const &certs, native_string const &password, bool pem=true)
 Sets the certificate (and its chain) and the private key. More...
 
virtual socket_state get_state () const override
 
virtual int connect (native_string const &host, unsigned int port, address_type family=address_type::unknown) override
 
virtual int read (void *buffer, unsigned int size, int &error) override
 
virtual int write (void const *buffer, unsigned int size, int &error) override
 
virtual int shutdown () override
 Signals peers that we want to close the connections. More...
 
virtual int shutdown_read () override
 Check that all layers further down also have reached EOF. More...
 
- Public Member Functions inherited from socket_layer
 socket_layer (event_handler *handler, socket_interface &next_layer, bool event_passthrough)
 
 socket_layer (socket_layer const &)=delete
 
socket_layeroperator= (socket_layer const &)=delete
 
virtual void set_event_handler (event_handler *handler) override
 The handler for any events generated (or forwarded) by this layer.
 
virtual native_string peer_host () const override
 
virtual int peer_port (int &error) const override
 
socket_interfacenext ()
 The next layer further down. Usually another layer or the actual socket.
 
- Public Member Functions inherited from socket_interface
 socket_interface (socket_interface const &)=delete
 
socket_interfaceoperator= (socket_interface const &)=delete
 
- Public Member Functions inherited from socket_event_source
socket_event_sourceroot () const
 Gets the root source. More...
 

Static Public Member Functions

static std::string list_tls_ciphers (std::string const &priority)
 Returns a human-readable list of all TLS ciphers available with the passed priority string.
 
static std::string get_gnutls_version ()
 
static std::pair< std::string, std::string > generate_selfsigned_certificate (native_string const &password, std::string const &distinguished_name, std::vector< std::string > const &hostnames)
 Creates a new private key and a self-signed certificate. More...
 

Friends

class tls_layer_impl
 

Additional Inherited Members

- Protected Member Functions inherited from event_handler
 event_handler (event_loop &loop)
 
 event_handler (event_handler const &)=delete
 
event_handleroperator= (event_handler const &)=delete
 
void remove_handler ()
 Deactivates handler, removes all pending events and stops all timers for this handler. More...
 
template<typename T , typename... Args>
void send_event (Args &&... args)
 Sends the passed event asynchronously to the handler. More...
 
template<typename T >
void send_event (T *evt)
 
timer_id add_timer (duration const &interval, bool one_shot)
 Adds a timer, returns the timer id. More...
 
void stop_timer (timer_id id)
 
- Protected Member Functions inherited from socket_layer
void forward_socket_event (socket_event_source *source, socket_event_flag t, int error)
 
void forward_hostaddress_event (socket_event_source *source, std::string const &address)
 
void set_event_passthrough ()
 
 socket_layer (event_handler *handler, socket_interface &next_layer, bool event_passthrough)
 
 socket_layer (socket_layer const &)=delete
 
socket_layeroperator= (socket_layer const &)=delete
 
virtual void set_event_handler (event_handler *handler) override
 The handler for any events generated (or forwarded) by this layer.
 
virtual native_string peer_host () const override
 
virtual int peer_port (int &error) const override
 
socket_interfacenext ()
 The next layer further down. Usually another layer or the actual socket.
 
- Protected Member Functions inherited from socket_interface
 socket_interface (socket_event_source *root)
 
 socket_interface (socket_interface const &)=delete
 
socket_interfaceoperator= (socket_interface const &)=delete
 
- Protected Member Functions inherited from socket_event_source
 socket_event_source (socket_event_source *root)
 
socket_event_sourceroot () const
 Gets the root source. More...
 
- Protected Attributes inherited from event_handler
event_loopevent_loop_
 
- Protected Attributes inherited from socket_layer
event_handlerevent_handler_ {}
 
socket_interfacenext_layer_
 
bool event_passthrough_ {}
 
- Protected Attributes inherited from socket_event_source
socket_event_source *const root_ {}
 

Detailed Description

A Transport Layer Security (TLS) layer.

Can be used both for client- and server-side TLS.

This class also supports TLS session resumption. Resumption has to be requested explicitly, there is no shared state between unrelated sessions.

Member Function Documentation

◆ client_handshake() [1/2]

bool client_handshake ( std::vector< uint8_t > const &  required_certificate,
std::vector< uint8_t > const &  session_to_resume = std::vector< uint8_t >(),
native_string const &  session_hostname = native_string() 
)

Starts shaking hands for a new TLS session as client.

Returns true if the handshake has started, false on error.

If the handshake is started, wait for a connection event for the result.

The certificate negotiated that eventually gets negotiated for the session] must match the passed required_certificate, either in DER or PEM, or the handshake will fail.

◆ client_handshake() [2/2]

bool client_handshake ( event_handler *const  verification_handler,
std::vector< uint8_t > const &  session_to_resume = std::vector< uint8_t >(),
native_string const &  session_hostname = native_string() 
)

Starts shaking hands for a new TLS session as client.

Returns true if the handshake has started, false on error.

If the handshake is started, wait for a connection event for the result.

If a verification handler is passed, it will receive a certificate_verification_event event upon which it must call set_verification_result. If no verification handler is passed, verification is done soley using the system trust store.

◆ generate_selfsigned_certificate()

static std::pair<std::string, std::string> generate_selfsigned_certificate ( native_string const &  password,
std::string const &  distinguished_name,
std::vector< std::string > const &  hostnames 
)
static

Creates a new private key and a self-signed certificate.

The distinguished name must be a RFC4514-compliant string.

If the password is non-empty, the private key gets encrypted using it.

The output pair is in PEM, first element is the key and the second the certificate.

◆ server_handshake() [1/2]

bool server_handshake ( )

Starts shaking hand for a new TLS session as server.

Returns true if the handshake has started, false on error.

If the handshake is started, wait for a connection event for the result.

Before calling server_handshake, a valid certificate and key must be passed in through set_certificate.

◆ server_handshake() [2/2]

bool server_handshake ( std::vector< uint8_t > const &  session_to_resume)

Starts shaking hand for a new TLS session as server.

Returns true if the handshake has started, false on error.

If the handshake is started, wait for a connection event for the result.

Before calling server_handshake, a valid certificate and key must be passed in through set_certificate.

◆ set_certificate()

bool set_certificate ( std::string const &  key,
std::string const &  certs,
native_string const &  password,
bool  pem = true 
)

Sets the certificate (and its chain) and the private key.

For servers it is mandatory and is the certificate the server presents to the client.

For clients it is the optional client certificate.

If the pem flag is set, the input is assumed to be in PEM, otherwise DER.

◆ set_certificate_file()

bool set_certificate_file ( native_string const &  keyfile,
native_string const &  certsfile,
native_string const &  password,
bool  pem = true 
)

Sets the file containing the certificate (and its chain) and the file with the corresponding private key.

For servers a certificate is mandatory, it is presented to the client during the handshake.

For clients it is the optional client certificate.

If the pem flag is set, the input is assumed to be in PEM, otherwise DER.

◆ shutdown()

virtual int shutdown ( )
overridevirtual

Signals peers that we want to close the connections.

Only disallows further sends, does not affect reading from the socket.

Implements socket_interface.

◆ shutdown_read()

virtual int shutdown_read ( )
overridevirtual

Check that all layers further down also have reached EOF.

Can only be called after read has returned 0, calling it earlier is undefined. shutdown_read should be called after eof to ensure all layers have reached EOF.

Returns
0 on success
EAGAIN if the shutdown cannot be completed, wait for a read event and try again.
otherwise an error has occured.

On an ordinary socket, this is a no-op. Some layers however may return an EOF before the next lower layer has reached its own EOF, such as the EOF of the secure channel from fz::tls_layer.

Closing the layer stack without all layers having reached EOF can lead to truncation on the write side: With a lower layer's EOF waiting in TCP's receive buffer and data pending in the send buffer, closing the socket is not graceful, it discards all pending data. Through shutdown_read you can assure that no pending data is left to receive, on this or any lower layer, so that closing the socket is done graceful ensuring delivery of all data in the send buffer (assuming there are no network errors).

Reimplemented from socket_layer.


The documentation for this class was generated from the following file: