How to properly use TLS related API

[ksanderon]

Introduction

Hello, I'm trying to add in rili project wrapper for tls/ssl layer over my network service implementation(it's just tcp/ip). Unfortunately I have some questions regarding how to use botan-2 properly, which are not answered explicite(or I oversight it) by documentation/manual, github issues nor code which I found in implementation of botan cli application :/

Of course these questions probably could be answered "somehow" by google, however I don't like "stackoverflow copy paste programming style" and hope it's better to ask than live with bad informations ;)

Real questions

• All "callbacks" provided in Botan::TLS::Callbacks are called as direct reaction for API that user calls on Botan::TLS::Client/Server? This question is regarding thread safety. If I undestand correctly botan do not spawn it own threads under the hood or defer calling user provided callbacks somehow other way - so can I assume that in this meaning botan code is synchronous? And because of that it's ok if I will only create critical sections where Botan::TLS::Client/Server API methods are called(+ in objects shared between Botan::TLS::Client/Server instances passed in ctors)? Edit: Maybe this is target dependent (os, compiler, build configuration)? Edit: Botan spawn threads at least for certs revocation during chain validation by OCSP over HTTP

• What should be done, when underlying transport connection can't send or receive more data (for example in case of peer connection lost), if I would like to cleanly teardown TLS/SSL resources aquired by botan? Use Botan::TLS::Client/Server::close()? Maybe use Botan::TLS::Client/Server::send_alert with proper for this purpose parameter(other than used by Botan::TLS::Client/Server::close())(but this don't have sense forme as botan will ask me to send to peer more data :/ )? Maybe just delete Botan::TLS::Client/Server instance?

• ~When, I can be sure that I can call Botan::TLS::Client/Server::send without exception (Botan::TLS::Client/Server::is_active() == true)? I need to check it every time when Botan::TLS::Callbacks::tls_session_established occure?~ _(note: I just found that for this purpose is tls_session_activated, but it is not mentioned in manual nor handbook)_

• If something will go wrong and Botan::TLS::Client/Server it will never be "activated", then I will be informed about this fact by Botan::TLS::Callbacks::tls_alert(this seems to be opposite to last question)? _Edit: Not only - some api functions can throw exceptions for example Botan::TLS::Client/Server::received_data can throw a lot of different exception types_

• How to detect when once "activated" Botan::TLS::Client/Server will be inactivated(so after that I should not use Botan::TLS::Client/Server::send)? Can I detect this situation just by checking in Botan::TLS::Callbacks::tls_alert if alert is fatal/warning? Edit: when exception is thrown from botan api, then can also be assumed connection is lost, and is at least implicite inactivated

• If I will call explicite Botan::TLS::Client/Server::close when I may assume that botan will not ask to send more data to peer, so when underlying connection can be cleanly closed?

• In user manual regarding Botan::TLS::Callbacks::tls_alert is mentioned: "Note that alerts received before the handshake is complete are not authenticated and could have been inserted by a MITM attacker." ~So how to detect that handshake is completed? I should be able to detect it in Botan::TLS::Callbacks::tls_session_established? It's true, that when is/was Botan::TLS::Client/Server::is_active() == true, then handshake was completed?~(note: tls_session_activated) What should be done if mentioned in manual scenario will occur? These alerts should be just discarded or there should be introduced some kind of special actions?(maybe link to papers which describe attack will be useful in manual?)

[randombit]

Sorry I had missed seeing this, totally legit questions here I think. Which I will work on providing good answers to when time permits and perhaps even update the docs accordingly. For now -

If I will call explicite Botan::TLS::Client/Server::close when I may assume that botan will not ask to send more data to peer, so when underlying connection can be cleanly closed?

When close is called, you may get one final callback to send the (possibly encrypted) alert message to the peer. That callback will occur before close returns.

What should be done if mentioned in manual scenario will occur? These alerts should be just discarded or there should be introduced some kind of special actions?

They cannot just be discarded because all implementations can and will send alerts before authentication to indicate some problem that prevents the handshake from succeeding. It is not possible (without out of band data) to know if a handshake_failure alert means a MITM attacker is selectively blocking your TLS handshakes from succeeding, or if there is simply some misconfiguration or other problem. But how to respond to this is going to be very application specific.