Add new(), connect(), accept() and handshake() to SslStream

[eaufavor]

These APIs allow more SslStream to be used more flexibly

[nox]

Just wondering, why do we need more flexibility around those functions? I would rather we reduce the number of ways to do the same thing in that crate, than increase it.

What edge does SslStream::new followed by SslStream::connect gives us over Ssl::connect?

[nox]

Btw, have you seen this other PR that touches the handshake API entrypoints? #142

[eaufavor]

My intention is to bring in the APIs openssl-rs provides. With these, it is easier for openssl-rs users to migrate to boring-rs (and vise versa).

Also I think this PR might might help simplify the async implementation too, as claimed by rust-openssl/rust-openssl#1397.

See more: tokio-rs/tokio-openssl@56f6618

[nox]

I really don't like how tokio-openssl lets you mix up poll_connect and poll_accept calls, which is something #142 completely prevents.

I think #142 is overall better than rust-openssl/rust-openssl#1397 but I'll let other people decide about that, as I can see value in API parity with the openssl stack, even if it is worse.

[eaufavor]

Thanks.
There are two things I care about this change

1. The ssl_set_fd (essentially unconnected SslStream) code patten (example https://wiki.openssl.org/index.php/Simple_TLS_Server) is the de facto way of using openssl/boringssl. It is fine that this crate provides a better interface but since the goal of this crate is "BoringSSL bindings for Rust", it should allow the said code pattern to be used.
2. I think the new unconnected SslStream is more ergonomic than its counterpart without this change

enum MySslStream<S> {
   PreConnect((Ssl, S))
   MidHandshake(MidHandshakeSslStream<S>)
   Connected<Ssltream<S>>
}

[nox]

I think the new unconnected SslStream is more ergonomic than its counterpart without this change

I don't understand this. Why do you need MySslStream?

[eaufavor]

This just an artificial example, say, I want my custom stream struct to log the TCP handshake time.

MyStream<S> {
  tcp_handshaket_time: Duration,
  MySslStream<S>
}

enum MySslStream<S> {
   PreConnect((Ssl, S))
   MidHandshake(MidHandshakeSslStream<S>)
   Connected<Ssltream<S>>
}

vs

MyStream<S> {
  tcp_handshaket_time: Duration,
  SslStream<S>
}

It is just very annoying that I cannot have a single object to store the ssl stream before and after TLS handshake.

The point I try to make is that the current interface is unnecessarily complicated for some use case, which can be greatly simplified with the APIs in this PR.

[nox]

Wouldn't you store the TCP handshake time in the inner S of SslStream<S>, thus completely avoiding that specific issue? Why hoist it in your own MySslStream<S> wrapper instead?

[eaufavor]

Maybe that is just a bad example. Maybe I have something that doesn't belong to S, say the TLS handshake time or maybe some preferences/settings I'd like to store for the TLS handshake itself. The goal of this PR is not about enabling certain things that is impossible to do without it. The goal is to provide a style of API interaction that is more familiar to openssl C users and openssl-rs users.